Skip to end of metadata
Go to start of metadata


Debugging is often done on the application code itself. But it usually requires launching the entire application and performing certain actions to debug a given scenario. It's much more convenient to run a test and debug from there, as tests typically cover a single class, function or scenario.

Let's see how we can debug our PHPUnit and Behat tests using PhpStorm.


Be sure to check the other tutorials about debugging PHP code with PhpStorm to learn more, including troubleshooting tips and advanced debugging techniques.

Since this tutorial covers PHPUnit, read up on PHPUnit support in PhpStorm. If you prefer behaviour-driven development (BDD), read more about using Behat in PhpStorm.


To debug PHP code with PhpStorm, we will need Xdebug or Zend Debugger. Make sure either Xdebug or Zend Debugger are installed and configured with PhpStorm.

1. Create a Run/Debug Configuration

The first thing we'll need is a Run/Debug configuration to be able to run our tests. We can create such configuration manually, making it possible to specify a lot of additional options related to our tests and test runner. We can also generate a Run/Debug configuration to quickly get started.

 Manually creating a Run/Debug configuration for a test

Create a new Run/Debug configuration using the Run | Edit Configurations menu. Next, add a new configuration of the type PHPUnit (to run unit tests) or Behat (to run Behat scenarios) and provide the required parameters.

Click Save to store the Run/Debug configuration.


Read more about creating Run/Debug configurations for PHPUnit in this tutorial. We also have a tutorial about using Behat in PhpStorm that covers Run/Debug configurations.

 Generating a Run/Debug configuration for a test

We can let the IDE generate a Run/Debug configuration for a test. From the Project tool window, select a tests folder or a test class and use the Debug | <tests name> context menu. We can also open our test class or scenario in the editor and press Alt+Shift+F9 (Ctrl+Alt+D on Mac OS X) to run tests with the debugger enabled.

The IDE will launch the test(s) with the debugger enabled, and open the debugger tool window.


To debug just one individual test, use the Debug | <test method name> context menu on the test function.

2. Debug the Test

Before launching the debugger, set a breakpoint in the test code or in the code being tested by our test(s). We can also enable the Run | Break at first line in PHP scripts menu.

Next. select the correct Run/Debug configuration from the toolbar and click the "bug" icon to start the debugger. We can also use the Run | Debug menu or the Shift+F9 keyboard shortcut (Ctrl+D on Mac OS X). This will launch our test(s) with the debugger attached, and pauses execution at the first breakpoint.

We can now inspect variables and step through source code using the tools and techniques outlined in Using the PhpStorm Debugger.

(optional) Using zero-configuration debugging to debug PHPUnit or Behat tests

In addition to the workflow described above (using Run/Debug Configurations), zero-configuration approach can be also employed for PHPUnit or Behat tests debugging.

In this case, the debugging session will be started when the Run action (Run | Run or the Shift+F10 keyboard shortcut (Ctrl-R on Mac OS X)) is invoked (so invoking the Debug action as in Run/Debug Configurations workflow is not necessary).

To take advantage of zero-configuration debugging approach, the Start Listening for PHP Debug Connections button should be pressed (or Run | Start Listening for PHP Debug Connections action invoked):

In the meantime, the test (or test suite) Run/Debug Configuration should be configured with proper Environment Variables or Interpreter Options as described in Debugging PHP CLI scripts with PhpStorm tutorial:

(optional) Profiling Tests

We can analyze performance of our PHP code by profiling it. Profiling allows us to gather program execution statistics such as the names of functions executed, the number of times a function has been executed, how long a function took to execute, which other functions have been called into, and so on. This information can give us a hint on where our code can be improved.

To profile tests using PhpStorm, we'll have to enable profiler support and modify our Run/Debug configuration to collect profiling data. Check the following tutorials to learn about configuring the profiler and analyzing profiling results:

  • No labels