PHPUnit Manual

Edition for PHPUnit 13.3. Updated on Aug 07, 2026.

Sebastian Bergmann

This work is licensed under the Creative Commons Attribution 3.0 Unported License.

Contents:

• 1. Installation
  • PHP on the Command-Line
    • Installing the PHP Command-Line Interpreter
    • Using the PHP Command-Line Interpreter
    • Configuring PHP for Development
  • Installing PHPUnit
    • PHP Archive (PHAR)
    • Composer
    • PHAR or Composer?
    • Global Installation
    • Web Server
• 2. Writing Tests for PHPUnit
  • Asserting return values
  • Expecting exceptions
  • Verifying side effects
  • Data Providers
  • Test Dependencies
  • Incomplete Tests
  • Skipping tests
    • Skipping tests using attributes
  • Testing output
    • Combining and repeating output expectations
  • Testing error log output
• 3. The Command-Line Test Runner
  • Running tests
    • PHPT tests
  • Selecting tests
    • Filtering by test name
    • Filtering by test suite
    • Filtering by group
    • Filtering by covered unit
    • Filtering by test ID
    • Listing tests
  • Outcome and Issues
  • Output
    • Runtime information
    • Progress
    • Test results
    • Summary
    • Alternative output formats
    • Controlling output
    • Interaction between output options
  • Exit codes
  • Stopping early
  • Logging
  • Test execution order
• 4. Organizing Tests
  • Composing a Test Suite Using the Filesystem
  • Composing a Test Suite Using XML Configuration
• 5. Fixtures
  • Template Methods
  • More setUp() than tearDown()
  • Pre-Conditions and Post-Conditions
  • Using Attributes Instead of Template Methods
  • Sharing Fixture
  • Global State
• 6. Test Doubles
  • Test Stubs
    • What are test stubs?
    • Common use cases
    • Reference
    • Return Value Generation
  • Mock Objects
    • What are mock objects?
    • Common use cases
    • Reference
  • Best Practices
    • Sealed Test Doubles
• 7. Code Coverage
  • Software Metrics for Code Coverage
  • Including Files
  • Targeting Units of Code
  • Ignoring Code Blocks
  • The Code Coverage Report in HTML Format
    • Filtering by Test Size
  • PHPCOV
    • Merging Code Coverage Data
    • Patch Coverage
  • Limitations
• 8. TestDox
  • Default Behaviour
    • Class Names
    • Method Names
    • Data Providers
  • Customizing Test Documentation
    • The TestDox Attribute
    • The TestDoxFormatter Attribute
    • The TestDoxFormatterExternal Attribute
  • TestDox Output
    • Console Output
    • Plain Text Output
    • HTML Output
    • XML Configuration
• 9. Risky Tests
  • Useless Tests
  • Unsealed Mock Objects
  • Unintentionally Covered Code
  • No Code Coverage Contribution
  • Output During Test Execution
  • Test Execution Timeout
  • Global State Manipulation
  • Leaked Error and Exception Handlers
  • Test Size Dependencies
• 10. Flaky Tests
  • Repeating Tests
    • Repeating Tests Using the Command Line
    • Repeating Tests Using the #[Repeat] Attribute
    • Failure Threshold
  • Retrying Tests
    • Retrying Tests Using the Command Line
    • Retrying Tests Using the #[Retry] Attribute
  • Combining Repeating and Retrying
  • Opting Individual Tests Out
  • Data Providers
  • PHPT Tests
• 11. Error Handling
  • Limiting issues to “your code”
  • Failing on deprecations based on how they are triggered
  • Ignoring issue suppression
  • Ignoring previously reported issues
  • Expecting Deprecations (E_USER_DEPRECATED)
  • Wrappers for trigger_error()
  • Custom Issue Trigger Resolvers
    • Implementing a custom resolver
    • Registering a custom resolver
  • Custom Deprecation Filters
    • Implementing a custom deprecation filter
    • Registering a custom deprecation filter
  • Errors (E_USER_ERROR)
  • Issues triggered outside of tests
  • Error handlers registered by tests
  • Disabling PHPUnit’s error handler
• 12. Extending PHPUnit
  • Enhancing concrete test cases
  • Extracting abstract test cases
  • Extracting traits
  • Implementing custom constraints
  • Implementing custom assertions
  • Implementing custom comparators
  • Implementing custom object exporters
  • Customizing test method invocation
  • Extending the Test Runner
    • Implementing an extension
    • A complete example: custom printer
    • Sharing an extension
    • Registering an extension
    • Debugging PHPUnit
  • Wrapping the Test Runner

Appendix

• 1. Assertions
  • Static vs. Non-Static Usage of Assertion Methods
  • Boolean
    • assertTrue()
    • assertFalse()
  • Identity
    • assertSame()
    • assertArraysAreIdentical()
    • assertArraysAreIdenticalIgnoringOrder()
    • assertArraysHaveIdenticalValues()
    • assertArraysHaveIdenticalValuesIgnoringOrder()
    • assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys()
    • assertArrayIsIdenticalToArrayIgnoringListOfKeys()
  • Equality
    • assertEquals()
    • assertEqualsCanonicalizing()
    • assertEqualsIgnoringCase()
    • assertEqualsWithDelta()
    • assertObjectEquals()
    • assertFileEquals()
    • assertFileEqualsFileIgnoringWhitespace()
    • assertArraysAreEqual()
    • assertArraysAreEqualIgnoringOrder()
    • assertArraysHaveEqualValues()
    • assertArraysHaveEqualValuesIgnoringOrder()
    • assertArrayIsEqualToArrayOnlyConsideringListOfKeys()
    • assertArrayIsEqualToArrayIgnoringListOfKeys()
  • Iterable
    • assertArrayHasKey()
    • assertContains()
    • assertContainsOnly()
    • assertContainsOnlyArray()
    • assertContainsOnlyBool()
    • assertContainsOnlyCallable()
    • assertContainsOnlyFloat()
    • assertContainsOnlyInt()
    • assertContainsOnlyIterable()
    • assertContainsOnlyNull()
    • assertContainsOnlyNumeric()
    • assertContainsOnlyObject()
    • assertContainsOnlyResource()
    • assertContainsOnlyClosedResource()
    • assertContainsOnlyScalar()
    • assertContainsOnlyString()
    • assertContainsOnlyInstancesOf()
  • Objects
    • assertObjectHasProperty()
  • Cardinality
    • assertCount()
    • assertSameSize()
    • assertEmpty()
    • assertGreaterThan()
    • assertGreaterThanOrEqual()
    • assertLessThan()
    • assertLessThanOrEqual()
  • Types
    • assertInstanceOf()
    • assertIsArray()
    • assertIsList()
    • assertIsBool()
    • assertIsCallable()
    • assertIsFloat()
    • assertIsInt()
    • assertIsIterable()
    • assertIsNumeric()
    • assertIsObject()
    • assertIsResource()
    • assertIsScalar()
    • assertIsString()
    • assertNull()
  • Strings
    • assertStringStartsWith()
    • assertStringEndsWith()
    • assertStringContainsString()
    • assertStringContainsStringIgnoringCase()
    • assertStringEqualsStringIgnoringLineEndings()
    • assertStringEqualsStringIgnoringWhitespace()
    • assertMatchesRegularExpression()
    • assertStringMatchesFormat()
    • assertStringMatchesFormatFile()
    • assertFileMatchesFormat()
    • assertFileMatchesFormatFile()
    • assertStringEqualsFile()
    • assertStringEqualsFileIgnoringWhitespace()
  • JSON
    • assertJson()
    • assertJsonFileEqualsJsonFile()
    • assertJsonStringEqualsJsonFile()
    • assertJsonStringEqualsJsonString()
  • XML
    • assertXmlFileEqualsXmlFile()
    • assertXmlStringEqualsXmlFile()
    • assertXmlStringEqualsXmlString()
    • assertXmlFileEqualsXmlFileConsideringComments()
    • assertXmlStringEqualsXmlFileConsideringComments()
    • assertXmlStringEqualsXmlStringConsideringComments()
  • Filesystem
    • assertDirectoryExists()
    • assertDirectoryIsReadable()
    • assertDirectoryIsWritable()
    • assertFileExists()
    • assertFileIsReadable()
    • assertFileIsWritable()
    • assertIsReadable()
    • assertIsWritable()
  • Math
    • assertInfinite()
    • assertNan()
  • Constraints
    • assertThat()
• 2. Attributes
  • Test
  • AllowMockObjectsWithoutExpectations
  • DisableReturnValueGenerationForTestDoubles
  • DoesNotPerformAssertions
  • IgnoreDeprecations
  • WithoutErrorHandler
  • IgnorePhpunitWarnings
  • Code Coverage
    • CoversClass
    • CoversClassesThatImplementInterface
    • CoversClassesThatExtendClass
    • CoversTrait
    • CoversMethod
    • CoversFunction
    • CoversNamespace
    • CoversFile
    • CoversDirectory
    • CoversDirectoryRecursively
    • CoversNothing
    • UsesClass
    • UsesClassesThatImplementInterface
    • UsesClassesThatExtendClass
    • UsesTrait
    • UsesMethod
    • UsesFunction
    • UsesNamespace
    • UsesFile
    • UsesDirectory
    • UsesDirectoryRecursively
  • Data Provider
    • DataProvider
    • DataProviderExternal
    • DataProviderClosure
    • TestWith
    • TestWithJson
  • Test Dependencies
    • Depends
    • DependsUsingDeepClone
    • DependsUsingShallowClone
    • DependsExternal
    • DependsExternalUsingDeepClone
    • DependsExternalUsingShallowClone
    • DependsOnClass
    • DependsOnClassUsingDeepClone
    • DependsOnClassUsingShallowClone
  • TestDox
    • TestDox
    • TestDoxFormatter
    • TestDoxFormatterExternal
  • Test Groups
    • Group
    • Small
    • Medium
    • Large
    • Ticket
  • Template Methods
    • BeforeClass
    • Before
    • PreCondition
    • PostCondition
    • After
    • AfterClass
  • Test Isolation
    • BackupGlobals
    • ExcludeGlobalVariableFromBackup
    • BackupStaticProperties
    • ExcludeStaticPropertyFromBackup
    • RunInSeparateProcess
    • RunTestsInSeparateProcesses
    • RunClassInSeparateProcess
    • PreserveGlobalState
    • WithEnvironmentVariable
  • Flaky Tests
    • Repeat
    • Retry
  • Skipping Tests
    • RequiresPhp
    • RequiresPhpExtension
    • RequiresSetting
    • RequiresPhpunit
    • RequiresPhpunitExtension
    • RequiresFunction
    • RequiresMethod
    • RequiresOperatingSystem
    • RequiresOperatingSystemFamily
    • RequiresEnvironmentVariable
• 3. Configuration
  • Configuration
  • Selection
  • Execution
  • Stopping on Issues
  • Failing on Issues
  • Reporting
  • Logging
  • Code Coverage
  • CLI-only Options
  • XML-only Settings
• 4. CLI Options
  • Configuration
  • Selection
  • Execution
  • Reporting
  • Logging
  • Code Coverage
  • Miscellaneous
• 5. XML Configuration File
  • The <phpunit> Element
    • The backupGlobals Attribute
    • The backupStaticProperties Attribute
    • The bootstrap Attribute
    • The cacheDirectory Attribute
    • The recordTestRunHistory Attribute
    • The colors Attribute
    • The columns Attribute
    • The controlGarbageCollector Attribute
    • The numberOfTestsBeforeGarbageCollection Attribute
    • The requireCoverageMetadata Attribute
    • The requireSealedMockObjects Attribute
    • The processIsolation Attribute
    • The stopOnDefect Attribute
    • The stopOnError Attribute
    • The stopOnFailure Attribute
    • The stopOnWarning Attribute
    • The stopOnRisky Attribute
    • The stopOnDeprecation Attribute
    • The stopOnNotice Attribute
    • The stopOnSkipped Attribute
    • The stopOnIncomplete Attribute
    • The failOnAllIssues Attribute
    • The failOnEmptyTestSuite Attribute
    • The failOnWarning Attribute
    • The failOnRisky Attribute
    • The failOnDeprecation Attribute
    • The failOnSelfDeprecation Attribute
    • The failOnDirectDeprecation Attribute
    • The failOnIndirectDeprecation Attribute
    • The failOnPhpunitDeprecation Attribute
    • The failOnPhpunitNotice Attribute
    • The failOnPhpunitWarning Attribute
    • The failOnNotice Attribute
    • The failOnSkipped Attribute
    • The failOnIncomplete Attribute
    • The beStrictAboutChangesToGlobalState Attribute
    • The beStrictAboutOutputDuringTests Attribute
    • The beStrictAboutTestsThatDoNotTestAnything Attribute
    • The beStrictAboutCoverageMetadata Attribute
    • The requireCoverageContribution Attribute
    • The enforceTimeLimit Attribute
    • The defaultTimeLimit Attribute
    • The diffContext Attribute
    • The timeoutForSmallTests Attribute
    • The timeoutForMediumTests Attribute
    • The timeoutForLargeTests Attribute
    • The defaultTestSuite Attribute
    • The stderr Attribute
    • The reverseDefectList Attribute
    • The registerMockObjectsFromTestArgumentsRecursively Attribute
    • The extensionsDirectory Attribute
    • The executionOrder Attribute
    • The resolveDependencies Attribute
    • The testdox Attribute
    • The testdoxSummary Attribute
    • The displayDetailsOnAllIssues Attribute
    • The displayDetailsOnIncompleteTests Attribute
    • The displayDetailsOnSkippedTests Attribute
    • The displayDetailsOnTestsThatTriggerDeprecations Attribute
    • The displayDetailsOnPhpunitDeprecations Attribute
    • The displayDetailsOnPhpunitNotices Attribute
    • The displayDetailsOnTestsThatTriggerErrors Attribute
    • The displayDetailsOnTestsThatTriggerNotices Attribute
    • The displayDetailsOnTestsThatTriggerWarnings Attribute
    • The shortenArraysForExportThreshold Attribute
    • The warnWhenPhpIsNotConfiguredForDevelopment Attribute
  • The <testsuites> Element
    • The <testsuite> Element
  • The <source> Element
    • The <include> Element
    • The <exclude> Element
    • The <directory> Element
    • The <file> Element
    • The <deprecationTrigger> Element
    • The <issueTriggerResolvers> Element
    • The <deprecationFilters> Element
    • The <identifyIssueTrigger> Attribute
    • The <ignoreSelfDeprecations> Attribute
    • The <ignoreDirectDeprecations> Attribute
    • The <ignoreIndirectDeprecations> Attribute
    • The <restrictNotices> Attribute
    • The <restrictWarnings> Attribute
    • The <baseline> Attribute
    • The <ignoreSuppressionOfDeprecations> Attribute
    • The <ignoreSuppressionOfPhpDeprecations> Attribute
    • The <ignoreSuppressionOfErrors> Attribute
    • The <ignoreSuppressionOfNotices> Attribute
    • The <ignoreSuppressionOfPhpNotices> Attribute
    • The <ignoreSuppressionOfWarnings> Attribute
    • The <ignoreSuppressionOfPhpWarnings> Attribute
  • The <coverage> Element
    • The includeUncoveredFiles Attribute
    • The ignoreDeprecatedCodeUnits Attribute
    • The pathCoverage Attribute
    • The driver Attribute
    • The disableCodeCoverageIgnore Attribute
    • The <report> Element
  • The <logging> Element
    • The <junit> Element
    • The <teamcity> Element
    • The <testdoxHtml> Element
    • The <testdoxText> Element
  • The <groups> Element
  • The <extensions> Element
    • The <bootstrap> Element
  • The <php> Element
    • The <includePath> Element
    • The <ini> Element
    • The <const> Element
    • The <var> Element
    • The <env> Element
    • The <get> Element
    • The <post> Element
    • The <cookie> Element
    • The <server> Element
    • The <files> Element
    • The <request> Element
• 6. Events
  • Application
  • TestRunner
  • TestSuite
  • Test
• 7. PHPT Tests
  • Anatomy of a PHPT Test
  • Running PHPT Tests
  • How a PHPT Test Is Executed
  • Sections
    • --TEST--
    • --FILE--, --FILEEOF--, --FILE_EXTERNAL--
    • --EXPECT--, --EXPECTF--, --EXPECTREGEX--
    • --ARGS--, --STDIN--
    • --INI--, --ENV--
    • --SKIPIF--
    • --XFAIL--
    • --CLEAN--
    • Ignored Sections
    • Unsupported Sections
  • Invalid PHPT Files
  • How Failures Are Reported
  • Code Coverage
  • Repeating and Retrying
  • When to Use PHPT
• 8. Copyright