How to run PHPUnit tests in Symfony

Automated tests let a Symfony project check application code before a change reaches a shared branch or deployment. PHPUnit is the test runner Symfony uses for unit, integration, and application tests, and the project-level wrapper reads the same configuration that CI jobs usually call.

Symfony Flex creates bin/phpunit, phpunit.dist.xml, and tests/bootstrap.php when the test packages are installed. The wrapper runs PHPUnit from the project dependencies, loads the test environment, and discovers test classes under tests/.

Use the project root as the working directory so PHPUnit can find the Symfony bootstrap and configuration file. A passing run ends with OK and returns exit code 0; failures, errors, warnings configured as failures, or missing tests return a nonzero status for CI and deployment gates.

1. Open a terminal in the Symfony project root.

   If bin/phpunit is missing in a new project, install the Symfony test pack with composer require --dev symfony/test-pack before running the suite.

2. Run the full PHPUnit suite.

   $ php bin/phpunit
   PHPUnit 13.2.1 by Sebastian Bergmann and contributors.
   
   Runtime:       PHP 8.5.7
   Configuration: /srv/app/phpunit.dist.xml
   
   .                                                                   1 / 1 (100%)
   
   Time: 00:00.001, Memory: 18.00 MB
   
   OK (1 test, 1 assertion)

   phpunit.dist.xml controls bootstrap, test environment variables, and test suite discovery for the normal project run.

3. Run one test file when only one area changed.

   $ php bin/phpunit tests/Service/SluggerTest.php
   PHPUnit 13.2.1 by Sebastian Bergmann and contributors.
   
   Runtime:       PHP 8.5.7
   Configuration: /srv/app/phpunit.dist.xml
   
   .                                                                   1 / 1 (100%)
   
   Time: 00:00.001, Memory: 18.00 MB
   
   OK (1 test, 1 assertion)

   Symfony discovers test classes ending in Test under tests/. Pointing PHPUnit at a file narrows the run without changing the XML configuration.

4. Run one test method with --filter when a failure needs a smaller loop.

   $ php bin/phpunit --filter testSlugifiesText
   PHPUnit 13.2.1 by Sebastian Bergmann and contributors.
   
   Runtime:       PHP 8.5.7
   Configuration: /srv/app/phpunit.dist.xml
   
   .                                                                   1 / 1 (100%)
   
   Time: 00:00.002, Memory: 18.00 MB
   
   OK (1 test, 1 assertion)

   PHPUnit treats the filter value as a regular expression, so escape backslashes when filtering by a fully qualified class name.

5. Confirm the latest PHPUnit command returned success for scripts or CI.

   $ echo $?
   0

   Run the exit-status check immediately after PHPUnit. Another shell command replaces the saved status value.