skip to content

Configuration & Coverage

2 roadmaps5 questions

phpunit.xml declares test suites, the bootstrap script, the <source> directories and strictness flags, and coverage runs through PCOV or Xdebug. Interviewers probe risky tests and reports.

on this pageshow

explore

questions

5

In a PHPUnit 13 phpunit.xml, what do the <testsuites> element, the bootstrap attribute and the <source> element each configure?

level: juniorimportance: must knowfreq 50%

answer

  1. which tests, what runs first, which code is yours
  2. directory suffix defaults to Test.php
  3. bootstrap is included once, usually vendor/autoload.php
  4. no <source>, no coverage
  5. phpunit.xml before phpunit.dist.xml

basics

~10 s

<testsuites> names sets of test directories or files; bootstrap names a PHP script, usually vendor/autoload.php, included once before tests load; <source> declares your first-party code, which coverage and issue reporting are scoped to.

solid answer

~40 s

`<testsuites>` holds named `<testsuite>` elements listing `<directory>` and `<file>` entries (a directory picks up files ending in `Test.php` by default) plus `<exclude>` paths; `--testsuite unit` runs one of them. The root `bootstrap` attribute names a script PHPUnit includes once before loading tests - normally `vendor/autoload.php`, or a small file that requires it and sets up the environment; an exception there aborts the run with "Error in bootstrap script". `<source>` declares first-party code with `<include>` and `<exclude>` directories: it is the filter for code coverage (without it PHPUnit warns "No filter is configured, code coverage will not be processed") and it scopes deprecation, notice and warning reporting. PHPUnit looks for `phpunit.xml`, then `phpunit.dist.xml`, then `phpunit.xml.dist` in the working directory.

code

xml · 23 lines
xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         cacheDirectory=".phpunit.cache">
    <testsuites>
        <testsuite name="unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="integration">
            <directory>tests/Integration</directory>
        </testsuite>
    </testsuites>

    <source>
        <include>
            <directory>src</directory>
        </include>
        <exclude>
            <directory>src/Legacy/Generated</directory>
        </exclude>
    </source>
</phpunit>

go deeper

for a junior

Recall the three roles: <testsuites> picks the tests, bootstrap loads the autoloader first, <source> marks your own code for coverage.

for a middle

Explain the Test.php suffix default, per-suite bootstrap, and why coverage is skipped with a warning when <source> is missing.

for a senior

Show how you structure suites and <source> for a legacy codebase so unit runs stay fast and coverage excludes generated or vendor code.

for a principal

Treat the configuration as a team contract: a committed dist file, local overrides, and suite boundaries that match how CI stages are split.

## The file and how PHPUnit finds it PHPUnit 13 reads its settings from an **XML configuration file**. Run without `-c`/`--configuration`, it looks in the current directory for `phpunit.xml`, then `phpunit.dist.xml`, then `phpunit.xml.dist`, and uses the first it finds. The usual convention is to commit a `.dist` file and let a developer override it locally with an untracked `phpunit.xml`. `vendor/bin/phpunit --generate-configuration` writes a starter file, and `--validate-configuration` checks one against the schema; a file that fails validation still runs, but PHPUnit emits a warning that results may not be as expected - a PHPUnit warning, so the run fails by default. Three parts of the file answer three questions: **which tests**, **what runs before them**, and **which code is yours**. ## `<testsuites>`: which tests A **test suite** is a named collection of test files. - `<directory>tests/Unit</directory>` collects every file under that path whose name ends in the `suffix` attribute, which defaults to `Test.php`; a `prefix` attribute exists too. - `<file>` adds a single file; `<exclude>` removes a path from the suite. - Several `<testsuite>` elements let you split fast unit tests from slow integration tests. On the command line `--testsuite unit` runs one, `--testsuite unit,integration` runs several, and `--exclude-testsuite` works the other way. The root `defaultTestSuite` attribute picks the suite used when none is named. ## The `bootstrap` attribute: what runs first `bootstrap="vendor/autoload.php"` tells PHPUnit to `include_once` that script before it loads any test class. Its job is to make classes loadable - Composer's autoloader - and optionally to prepare the process: environment variables, a default time zone, constants. - If the file is missing, PHPUnit stops with an error naming it. - If the script throws, PHPUnit aborts with "Error in bootstrap script" plus the exception and its trace. - A `<testsuite>` element can carry its own `bootstrap` attribute; that script is loaded only when the suite is selected, so integration-only setup does not slow unit runs. Keep the bootstrap small. Anything it does happens once per process and is shared by every test, so it is the wrong place for per-test fixtures. ## `<source>`: which code is yours `<source>` declares your **first-party code**: ```xml <source> <include><directory>src</directory></include> <exclude><directory>src/Legacy/Generated</directory></exclude> </source> ``` A `<directory>` here picks up files ending in `.php` by default. PHPUnit uses the declaration for two different jobs: 1. **Code coverage filter.** Only files in `<source>` appear in coverage reports. With no `<source>` at all PHPUnit emits a warning, "No filter is configured, code coverage will not be processed", and writes no report; if the paths match no files, it says so and again skips coverage. Uncovered files are listed at 0 % by default, because the coverage element's `includeUncoveredFiles` attribute defaults to true. 2. **Issue attribution.** Attributes such as `restrictNotices`, `restrictWarnings` and `ignoreIndirectDeprecations` use `<source>` to tell whether a notice or deprecation came from your code or from a dependency in `vendor/`. ## Putting it together | Element or attribute | Answers | Typical value | |---|---|---| | `<testsuites>` | Which test files run | `tests/Unit`, `tests/Integration` | | `bootstrap` | What is loaded before tests | `vendor/autoload.php` | | `<source>` | Which code is first-party | `src` | | `cacheDirectory` | Where run history and caches live | `.phpunit.cache` | ## A legacy project's first configuration When a legacy application arrives without any PHPUnit setup, the order of work matters. Start with one `unit` suite that only contains tests which need no database or network, a bootstrap that loads the autoloader and nothing else, and a `<source>` that points at the application code while excluding generated, vendored or template directories. Add the `integration` suite afterwards, with its own bootstrap for credentials and schema setup. This keeps the first CI job fast and green, and it makes every later step - stricter settings, coverage reports - a change to one well-understood file rather than a rewrite. ## Common mistakes 1. Leaving `<source>` out and wondering why `--coverage-html` produced nothing. 2. Naming test files `UserTests.php` or `user_test.php`: they do not end in `Test.php`, so the directory scan skips them silently. 3. Putting database seeding in the bootstrap, so it runs once for the whole process instead of once per test that needs it. 4. Pointing `<source>` at the project root, which drags `vendor/` and tests into coverage. 5. Keeping an old file whose coverage paths still live under the pre-`<source>` layout; `--migrate-configuration` rewrites older formats.

  • In PHPUnit 13, why is a file named InvoiceTests.php under tests/Unit never run?
    A `<directory>` inside `<testsuite>` only collects files ending in its `suffix`, which defaults to `Test.php`. `InvoiceTests.php` ends in `Tests.php`, so the scan skips it without any message. Rename the file, or add a `<file>` entry or a `suffix` that matches the project's convention.
  • With PHPUnit 13, when would you give a single <testsuite> its own bootstrap attribute?
    When one suite needs setup the others do not - for example integration tests that load database credentials or start a schema migration. The per-suite script is loaded only when that suite is selected, so `--testsuite unit` stays fast and free of integration dependencies. The root bootstrap still runs first.

saying these in an interview costs you the question

  • Thinks the bootstrap script runs before every test method
  • Believes coverage works without a <source> element
  • Assumes any PHP file under the test directory is collected
  • Points <source> at the project root including vendor/
  • Confuses <source> with the list of test directories
open as a page

With PHPUnit 13, how do --filter and --testsuite narrow a test run, and what pattern syntax does --filter accept?

level: middleimportance: should knowfreq 42%

basics

~10 s

--testsuite selects named suites from phpunit.xml; --filter selects individual tests by a case-insensitive regular expression matched against Class::method plus any data-set name, with shortcuts such as #2 or @name for data sets.

open as a page

With PHPUnit 13, what makes a test risky, and why does a run with risky tests still exit with code 0 unless failOnRisky is set?

level: middleimportance: should knowfreq 40%

basics

~20 s

A risky test passed but broke a rule PHPUnit checks, such as performing no assertions or printing output. Risky results are reported but do not fail the run by default, because failOnRisky defaults to false.

open as a page

In CI, how do you make PHPUnit 13 produce HTML and Clover coverage reports, and how do you choose between PCOV and Xdebug as the driver?

level: seniorimportance: should knowfreq 40%

basics

~20 s

Install a coverage driver - PCOV for fast line coverage, Xdebug in coverage mode for branch and path coverage - declare <source>, then pass --coverage-html and --coverage-clover or configure <coverage><report>. Without a driver PHPUnit warns and writes nothing.

open as a page

A PHPUnit 13 suite passes in default order but fails intermittently with executionOrder="random"; how do you reproduce the failure and find its cause?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Random order exposes tests that depend on state another test left behind. Take the Random Seed PHPUnit prints, replay it with --random-order-seed, find the test that runs earlier and leaks state, and make each test set up its own.

open as a page