CI coverage

Have GitHub Actions upload a coverage artifact on every push. verifAIed picks it up when the run finishes and refreshes the branch.

What verifAIed looks for

verifAIed reads one artifact from each workflow run. It must contain:

  • A coverage report at the artifact root: coverage.json from pytest-cov, coverage/coverage-final.json from vitest, or both. Only these JSON reports are accepted, not LCOV or XML.
  • junit.xml at the artifact root. It tells verifAIed which tests passed and which failed.

The artifact must be named coverage. To use another name, set Artifact name under Settings → Coverage on the repository's page. The two names must match exactly, including case.

- uses: actions/upload-artifact@v4
  with:
    name: coverage
    path: |
      coverage.json
      coverage/coverage-final.json
      junit.xml
    if-no-files-found: error

Upload the artifact even when tests fail (if: always()), so a red run still shows which tests failed.

Example workflows

Copy the one for your test runner into .github/workflows/, or let your agent write it during Set up.

Python: pytest and uv
Runs pytest with per-test coverage, then uploads coverage.json and junit.xml.
# Example GitHub Actions workflow for pytest and uv

name: Coverage

on:
  push:
    branches: [main]
  pull_request:

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - name: Install dependencies
        # Reads pyproject.toml + uv.lock; installs main + dev groups.
        run: uv sync --all-extras --dev
      - name: Run tests with coverage
        # --cov-context=test records which test touched which line
        # (collection only — see the coverage step below).
        # --junit-xml produces a junit.xml that verifAIed reads for
        # the tests panel (pass/fail + failure messages per function).
        run: uv run pytest --cov --cov-branch --cov-context=test --junit-xml=junit.xml
      - name: Emit coverage.json with per-test contexts
        # pytest-cov's --cov-report=json would emit coverage.json but
        # would NOT include the per-test contexts collected above.
        # Running `coverage json --show-contexts` ourselves is the
        # least-intrusive way to get them in — works regardless of
        # pyproject.toml / .coveragerc layout.
        if: always()
        run: uv run coverage json --show-contexts -o coverage.json
      - name: Upload coverage artifact
        # Upload even if the test step failed (e.g. coverage below
        # threshold) so verifAIed can still pick up the artifact.
        if: always()
        uses: actions/upload-artifact@v4
        with:
          # Must match the "Coverage artifact name" in verifAIed.
          name: coverage
          # Upload both files at the artifact root. verifAIed reads
          # coverage.json for line coverage and junit.xml for per-test
          # pass/fail on the function-detail page.
          path: |
            coverage.json
            junit.xml
          if-no-files-found: error
JavaScript and TypeScript: vitest
Runs vitest with the Istanbul provider, then uploads coverage-final.json and junit.xml.
# Example GitHub Actions workflow for vitest

name: Coverage

on:
  push:
    branches: [main]
  pull_request:

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - name: Install dependencies
        run: npm ci
      - name: Run tests with coverage
        # Requires @vitest/coverage-istanbul as a dev dependency. The
        # Istanbul provider applies source maps, so the report points at
        # your original .ts/.tsx files. The junit reporter produces the
        # junit.xml verifAIed reads for the failing-tests panel.
        if: always()
        run: npx vitest run --coverage --coverage.provider=istanbul --coverage.reporter=json --reporter=default --reporter=junit --outputFile.junit=junit.xml
      - name: Upload coverage artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          # Must match the "Coverage artifact name" in verifAIed.
          name: coverage
          path: |
            coverage/coverage-final.json
            junit.xml
          if-no-files-found: error

Python: include per-test data

Run pytest with --cov-context=test, then write the report with a second command:

coverage json --show-contexts -o coverage.json

The pytest flag collects which test ran which line, but it does not put that in the JSON report by itself. Without the second command, the list of tests on each function stays empty and the branch shows Needs attention. Setting show_contexts = true under [tool.coverage.json] in pyproject.toml does the same job.

JavaScript and TypeScript: use Istanbul

Use vitest's Istanbul provider, @vitest/coverage-istanbul. It applies source maps, so the report points at your original .ts and .tsx files. Do not use the v8 provider: its report is rejected.

Istanbul reports do not record which test ran which line, so a function's page cannot list its tests for JavaScript and TypeScript. Failing tests still come from junit.xml.

Tests in more than one job

If backend and frontend tests run in separate jobs, upload each job's files under its own name, then merge them into the one coverage artifact in a job that needs both:

coverage:
  needs: [backend, frontend]    # each uploads coverage-<name>
  if: always()
  runs-on: ubuntu-latest
  steps:
    - uses: actions/upload-artifact/merge@v4
      with:
        name: coverage
        pattern: coverage-*
        separate-directories: true  # keeps two junit.xml apart

If the artifact has no coverage for one of your languages, verifAIed reads that language from the commit's source and lists its functions as untested. Test files and generated files are skipped.

Upload from your machine instead

You do not need CI to use verifAIed. After a test run, upload the report from your working tree:

verifaied upload --junit junit.xml

The branch appears as a local branch, separate from the one CI reports on. To see what would be sent without sending it:

verifaied upload --dry-run

Only the files named in the coverage report are read and uploaded. Nothing else in the directory is sent. CLI commands lists the other options, and Repositories and branches explains local branches.