Test Explorer#

The Test Explorer view enables the visual execution and debugging of PHPUnit tests. The tests are executed by the PHPUnit and the results are displayed in the Test Explorer, as shown in the next figure. The PHPUnit output is shown in the PHP (PHPUnit) output tab.

Each test is listed in the Test Explorer view. In the code, tests are annotated with the test icon. The icon shows the current test status, and allows to quickly Run, and Debug the test.

Configuration#

It is necessary to configure the editor before the tests can be executed. The process requires PHP (php), the PHPUnit package (phpunit/phpunit) and a PHPUnit configuration file (phpunit.xml (.dist)).

Tests are resolved quickly by parsing the phpunit.xml or phpunit.xml.dist files, and corresponding .php files in the workspace. Any changes to those files will automatically update the Test Explorer as well.

PHP#

Running the tests relies on the configured PHP executable. See Selecting PHP Executable for more details.

PHPUnit#

The PHPUnit phar file or PHPUnit composer package are necessary to execute the tests. PHPUnit Test Explorer uses the following PHPUnit:

1. From the vendor directory, usually created by composer.
2. Otherwise the PHPUnit PHAR (version 6.5.12.) bundled with PHP Tools.

In case there is the phpunit/phpunit composer package, it is used implicitly for the tests execution.

To manually specify path to the phpunit binary, use setting phpunit.phpunit. Example setting:

{
    "phpunit.phpunit" : "${workspaceFolder}/phpunit"
}

If none of the above is found, bundled PHPUnit PHAR (version 6.5.12.) is used.

Custom Command#

Running PHPUnit can be customized using the setting "phpunit.command".

Default value: "\"${php}\" ${phpargs} \"${phpunit}\" ${phpunitargs}"

The string command can have the following variables:

${phpunit} - will be replaced with phpunit binary path. ${phpunitxml} - will be path to corresponding phpunit.xml. ${phpunitargs} - the arguments we provide, including generated filters for executing specific tests or groups. ${php} - resolved path to php executable. ${phpargs} - the default arguments for php we provide. ${cwd} - current working directory.

See the VSCode's Output > PHP (PHPUnit) tab for details.

Configuration File#

The tests rely on the phpunit.xml or phpunit.xml.dist configuration files (PHPUnit configuration), which should be placed in the root of the workspace.

Tests#

The name, location, extension and settings of the tests are defined in the phpunit.xml configuration file. The tests should be located in a sub-directory, not directly in the workspace root, because PHPUnit does not recognize them there.

Test Explorer View#

Test Explorer View provides tools for manual and automatic test execution with visual representation of the results. The view is only visible if there are some tests or the phpunit.xml configuration file in the workspace.

Debugging Tests#

Tests can be debugged with Xdebug by clicking the bug-like icon in the Test Explorer view, or Debug Test command in the test margin. The debugging process is the same as standard debugging. The Test Explorer can debug one or more tests at once.

Custom Debug Launch Profile#

Specify a new "php" or "phpunit" launch profile in .vscode/launch.json file, and use it for debugging tests in Test Explorer.

Example launch.json file:

{
    "configurations": [
        {
            "name": "Debug With Mapping",
            "type": "php",
            "request": "launch",
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "ignoreExceptions": ["NotSupported*"]
        }
    ]
}

Notes:

• the profile must have "name"
• "type" must be either "php" or "phpunit"
• there must not be "program" property

The custom (launch.json) profile will be listed in Test Explorer, under Debug menu:

Profiling Tests#

Use the Debug menu in Test Explorer to Profile tests, or profile a single test with right click on the test -> Debug with Profile -> Profile.

Browse through the profiling results which open after the session ends:

While the profiling results are still opened, see the hot paths in your code:

Notes:

• Xdebug PHP extension needs to be properly installed
• Profiler VSCode extension needs to be installed.
• See profiling for more details.

Test Results#

Test results are displayed:

• the Test Explorer view shows small icons next to each test and the test run duration. The icons meaning is:
• - The test was executed without errors.
• - The test was executed with errors; the error message is in the output tab.
• - The test was executed and skipped (see incomplete-and-skipped-tests).
• - Test is currently running (this is shown usually during debugging).
• the icon next to each test right in the code shows icon with the last test result as well.
• failures are displayed inline, right on the failed assertion:

The actual result of the PHPUnit execution is displayed in the PHP (PHPUnit) output tab, while each test has its own output available by clicking on the test in the Test Explorer View.