Testing with PHPUnit

Before you start

1. Make sure the PHP plugin is installed and enabled. The plugin is not bundled with IntelliJ IDEA, but it can be installed from the JetBrains plugin repository as described in Installing, Updating and Uninstalling Repository Plugins and Enabling and Disabling Plugins.
2. Make sure the PHP interpreter is configured in IntelliJ IDEA on the PHP page, as described in Configuring Local PHP Interpreters and Configuring Remote PHP Interpreters.

Where do I get PHPUnit from?

Option 1: Download phpunit.phar
Download phpunit.phar as described on PHPUnit Official website and save it on your computer:

• To get full coding assistance in addition to simply running PHPUnit tests, store phpunit.phar under the root of the project where PHPUnit will be later used.
• If you only need to run PHPUnit tests and you do not need any coding assistance, you can save phpunit.phar outside the project.

Option 2: Use Composer

1. On the context menu of composer.json, choose Composer | Manage Dependencies.
2. In the Manage Composer Dependencies Dialog that opens, select the phpunit/phpunit package from the Available Packages list, possibly using the search field. The list shows all the available packages, the packages that are already installed are marked with a tick.

   Choose the relevant version from the Version to install list.

3. If necessary, expand the Settings hidden area and specify the advanced installation options. In the Command line parameters text box, type the additional command line parameters. For example, to have the package added to the require-dev section of the composer.json file instead of the default require section, type --dev. For more information about using the Composer command line options during installation, refer to the Composer documentation.
4. Click Install.

How do I integrate PHPUnit with IntelliJ IDEA in a project?

Step 1: Choose the type of configuration for PHPUnit

Open the Settings / Preferences dialog by pressing Ctrl+Alt+S, or alternatively choose File | Settings on Windows and Linux or IntelliJ IDEA | Preferences on macOS. Expand the Languages and Frameworks node and select Test Frameworks under PHP.

On the Test Frameworks page that opens, click in the central pane and choose the configuration type from the list:

Step 2: Choose the PHP interpreter to use
To use PHPUnit with a remote PHP interpreter, choose one of the configurations from the dialog box that opens.

Step 3: Specify the PHPUnit installation type
In the right-hand pane, choose one of the methods:

• Option 1: Run PHPUnit downloaded via Composer
  Specify the path to the autoload.php file in the vendor folder. See PHPUnit Installation via Composer and Composer for details.
• Option 2: Run PHPUnit from phpunit.phar
  Download phpunit.phar, save the archive in the project root folder, and specify the path to it. When you click , IntelliJ IDEA detects and displays the PHPUnit version.
• Option 3: Run PHPUnit from PEAR
  Pear should be configured as an include path.

  The PHPUnit installation procedure depends on the operating system you use and your system settings. Please, refer to the PHPUnit installation instructions for information on installing and configuring this tool.

Step 4 (optional): Specify the default configuration file
In the Test Runner area, appoint the configuration XML file to use for launching and executing scenarios.
By default, PHPUnit looks for a phpunit.xml configuration file in the project root folder or in the config folder. You can appoint a custom configuration file.
You can also type the path to a bootstrap file to have PHP script always executed before launching tests. In the text box, specify the location of the script. Type the path manually or click and select the desired folder in the dialog that opens.

How do I generate a PHPUnit test for a class?

Step 1: Open the Create New PHP Test dialog

Do any of the following:

• On the main menu, choose File | New. Then, choose PHP Test | PHPUnit Test from the pop-up menu.
• In the Project tool window, press Alt+Insert or right-click the PHP class to be tested and choose New | PHP Test | PHPUnit Test.
• In the editor of the PHP class to be tested, position the caret inside the definition of the class. Then, choose Go To | Test on the context menu or press Ctrl+Shift+T and select Create New Test from the pop-up menu. This way, you can generate a test for a PHP class defined among several classes within a single PHP file.

The Create New PHP Test dialog opens:

Step 2: Configure test generation

In the Create New PHP Test dialog, specify the following:

1. The test file template, that is, the template based on which IntelliJ IDEA will generate the test class. Make sure that PHPUnit is selected in the Test file template list.
2. The fully qualified name of the class to be tested, this name will be used to propose the Test Class Name. To use completion, press Ctrl+Space.
3. The name of the test class. IntelliJ IDEA automatically composes the name from the production class name as follows: <production class>Test.php. The test class name is displayed in the Name text box of the Test Class area.
4. The folder for the test class. By default, it is the folder where the production class is stored. To specify a different folder, click next to the Directory text box and choose the relevant folder.
5. The production class methods to generate test method stubs for. In the Generate test methods for area, select the checkboxes next to the required production class methods. To include inherited methods from parent classes, select the Show inherited methods checkbox.

   IntelliJ IDEA will automatically compose the test methods' names as test<production method>. You can customize the code templates used for generating test method stubs on the Code tab of the File and Code Templates settings page.

6. When the test is ready, navigate back to the production class by choosing Navigate | Go to Test Subject. For details, see Navigating Between Test and Test Subject.

Step 3: Launch test generation
Check, accept, or update the predefined settings and click OK to initiate the test generation.

How do I generate a PHPUnit test method?

1. Open the required test class in the editor, position the cursor anywhere inside the class definition, and choose Generate on the context menu, then choose PHPUnit Test Method from the Generate pop-up list.

2. Set up the test fixture, that is, have IntelliJ IDEA generate stubs for the code that emulates the required environment before test start and returns the original environment after the test is over:

   On the context menu, choose Generate | Override Methods, then choose SetUp or TearDown in the Choose methods to override dialog that opens.

   For more details, see Fixtures on the PHPUnit Official website.

How do I run and debug PHPUnit tests?

You can run and debug single tests as well as tests from entire files and folders. IntelliJ IDEA creates a run/debug configuration with the default settings and a launches the tests. You can later save this configuration for further re-use.

Option 1: To run or debug a single test
Open the test file in the editor, right-click the call of the test and choose Run '<test_name>' or Debug '<test_name>' on the context menu.

Option 2: To run or debug tests from a file
In the Project view, select the file with the tests to run and choose Run '<file_name>' or Debug '<file_name>' on the context menu.

Option 3: To run or debug tests from a folder
In the Project view, select the folder with the tests to run and choose Run '<folder_name>' or Debug '<folder_name>' on the context menu.

Option 4: To save an automatically generated default configuration
After a test session is over, choose Save <default_test_configuration_name> on the context menu of the test, test file, or folder.

Option 5: To run or debug tests through a previously saved run/debug configuration
Choose the required PHPUnit configuration from the list on the tool bar and click or .

Option 6: To create a custom run/debug configuration

1. In the Project view, select the file or folder with the tests to run and choose Create run configuration on the context menu. Alternatively, choose Run | Edit Configurations on the main menu, then click and choose PHPUnit from the list.
2. In the Run/Debug Configuration: PHPUnit dialog that opens, specify the test scope and (optionally) test runner options.

How do I monitor test results?

IntelliJ IDEA shows the results of test execution in the Test Runner tab of the Run Tool Window. The tab is divided in 2 main areas. In the left-hand area you can drill down through all unit tests to see the succeeded and failed ones. In this area you can also filter tests and export results.
The right-hand area displays the raw PHPUnit output:

Use the context menu in the left-hand area to run specific tests or navigate to the source code:

How do I run PHPUnit tests automatically?

You can configure IntelliJ IDEA to re-run tests automatically when the affected code is changed. This option is configured per run/debug configuration and can be applied to a test, a test file, or a folder depending on the test scope specified in this run/debug configuration.

To configure re-running tests automatically

1. Run the tests.
2. In the Test Runner tab, press the toggle button on the toolbar:

   

3. Optionally, set the time delay for launching the tests upon the changes in the code: