PHPUnit Manual

Edition for PHPUnit 12.5. Updated on Dec 11, 2025.

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
  • Data Providers
  • Testing Output
  • Incomplete Tests
  • Skipping Tests
    • Skipping Tests using Attributes
  • Test Dependencies
  • Failure Output
    • Edge Cases
• 3. The Command-Line Test Runner
  • Outcome and Issues
  • Output
    • Versions and Configuration
    • Progress
    • Test Results
    • Summary
  • Command-Line Options
    • Configuration
    • Selection
    • Execution
    • Reporting
    • Logging
• 4. Organizing Tests
  • Composing a Test Suite Using the Filesystem
  • Composing a Test Suite Using XML Configuration
• 5. Fixtures
  • More setUp() than tearDown()
  • Sharing Fixture
  • Global State
• 6. Test Doubles
  • Test Stubs
    • Creating Test Stubs
    • Configuring Test Stubs
  • Mock Objects
    • Creating Mock Objects
    • Configuring Mock Objects
  • MockBuilder API
    • setConstructorArgs()
    • disableOriginalConstructor()
    • disableOriginalClone()
    • disableAutoReturnValueGeneration()
    • onlyMethods()
    • getMock()
    • Set-Hooked Properties
• 7. Code Coverage
  • Software Metrics for Code Coverage
  • Including Files
  • Targeting Units of Code
  • Ignoring Code Blocks
• 8. Risky Tests
  • Useless Tests
  • Unintentionally Covered Code
  • Output During Test Execution
  • Test Execution Timeout
  • Global State Manipulation
• 9. Error Handling
  • Limiting issues to “your code”
  • Ignoring issue suppression
  • Ignoring previously reported issues
  • Expecting Deprecations (E_USER_DEPRECATED)
  • Disabling PHPUnit’s error handler
• 10. Extending PHPUnit
  • Enhancing concrete test cases
  • Extracting abstract test cases
  • Extracting traits
  • Extending the Test Runner
    • Implementing an extension
    • 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()
    • assertArrayIsIdenticalToArrayOnlyConsideringListOfKeys()
    • assertArrayIsIdenticalToArrayIgnoringListOfKeys()
  • Equality
    • assertEquals()
    • assertEqualsCanonicalizing()
    • assertEqualsIgnoringCase()
    • assertEqualsWithDelta()
    • assertObjectEquals()
    • assertFileEquals()
    • 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()
    • assertMatchesRegularExpression()
    • assertStringMatchesFormat()
    • assertStringMatchesFormatFile()
    • assertFileMatchesFormat()
    • assertFileMatchesFormatFile()
    • assertStringEqualsFile()
  • JSON
    • assertJson()
    • assertJsonFileEqualsJsonFile()
    • assertJsonStringEqualsJsonFile()
    • assertJsonStringEqualsJsonString()
  • XML
    • assertXmlFileEqualsXmlFile()
    • assertXmlStringEqualsXmlFile()
    • assertXmlStringEqualsXmlString()
  • Filesystem
    • assertDirectoryExists()
    • assertDirectoryIsReadable()
    • assertDirectoryIsWritable()
    • assertFileExists()
    • assertFileIsReadable()
    • assertFileIsWritable()
    • assertIsReadable()
    • assertIsWritable()
  • Math
    • assertInfinite()
    • assertNan()
  • Constraints
    • assertThat()
• 2. Attributes
  • Test
  • AllowMockObjectsWithoutExpectations
  • DisableReturnValueGenerationForTestDoubles
  • DoesNotPerformAssertions
  • IgnoreDeprecations
  • WithoutErrorHandler
  • Code Coverage
    • CoversClass
    • CoversClassesThatImplementInterface
    • CoversClassesThatExtendClass
    • CoversTrait
    • CoversMethod
    • CoversFunction
    • CoversNothing
    • UsesClass
    • UsesClassesThatImplementInterface
    • UsesClassesThatExtendClass
    • UsesTrait
    • UsesMethod
    • UsesFunction
  • Data Provider
    • DataProvider
    • DataProviderExternal
    • 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
  • Skipping Tests
    • RequiresPhp
    • RequiresPhpExtension
    • RequiresSetting
    • RequiresPhpunit
    • RequiresPhpunitExtension
    • RequiresFunction
    • RequiresMethod
    • RequiresOperatingSystem
    • RequiresOperatingSystemFamily
    • RequiresEnvironmentVariable
• 3. Events
  • Application
  • TestRunner
  • TestSuite
  • Test
• 4. The XML Configuration File
  • The <phpunit> Element
    • The backupGlobals Attribute
    • The backupStaticProperties Attribute
    • The bootstrap Attribute
    • The cacheDirectory Attribute
    • The cacheResult Attribute
    • The colors Attribute
    • The columns Attribute
    • The controlGarbageCollector Attribute
    • The numberOfTestsBeforeGarbageCollection Attribute
    • The requireCoverageMetadata 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 failOnPhpunitDeprecation Attribute
    • The failOnNotice Attribute
    • The failOnSkipped Attribute
    • The failOnIncomplete Attribute
    • The beStrictAboutChangesToGlobalState Attribute
    • The beStrictAboutOutputDuringTests Attribute
    • The beStrictAboutTestsThatDoNotTestAnything Attribute
    • The beStrictAboutCoverageMetadata Attribute
    • The enforceTimeLimit Attribute
    • The defaultTimeLimit 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 displayDetailsOnTestsThatTriggerErrors Attribute
    • The displayDetailsOnTestsThatTriggerNotices Attribute
    • The displayDetailsOnTestsThatTriggerWarnings Attribute
    • The shortenArraysForExportThreshold 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 <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 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
• 5. Copyright