All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Write the missing tests.

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

The same job on other stacks

Keep reading