How to run PHPUnit tests in PhpStorm

Published: 5 Apr 2021
Written by: Chun Fei Lung

A tutorial for people who keep forgetting how to run PHPUnit tests using PhpStorm.

Testing may feel like a pointless exercise at first, but it helps you move a lot faster in the long run

PhpStorm comes with built-in support for PHPUnit, but it can be a bit of a hassle to set up – especially if it’s been a while since you last went through the whole process. This guide probably won’t fix that, but at least you’ll know how you can get it to work!

Before we start…

Make sure that:

you’ve created or checked out a Composer-based PHP project;
have installed its dependencies using composer install; and
have opened the project in PhpStorm.

Running tests from a terminal

This tutorial teaches you how to set up PHPUnit within PhpStorm.

But just to be clear, you don’t have to run tests via PhpStorm’s graphical user interface (GUI). You can also simply run the following command from your project directory by opening the Terminal view in PhpStorm or via a terminal emulator of your choice:

$ vendor/bin/phpunit
PHPUnit 9.5.4 by Sebastian Bergmann and contributors.

.                                                                   1 / 1 (100%)

Time: 00:00.004, Memory: 6.00 MB

OK (1 test, 1 assertion)

This lets you do anything that can also be done via the GUI, and more!

Many people prefer using the GUI however. This is perfectly fine: you should use whatever you feel most comfortable with!

Running tests from PhpStorm

First try to run the tests. You can run do this by right-clicking the tests/ directory (side note: or less commonly, src/), a test class or test method, and selecting the “Run” option.

A context menu that is displayed when you right-click in a class file.
The menu shows a menu option that lets you run the tests in this file.

If that works, this tutorial is not for you.

Otherwise, you may see a window that looks very similar to the one below. Press “Fix” to edit your project configuration.

PhpStorm shows the “Edit configuration” window. An error message explains
that the project does not have a default interpreter and tells you to
press the “Fix” button.

PhpStorm will show you a screen that lets you select a PHP language level and a CLI interpreter.

A window that lets you select a PHP language level and interpreter
for your project.

Select an appropriate PHP language level (e.g. 8.0) and the CLI interpreter that supports the chosen language level.

Skip to the end if you can select an appropriate CLI interpreter here. Otherwise, continue with the step below.

Configuring a CLI interpreter

Press the ellipsis button (…) to the right of the “CLI Interpreter” dropdown to add a new CLI interpreter. This opens a new window that lists all interpreters that have been added to your PhpStorm projects.

Press the plus button (+) to add a new CLI interpreter. PhpStorm will show you a list of available interpreters.

A window that shows all CLI interpreters. The plus button has been
pressed and shows a context menu that lets you select a new CLI
interpreter.

If your project runs inside a virtual machine (side note: This includes Docker and Vagrant), select the first option.

Otherwise select “Other Local…” if you have another PHP version installed on your local machine. This includes PHP versions that were installed via a package manager, like Homebrew.

A window in which we can create a new CLI interpreter. We have
provided /usr/local/bin/php as the path to the PHP executable.

The screenshot above shows what you see when you select “Other Local…”. This window lets you enter a descriptive name of your choosing and tell PhpStorm where it can find the PHP executable.

In this example I named it “Non-ancient PHP” and told PhpStorm that it’s located at /usr/local/bin/php.

Where is my PHP executable?

On Linux and macOS you can use which to see which PHP your system uses when you run php via a terminal:

$ which php
/usr/local/bin/php

Note that this is merely a symlink to the actual PHP executable. If you have multiple different PHP versions installed (e.g. 7.4 and 8.0) and need to switch between them regularly, you may want to create several CLI interpreters in PhpStorm and point them to the specific versions (e.g. /usr/local/Cellar/php/8.0.3/bin/php).

Docker users simply need to select the right image, or service if they use Docker Compose.

If you have entered a valid path to a PHP executable, PhpStorm will show the version number and whether the chosen PHP version includes a debugger.

Press “OK” to save your changes and return to the previous screen. Select your newly created CLI interpreter and press “OK” again.

We have selected the right PHP language level and CLI interpreter
for our project.

Wrapping up

We’re now back in the “Edit configuration” window, except this time we no longer see an error message that tells us we need to fix things.

Press the “Run” button near the bottom of the window to run the tests.

PhpStorm shows the “Edit configuration” window again, this time
without an error message.

If your project follows modern conventions, PhpStorm should be able to run your tests now!

Feel free to send me a message (side note: You can find my address on my GitHub profile) if you followed all the steps in this tutorial, but PhpStorm still refuses to run your tests.