PHPUnit Manual Sebastian Bergmann PHPUnit Manual Sebastian Bergmann Publication date Edition for PHPUnit 6.5. Updated on 2017-12-07. Copyright © 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 Sebastian Bergmann This work is licensed under the Creative Commons Attribution 3.0 Unported License. Table of Contents 1. Installing PHPUnit ..................................................................................................... 1 Requirements ........................................................................................................ 1 PHP Archive (PHAR) ............................................................................................ 1 Windows ..................................................................................................... 1 Verifying PHPUnit PHAR Releases ................................................................. 2 Composer ............................................................................................................. 4 Optional packages ................................................................................................. 4 2. Writing Tests for PHPUnit .......................................................................................... 5 Test Dependencies ................................................................................................. 5 Data Providers ...................................................................................................... 8 Testing Exceptions ............................................................................................... 12 Testing PHP Errors .............................................................................................. 14 Testing Output .................................................................................................... 15 Error output ........................................................................................................ 16 Edge cases ................................................................................................. 18 3. The Command-Line Test Runner ................................................................................ 20 Command-Line Options ........................................................................................ 20 4. Fixtures .................................................................................................................. 27 More setUp() than tearDown() ............................................................................... 29 Variations ........................................................................................................... 29 Sharing Fixture ................................................................................................... 29 Global State ........................................................................................................ 30 5. Organizing Tests ...................................................................................................... 33 Composing a Test Suite Using the Filesystem .......................................................... 33 Composing a Test Suite Using XML Configuration ................................................... 34 6. Risky Tests ............................................................................................................. 35 Useless Tests ...................................................................................................... 35 Unintentionally Covered Code ............................................................................... 35 Output During Test Execution ............................................................................... 35 Test Execution Timeout ........................................................................................ 35 Global State Manipulation ..................................................................................... 35 7. Incomplete and Skipped Tests .................................................................................... 36 Incomplete Tests ................................................................................................. 36 Skipping Tests .................................................................................................... 37 Skipping Tests using @requires ............................................................................. 38 8. Database Testing ...................................................................................................... 40 Supported Vendors for Database Testing ................................................................. 40 Difficulties in Database Testing ............................................................................. 40 The four stages of a database test ........................................................................... 41 1. Clean-Up Database ................................................................................... 41 2. Set up fixture .......................................................................................... 41 3–5. Run Test, Verify outcome and Teardown .................................................. 41 Configuration of a PHPUnit Database TestCase ........................................................ 42 Implementing getConnection() ....................................................................... 42 Implementing getDataSet() ............................................................................ 43 What about the Database Schema (DDL)? ....................................................... 43 Tip: Use your own Abstract Database TestCase ................................................ 43 Understanding DataSets and DataTables .................................................................. 45 Available Implementations ............................................................................ 45 Beware of Foreign Keys ............................................................................... 54 Implementing your own DataSets/DataTables ................................................... 54 The Connection API ............................................................................................ 55 Database Assertions API ....................................................................................... 56 Asserting the Row-Count of a Table ............................................................... 56 Asserting the State of a Table ........................................................................ 56 iii PHPUnit Manual Asserting the Result of a Query ..................................................................... 57 Asserting the State of Multiple Tables ............................................................. 58 Frequently Asked Questions .................................................................................. 59 Will PHPUnit (re-)create the database schema for each test? ............................... 59 Am I required to use PDO in my application for the Database Extension to work? .... 59 What can I do, when I get a “Too much Connections” Error? .............................. 59 How to handle NULL with Flat XML / CSV Datasets? ...................................... 59 9. Test Doubles ........................................................................................................... 60 Stubs ................................................................................................................. 60 Mock Objects ..................................................................................................... 65 Prophecy ............................................................................................................ 71 Mocking Traits and Abstract Classes ...................................................................... 71 Stubbing and Mocking Web Services ...................................................................... 72 Mocking the Filesystem ........................................................................................ 74 10. Testing Practices .................................................................................................... 77 During Development ............................................................................................ 77 During Debugging ............................................................................................... 77 11. Code Coverage Analysis .......................................................................................... 79 Software Metrics for Code Coverage ...................................................................... 79 Whitelisting Files ................................................................................................ 80 Ignoring Code Blocks ........................................................................................... 80 Specifying Covered Methods ................................................................................. 81 Edge Cases ......................................................................................................... 83 12. Other Uses for Tests ............................................................................................... 84 Agile Documentation ........................................................................................... 84 Cross-Team Tests ................................................................................................ 84 13. Logging ...............................................................................................................