Unit Testing V - Testing in PhpStorm

Running Codeception unit tests inside the PhpStorm code editor

In the previous article in this series, we looked at running a simple unit test from the command line that tested the constructor of the User class. In this one we'll see how to run that test in the PhpStorm editor.

If you don't use PhpStorm, you can skip this article.

This article assumes that you have successfully installed Codeception (which installs PhpUnit) with Composer in your vendor directory, and created the unit test described in the previous articles. It's also critical that your project loads the vendor autoload file.

MODX logo

Running Tests in PhpStorm

In order to run tests in PhpStorm, you first need to set the PhpUnit configuration.

  1. In PhpStorm, go to File | Settings (or Ctrl-Alt-S)
  2. Expand the Languages & Frameworks section
  3. Expand the PhpUnit section
  4. Click on Test Frameworks
  5. There should be a PhpUnit configuration with a little PHP icon, if so click on that
  6. If it's not there, click on the + symbol and add it
  7. Check the "Use Composer autoload" radio button
  8. Put the path to autoload.php in the "Path to script" input (e.g., C:\xampp\htdocs\addons\vendor\autoload.php)
  9. Click on "Apply"
  10. As long as you're there, using the same method, create a Codeception configuration
  11. Put the path to Codeception in the "Path to Codeception executable" (e.g., C:\xampp\htdocs\addons\vendor\codeception\codeception\codecept)
  12. Click on the "Apply" button
  13. Click on the "OK" button

The user test file we created earlier will not run in PhpStorm at this point because it's a Codeception unit test rather than a PhpUnit test. It can be modified to run as a PhpUnit test, but I prefer to use Codeception for all tests, since it's the only way to run acceptance tests, and I don't like switching back and forth.

These steps should make your test file run as is.

  1. Load the test file T1_UserTest.php in the editor.
  2. In the PhpStorm top menu, click on "View" and make sure the "Toolbar" is checked so it will appear.
  3. Right click in your test file *outside of any function*. This is important because otherwise it will try to run just that function.
  4. Select the Codeception option (the Codeception icon is the letter "C" with a checkmark inside it).
  5. The test will fail to run (it will tell you it couldn't find the configuration file), but you should see the name of your file in the toolbar at the top next to the Codeception icon.
  6. In the project tree at the left, right-click on the directory above the one with the .yml file (_build in our example). Select "Copy Path." That will put the path in the clipboard.
  7. In the toolbar, click on the filename dropdown showing the name of the file and the Codeception logo. In the dropdown menu that appears, click on "Edit Configurations".
  8. This should open a dialog to edit the Run/Debug Configuration for your test file.
  9. The "File" radio should be selected, and the path to the file should already be correct.
  10. In the "Custom working directory" input, paste the path to the directory above your codeception.yml file *with no slash at the end* (e.g., path/to/_build). You may need to add to the beginning of it to make it a full path.
  11. Click on the "Apply" button
  12. Click on the "OK" button

Your test should now run inside PhpStorm when you right-click *outside of any function* and select "run" with the Codeception option.

Subsequent runs can be executed just by clicking on the green triangle at the upper left of the debug console, or on the green triangle in the toolbar.

Important: if you switch to a different file in the editor, clicking on the green triangles will run the *previous* file, not the current one. The first run for a given file must be started by right-clicking in the file.

Another way to set the Run/Debug configuration is to click on the same dropdown and select the file from the list, but the list can get pretty long, so I prefer to just try to run the test. That will put the current file (or method) at the top, which makes things easier.

It's possible to run individual test methods (functions) within your file from inside PhpStorm by right-clicking inside them. At this writing, though, you need to create a Run/Debug configuration (exactly as we did above except that you right-click inside the method) for every method. Otherwise, you'll see this message when you try to run an individual test function:

Test framework quit unexpectedly
    Configuration file could not be found.
    Run `bootstrap` to initialize Codeception.

It can't find the configuration file because it's looking in the wrong working directory. Running bootstrap won't help at all. The name of the method you tried to run should be in the toolbar at the top, so you can create a run configuration for it the same way we did for the whole file earlier. Click on the down arrow, then on "Edit Configurations", then cut and paste the working directory from the whole file to this method.

In PhpStorm, the methods in a test file should inherit the run configuration from the file they are in, but at this point, they don't. I couldn't find any workaround. Still, if you're having trouble with a specific test, it's may be worth creating a Run/Debug configuration for it, especially if the methods that run ahead of it are time-consuming. This assumes that your tests are independent of each other (as they should be) and don't depend on a previous test having been run.

Run/Debug Configuration for Future Tests

For future tests, you can follow the steps above, or you can click on the name of the current file in the drop-down menu in the toolbar and select "Edit Configurations" in the dialog that appears. Select a file previous test file in the same project that works (still in the dialog) and copy the working directory path. Then click on the current file in the dialog and paste that path into the "Custom Working Directory" input. Click "Apply" and "OK." You may also want to click on the drop-down again, select your test file, and save the configuration. PhpStorm remembers recent configurations, but there's a limit to how many it will remember. The saved configurations will always be available.


Configuring a debugger in PhpStorm is beyond the scope of this article, but it's tremendously valuable when a test is passing that shouldn't or vice versa. It can save a lot of trial and error to be able to step through the test and examine the variables and code as it executes.

I've had to do this debugger configuration a number of times, and it's almost never as easy as they make it sound in the docs, though the process is a lot easier than it used to be. Once it's configured properly, it's a dream to use. You just set one or more breakpoints (by clicking in the left margin next to the line of code where you want the debugger to stop — you'll see a red dot appear), and then launch the debug run by right-clicking anywhere in the code and selecting the "Debug ... " option.

There are two steps to using the debugger in PhpStorm. First, you must have or install the debugger (e.g., Xdebug) and enable it in your php.ini file. Second, you have to configure the debugger in the PhpStorm's settings.

Repeating a Debugging Run

Once you've done a debug run by right-clicking in the file, subsequent runs can be executed just by clicking on the green bug at the upper left of the debug console, or on the green bug in the toolbar.

Important: if you switch to a different file in the editor, clicking on either of the green bugs will start a debug run of the *previous* file not the current one. The first run for a given file must be started by right-clicking in the file.

Coming Up

In the next article in this series, we'll get back to our User class and do some minimal validation on our User class fields.

For more information on how to use MODX to create a website, see my website Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (0)

Please login to comment.