# Add Test Coverage to CI for a Filament App

Yes. An agent turns on PCOV in your Filament app's test workflow, runs Pest with a coverage report, publishes it as an artifact and to Codecov, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-coverage-to-ci/filament/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the test setup before it adds a flag to it. In a Filament app shaped like filamentphp/demo, `composer.json` requires `php ^8.1`, `filament/filament ^5.0` and `laravel/framework ^12.0`, with `pestphp/pest ^3.0`, `phpunit/phpunit ^11.0`, `larastan/larastan ^3.1` and `laravel/pint` for development; the `test:pest` script runs `pest --parallel`, `test:phpstan` runs `phpstan analyse` at level 8 over `app/`, and `test` runs both. `phpunit.xml` declares one suite, `Filament`, over `tests/Filament`, and a `<source>` block that includes only `app/`, which is exactly what a coverage report measures. `tests/Pest.php` binds `RefreshDatabase` and an `actingAs` with a factory user to every test under `Filament`, and the suite is thirteen widget tests under `tests/Filament/Widgets/`, from `ShopKpisStatsTest.php` to `WorkforceInsightsStatsTest.php`, with no tests for the resources under `app/Filament/Resources/`.

`.github/workflows/tests.yml` runs on push and pull request with a pinned `actions/checkout`, a Composer cache keyed on `composer.lock`, `shivammathur/setup-php` at PHP 8.4 with `mbstring, pdo, pdo_sqlite` and `coverage: none`, `cp .env.example .env`, `composer install`, Node 20 with `npm ci` and `npm run build`, `php artisan key:generate`, `touch database/database.sqlite` and `composer test:pest`. Pest's documentation says coverage needs Xdebug 3 or PCOV, so the agent changes `coverage: none` to `coverage: pcov` in that job only; `phpstan.yml` keeps `none` because static analysis measures nothing.

The run itself gains a new Composer script, `test:coverage`, that runs Pest with `--coverage`, `--coverage-clover coverage.xml` and `--coverage-html coverage/`, and the workflow calls it in place of `test:pest`, so a developer can run the same command locally with PCOV installed. The agent tries the script with and without `--parallel` in the sandbox, because the merged report from the parallel runner is what has to be correct, and keeps whichever form produces a complete `coverage.xml`, saying which in the pull request. `coverage/` and `coverage.xml` go into `.gitignore` beside `.phpunit.result.cache`. The HTML report is uploaded with `actions/upload-artifact`, and `coverage.xml` goes to Codecov through `codecov/codecov-action@v5` with a `CODECOV_TOKEN` secret, written so a fork without the secret does not fail. No `--min` threshold is set on the first run, because the number is not known until the report exists.

In the sandbox the agent installs PHP 8.4 with PCOV, runs `composer install`, copies `.env.example`, generates the key, creates the SQLite file, runs `npm ci` and `npm run build` so the Vite manifest the panel needs exists, and runs the new coverage script. It pastes the summary Pest prints and names the directories under `app/` with no coverage, which in this layout is most of `app/Filament/Resources/`, since the only tests are for widgets.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add test coverage reporting to this Filament application's GitHub Actions workflow and open a pull request. Read composer.json, phpunit.xml, tests/Pest.php, the test files under tests/Filament, .github/workflows/tests.yml, .github/workflows/phpstan.yml, .env.example and .gitignore first. In tests.yml set coverage to pcov in the setup-php step and leave phpstan.yml at none. Add a test:coverage script to composer.json that runs Pest with --coverage, --coverage-clover coverage.xml and --coverage-html coverage/, try it with and without --parallel in the sandbox and keep the form that produces a complete clover file, and call it from the workflow in place of test:pest. Add coverage/ and coverage.xml to .gitignore. Upload the HTML report as a workflow artifact and coverage.xml with codecov/codecov-action@v5 using a CODECOV_TOKEN secret in a way that does not fail on forks. Set no minimum threshold yet. In the sandbox install PHP 8.4 with PCOV, run composer install, prepare .env, the key and the SQLite database, build the assets, run the coverage script, and paste the summary and the list of app/ directories with no coverage in the pull request. Change no test and no application code.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that touches `.github/workflows/tests.yml`, `composer.json` and `.gitignore`: the `pcov` driver in the PHP setup step, a `test:coverage` script, the coverage step in place of `test:pest`, an artifact upload and a Codecov upload. The description reproduces the summary Pest printed in the sandbox and lists the directories under `app/` that no test reaches.

The `tests` workflow runs on the pull request, so the first coverage report in CI is produced by the change that adds it, and the HTML artifact on that run is the first thing a reviewer opens. `phpstan.yml` and `format.yml` are unchanged.

A reviewer checks that the driver is `pcov` and not Xdebug, which would slow the job, that the report is scoped by the existing `<source>` block to `app/` so vendor code is not counted, that the Codecov step tolerates a missing token, and that the `--parallel` choice is stated. Then they merge and decide whether a `--min` gate comes next.

## Run it on every new Laravel repository

A team that wants a coverage number on every Laravel and Filament app sends one `POST /o/{org}/sessions` per repository with this prompt and the repository in `resources`. Each run reads its own workflow, so an app on Xdebug keeps it with `XDEBUG_MODE=coverage` and an app without a `<source>` block in `phpunit.xml` gets one added, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with `session_url` to read the pull request and the pasted summary from. A key keeps up to `max_concurrent` runs going, four unless raised (the ceiling is 100), so every Laravel repository in the batch can be posted together; the extra ones come back `202` with `status: "queued"` and begin, oldest first, when a slot frees.

## Why run it on Rush?

Turning on coverage in a Laravel workflow is one line in `setup-php` and a few flags, but whether the report is right depends on the driver, the parallel runner and the `<source>` scope, and the only way to know is to run it. In a Rush sandbox the agent installs PHP with PCOV, builds the assets the panel needs, runs Pest both ways and keeps the output, so the pull request shows the summary that the workflow will reproduce.

The report is also the map for the next job. With thirteen widget tests and none for the resources, the number is low and the list of untested directories is long; the agent reports both as measured, with no threshold invented, and the same request works unchanged on the next app.

## Frequently asked questions

### Why PCOV and not Xdebug?

Pest's documentation accepts either, and `setup-php` can install both. PCOV only collects line coverage and adds less overhead to the test run, which fits a workflow whose job is a report, not a debugger. An app that already has Xdebug keeps it with `XDEBUG_MODE=coverage`.

### Does coverage work with --parallel?

The agent runs the script both ways in the sandbox and keeps the form that produces a complete `coverage.xml`, and the pull request says which. If the parallel runner's merged report is complete, the workflow keeps the speed; if not, the coverage step runs without `--parallel` and `test:pest` stays parallel for local use.

### What is measured?

Only what `phpunit.xml` lists in its `<source>` block, which is `app/`. Filament's own code under `vendor/` and the generated assets are not counted, so the percentage is about your resources, pages and widgets.

### Can I fail the build under a threshold?

Yes, with Pest's `--min` once the first report exists. The agent does not set one, because the number before the first run is unknown, and the pull request names the flag for when you choose a value.

## More Filament jobs

- [Add a CSV Import to a Filament Resource](https://getrush.ai/run/add-csv-import/filament/)
- [Add Email Verification to a Filament Panel from a Linear Issue](https://getrush.ai/run/add-email-verification/filament/)
- [Add Internationalisation to a Filament Admin Panel from a Linear Issue](https://getrush.ai/run/add-i18n/filament/)

## The same job on other stacks

- [Add Test Coverage Reporting to a Flutter App's CI](https://getrush.ai/run/add-coverage-to-ci/flutter/)
- [Add Coverage Reporting to a GitHub Action's CI](https://getrush.ai/run/add-coverage-to-ci/github-actions/)
- [Add Test Coverage Reporting to Go CI](https://getrush.ai/run/add-coverage-to-ci/go/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
