Pest

To use Captain with Pest, you need to configure your test suite to output test results to a file and then tell Captain where to find those test results.

Getting started

Captain supports Pest 3 and 4. This integration has been tested with Pest 3.0.0, 3.8.4, 4.0.0, and 4.7.8.

Pest can output JUnit XML results using --log-junit. Create a .captain/config.yml file in your repository root:

test-suites:
  your-project-pest:
    command: vendor/bin/pest --log-junit tmp/results.xml
    results:
      language: PHP
      framework: Pest
      path: tmp/results.xml

Use framework: Pest, not framework: PHPUnit, even though Pest uses PHPUnit internally.

You can change your-project-pest to any name you like, but we typically recommend using the name of your project followed by a dash followed by pest. The command is the command you already use to run your test suite. Captain will invoke this command to run your tests. The example above shows what you might use if you use vendor/bin/pest and want to store test results in tmp/results.xml.

Once Captain is configured, you can run captain run your-project-pest --print-summary. If you see your typical test output followed by a captain block like this:

--------------------------------------------------------------------------------
----------------------------------- Captain ------------------------------------
--------------------------------------------------------------------------------

then you've configured everything correctly! You can now supercharge your test framework's capabilities. See below for configuring each of Captain's features.

Identifying tests

Captain uses framework specific "identity recipes" to identify the tests in your suite. These recipes are order dependent components extracted from native test framework output.

We use this identity to track the executions of a test over the course of their lifetime in your suite. This enables us to do things like flake detection, quarantining, and retries.

Captain identifies each Pest test using both its physical file path and its description. Both must match; a description alone does not identify a test across files.

The description combines the JUnit class and test case name as class::name, including dataset text when present.

Pest 3 and 4 can report a file as tests/Feature/ExampleTest.php::description. Captain removes the ::description suffix from the file attribute, keeping the physical PHP file path separate from the test description. Use the file and description from Captain's parsed results when configuring quarantines.

Switching from PHPUnit results

Changing only the framework label from PHPUnit to Pest preserves test identity when the identity fields are unchanged. However, the Pest parser normalizes a previously reported file.php::description to file.php, changing the file component of that identity. This normalization applies only to the Pest parser; the PHPUnit parser leaves these paths unchanged.

If your historical results contain these suffixed paths, new results will not automatically retain their flake or quarantine history. Existing quarantines may need to be recreated with the normalized file paths. Do not assume that historical results or quarantine settings will migrate automatically.

Quarantining tests

Captain makes managing flaky tests easier than ever. When a test is identified as flaky, you can quarantine the test without modifying it, so that if only those tests fail, Captain reports a success with a 0 exit code. Unlike skipped tests, quarantined tests will continue to run, so you can still view their failure messages and see how frequently they are failing.

In OSS mode, supply both identity fields:

captain add quarantine your-project-pest \
  --file tests/Feature/ExampleTest.php \
  --description 'Tests\Feature\ExampleTest::it returns a successful response'

Replace both values with the exact values from your results, including any absolute path or dataset text.

See the OSS quarantining guide for more information on managing quarantined tests in OSS mode.

Retrying tests

You can configure Captain to automatically retry failed tests to help you determine if failing tests are flaky or are genuinely failing. To configure retries, update your .captain/config.yml file like so:

test-suites:
  your-project-pest:
    command: vendor/bin/pest --log-junit tmp/results.xml
    results:
      language: PHP
      framework: Pest
      path: tmp/results.xml
    output:
      print-summary: true
    retries:
      attempts: 2
      command: vendor/bin/pest --log-junit tmp/results.xml --filter '{{ filter }}' '{{ file }}'

Keep both filter and file in the retry command so that tests with the same description in different files are not retried together. Keep --log-junit pointed at the configured results path so Captain can read the results of each retry.

Captain escapes and anchors test names in the filter, including punctuation and nested groups. Dataset selection depends on the Pest version:

• Pest 3: Captain retries all datasets of a failed parameterized test because Pest 3 cannot isolate the failed dataset through the filter.
• Pest 4: Captain retries only the failed datasets.

Once configured, Captain will invoke your original test command, check for any failures, and retry your tests however many times you've specified (in this example, two additional times) by templating the failures into the command specified by retries.command. The output.print-summary option is not required, but we've added it for convenience in understanding the overall results after the retries have been factored in.

Partitioning

Captain can optimally partition your test suite's files into multiple groups for execution on multiple CI nodes. Captain tracks your test file runtime so that it can balance each partition.

Configure partitioning in .captain/config.yml:

test-suites:
  your-project-pest:
    command: vendor/bin/pest --log-junit tmp/results.xml
    results:
      language: PHP
      framework: Pest
      path: tmp/results.xml
    partition:
      command: vendor/bin/pest --log-junit tmp/results.xml {{ testFiles }}
      globs:
        - 'tests/**/*Test.php'

Captain will fill in the testFiles placeholder of your partition.command with the files resulting from expanding your configured partition.globs.

Adjust the glob to match your test files, excluding bootstrap files such as tests/Pest.php. Partitioning distributes whole files, not individual tests within a file. Captain skips empty partitions without invoking Pest.

Run each partition in a separate CI job, using a different zero-based index:

captain run your-project-pest --partition-index 0 --partition-total 2
captain run your-project-pest --partition-index 1 --partition-total 2

See the CI platform guides for installing Captain and configuring your CI jobs.