With unit testing, we can verify parts of our source code are working as expected. After we've changed our code or performed a refactoring, unit tests can tell us if the changes we did break existing functionality or not. Only when all the tests are "green" (all tests pass) can we be sure that we're not breaking the functionality of our code.
PhpStorm uses PHPUnit as the test runner, a widely used unit testing framework for PHP which provides a lot of features. Let's see how it integrates with PhpStorm.
1. Adding a unit test to a project
Adding unit tests to a project can be done in several ways. We can create a new file and select the PHPUnit | PHPUnit test file template. Another way to create a test for some specific class is to invoke use the Go to Test action (with Navigate | Go to Test or Cmd+Shift+T / Ctrl+Shift+T) and choose Create new test.
Either method for creating a new test will open Create New PHPUnit Test dialog, in which we can specify the name of the class to test, the name and namespace of the test class, and where the PHP file should be saved.
After clicking OK, a boilerplate unit test class will be generated.
2. Enabling PHPUnit for our project
As we can see from the generated class above, there is no autocompletion support yet and PhpStorm does not know about the PHPUnit_Framework_TestCase class PHPUnit provides. Why is that? Because we haven't enabled PHPUnit yet for our project. Let's do that.
We can reference PHPUnit in several ways, depending on preferences or project standards.
- One approach is to install PHPUnit using PEAR. By adding an external library we can load PHPUnit from PHP's include path.
- Another approach is installing PHPUnit via Composer in PhpStorm.
- Another approach is downloading PHPUnit as a PHAR file and loading the PHAR file in our unit test code.
For this tutorial, let's go with the last option and work with PHPUnit from a PHAR file. From the Project Settings | PHP | PHPUnit, we can specify how we want to load PHPUnit. The options presented are the same options as described above (include path, Composer or PHAR). We don't have to grab the phpunit.phar file from www.phpunit.de ourselves: we can let PhpStorm download it for us.
Optionally, we can also specify the path to a phpunit.xml configuration file, or the path to a bootstrap file (to run arbitrary PHP code before unit tests run).
After closing the settings, we now get full autocompletion support on all PHPUnit's classes and functions:
3. Creating a Run Configuration
In order to be able to run unit tests, we need to create a new Run Configuration. We can add one of the type PHPUnit and give it a name. Next, we can provide details such as which tests should be run (all tests in a directory, a specific test class or one specific test). Adding test runner arguments or PHP interpreter options is also supported. Let's go with all tests in the tests folder of our project.
4. Running unit tests
We are now able to run (or debug) our unit tests! It's very easy: just run the configuration we've just created. This will bring up a new tool window in which test results will be displayed.
The test results tool window is divided in 3 main areas: the left side allows us to filter tests or export results. The middle area shows us the raw PHPUnit output. In the right part, we can drill down through all unit tests and see which ones succeeded and which ones failed.
From the test results we can also use the context menu to perform several actions, such as running one specific test or navigating to the test source code.
Keep in mind that you can also debug unit tests, as well as use the techniques outlined in Profiling the Performance of PHP Applications to analyze the test run performance.