PHPUnit Test Workbench

An extension to integrate PHPUnit with the native Test Explorer functionality within VS Code. Zero configuration required for common environment setups (i.e. where php is in your environment path, and PHPUnit is installed via Composer or included as a PHAR library).

Overview animation

Features

Integrates with standard VS Code Test Explorer
Organise and run your tests:
- By namespace
- By test suite (as defined in your phpunit.xml configuration file)
- Simple list of files and methods
Filter and run your tests by test group annotations or attributes
Errors appear as a peek within the editor
History of test run results and execution times is maintained
Includes commands and hotkeys to allow quick running of test or test suites
Debug test scripts using your existing debug profiles

Requirements

PHP: Version 7+
PHPUnit: Version 9 & 10

To run tests with debugging:

XDebug: Version 3

To run test coverage, either:

XDebug: Version 3; or
PCOV: Version appropriate to your PHP binary

PHP binary and PHPUnit must be installed on the environment where the tests are being run.

If you are running in a Docker container, WSL or any other remote/virtual environment, this extension will work in conjunction with the Remote Development extension by Microsoft.

Commands

Command	ID	Description
PHPUnit: Run test method	`phpunit-test-workbench.runMethod`	If the cursor is located within a test method, execute only that test method.
PHPUnit: Run test class	`phpunit-test-workbench.runClass`	If the active editor is for a test class, execute all test methods within the class.
PHPUnit: Run test class with tag	`phpunit-test-workbench.runClassWithTag`	If the active editor is for a test class, execute all test methods within the class tagged with the selected group.
PHPUnit: Run test suite	`phpunit-test-workbench.runSuite`	Display a dialog allowing the user to select from the list of test suites found in configuration files. All test methods within the class will be executed.
PHPUnit: Run test suite with tag	`phpunit-test-workbench.runSuiteWithTag`	Display a dialog allowing the user to select from the list of test suites found in configuration files. All test methods tagged with the selected group within the test suite will be executed.
PHPUnit: Run all tests	`phpunit-test-workbench.runAll`	Run all tests identified in the Test Explorer.
PHPUnit: Run all tests with tag	`phpunit-test-workbench.runAll`	Run all tests identified in the Test Explorer tagged with the selected group.
PHPUnit: Debug test method	`phpunit-test-workbench.debugMethod`	If the cursor is located within a test method, execute only that test method using the debugger.
PHPUnit: Debug test class	`phpunit-test-workbench.debugClass`	If the active editor is for a test class, debug all test methods within the class.
PHPUnit: Debug test class with tag	`phpunit-test-workbench.debugClassWithTag`	If the active editor is for a test class, debug all test methods within the class tagged with the selected group.
PHPUnit: Debug test suite	`phpunit-test-workbench.debugSuite`	Display a dialog allowing the user to select from the list of test suites found in configuration files. All test methods within the test suite will be executed using the debugger.
PHPUnit: Debug test suite with tag	`phpunit-test-workbench.debugSuiteWithTag`	Display a dialog allowing the user to select from the list of test suites found in configuration files. All test methods tagged with the selected group within the suite will be executed using the debugger.
PHPUnit: Debug all tests	`phpunit-test-workbench.debugAll`	Debug all tests identified in the Test Explorer.
PHPUnit: Debug all tests with tag	`phpunit-test-workbench.debugAllWithTag`	Debug all tests identified in the Test Explorer tagged with the selected group.
PHPUnit: Re-execute last test run	`phpunit-test-workbench.rerunLastTestRun`	Re-run the most recent test run. This could be a regular run, a debug run, or a run including test coverage.

Configuration options

Option	Description
`log.level`	Control the level of information displayed in the output panel.
`log.autoDisplayOutput`	Control when to automatically display the Output panel showing log messages. Regardless of this setting, log output can always be viewed by opening the relevant Output panel manually.
`log.displayFailuresAsErrorsInCode`	If enabled, the failed assertion will be highlighted as an error in source code.
`php.binaryPath`	Path to the location of the PHP binary. If left blank, it will be assumed that `php` is available via the environment `$PATH` variable.
`phpunit.locatorPatternComposerJson`	The glob describing the location of your composer file (usually named `composer.json`). If left blank, PHPUnit Test Workbench will attempt to find a `composer.json` file in the root workspace folder. The default pattern is `composer.json`.
`phpunit.binaryPath`	Path to the location of the PHPUnit binary (either `phpunit` or `phpunit.phar`). If left blank, the following locations will be checked: Composer `vendor` directory `phpunit.phar` in the root of the current workspace directory If not found anywhere, it will be assumed that `phpunit.phar` is available via the environment `$PATH` variable.
`phpunit.locatorPatternConfigXml`	The glob describing the location of your configuration file (usually named `phpunit.xml`). The default pattern is `phpunit.xml`.
`phpunit.testDirectory`	Relative path from the workspace folder root to the directory where tests should be executed from (usually the `tests` folder).
`phpunit.testFileSuffix`	Suffix used to identify test files within the test directory. If left blank, PHPUnit default suffixes (`Test.php` and `.phpt`) will be used.
`phpunit.coverageDriver`	Code coverage driver that PHPUnit will use to generate code coverage statistics. Either PCOV or Xdebug must be selected to enable code coverage functionality.
`phpunit.coverageSourceDirectory`	Path to the folder containing source code that should be included in code coverage statistics. If left emtpy, PHPUnit Test Workbench will attempt to use `./src`, `./lib` or `./app` in that order. If none of these directories are found, the workspace root will be used (however, this is not recommended as it will include test files and vendor packages).
`phpunit.coverageOutputDirectory`	Path to the location where a generated code coverage file should be stored. If left empty, PHPUnit Test Workbench will attempt to save it to the system temporary directory.
`phpunit.testNamespacePrefix`	If using PSR-4 namespaces, use this setting to map your test namespace prefix to the test directory (as defined in the `phpunit-test-workbench.phpunit.testDirectory` setting). Default is blank - this assumes that either: Your `composer.json` file maps the namespaces for your test classes (recommended); or The folder structure inside your test directory matches the namespace structure exactly.
`phpunit.testOrganization`	Method used to organise and display tests in the Test Explorer: By file: Show as a flat list of files, with test methods as children By namespace: Hierarchical display, organized using the namespace structure (assumes compliance with PSR-4)
`phpunit.useTestSuiteDefinitions`	Use test suite definitions within your configuration file to locate and group tests in the Test Explorer. Note that using this option requires a valid PHPUnit configuration file to be found via the `phpunit.locatorPatternConfigXml` glob pattern. Test suite definitions in the configuration file will ignore the `phpunit.testDirectory` setting.
`xdebug.clientPort`	Default port to use for Xdebug connections, if a port is not defined in your selected debug launch configuration. Default is `9003`.
`xdebug.clientHost`	Default hostname to use for Xdebug connections, if a host is not defined in your selected debug launch configuration. Default is `localhost`.

Examples

Test organization

Test organisation example

Group tests by test suite

Filter tests by tags

Group tests by test suite

Display of failed tests

Debugging test scripts

Execute tests via commands

Release notes

v0.8.0 - 2024-09-06

NEW: Add support for stack traces on test failure messages (#105)

v0.7.4 - 2024-05-07

FIXED: Error peek not appearing on correct line when running Laravel v10.x tests (#101)

v0.7.3 - 2024-05-05

CHANGED: Shift peek for test failures to appear on the line where the test failure occurred (#98)

v0.7.2 - 2024-05-02

FIXED: Renaming a test class causes child methods to be "undetected" until full refresh of tests (#96)

v0.7.1 - 2024-05-01

FIXED: Debugging a test triggers code coverage (#94)

v0.7.0 - 2024-04-22

NEW: Add namespace / class / method icons to items in Test Explorer (#90)
NEW: Add new 'Rerun last test' command (#89)
NEW: Add test coverage run profile (#33)

v0.6.1 - 2024-02-26

FIXED: Pipe escaped characters still appearing in expected / actual result values (#87)

v0.6.0 - 2024-02-26

NEW: Add support for continuous run test profiles (#68)
NEW: Add indicator to status bar when test detection is running (#73)
CHANGED: Tidy up logging and test results messages (#81)
CHANGED: Refactored test output parsing (#82)
FIXED: File watcher not triggering for test file on change while in a remote Dev Container (#76)
FIXED: Prevent workspace scanning for test executing more than once at the same time (#86)

v0.5.0 - 2023-05-17

NEW: Use @testdox annotation as the label for test classes and methods (#60)
NEW: Add support for the @group annotation and attribute (and aliases) (#61)
NEW: Add commands for running tests with a specific flag (#69)
CHANGED: Add support for recording results for test methods using a data provider (#55)
FIXED: Fix build process so that php-parser dependency is packaged for node (#8)

v0.4.2 - 2023-03-29

FIXED: Namespace folder locations not being correctly identified on Remote Workspaces - for real this time (#58)

v0.4.1 - 2023-03-29

FIXED: Namespace folder locations not being correctly identified on Remote Workspaces (#58)

v0.4.0 - 2023-03-28

NEW: Add support for PHPUnit 10 (#49)
NEW: Add detection for namespaces mapped in composer.json (#50)
CHANGED: Refactor test file parsing to find additional test script edge cases (#54)
FIXED: Not all test results captured when executing against large test suites (#51)

v0.3.4 - 2022-12-12

FIXED: Editing an existing test script does not not update location of shifted class and function 'run' icons (#47)

v0.3.3 - 2022-12-05

FIXED: Missing commands for debugging tests (#45)

v0.3.2 - 2022-12-02

FIXED: New test added to Test Explorer on each keystroke instead of on file save (#42)
FIXED: All test files being reparsed whenever any single test file is saved (#43)

v0.3.1 - 2022-12-01

FIXED: Some test failures not correctly detected by results parser (#40)

v0.3.0 - 2022-11-28

NEW: Include pertinent information in recorded test run output (#34)
NEW: Add test debug run profile (#36)
NEW: Include summary of test run in output (#38)

v0.2.0 - 2022-10-19

NEW: Detect tests identified with the @tests docblock annotation (#21)
NEW: Setting to control when Output panel is displayed on test execution (#25)
NEW: Highlight lines within test methods where test failures occur (#26)
NEW: Wire up Test Explorer cancel button to actually cancel test run (#27)
FIXED: Test run icons offset by 1 line from class and method identifiers (#23)
FIXED: Output from Git editors being parsed for test cases (#31)

v0.1.3 - 2022-10-17

FIXED: Clicking the 'Run test' icon in a test class sometimes refreshes the Test Explorer instead of running the test (#19)
FIXED: Clicking 'Go to test' on a namespace in Test Explorer displays an error (#17)

v0.1.2 - 2022-10-15

FIXED: Build error where xml2js library was not referenced properly

v0.1.1 - 2022-10-15

FIXED: Commands not executing tests for specific classes or methods (#12)
Updated documentation to include example images

v0.1.0 - 2022-10-14

Initial release

PHPUnit Test Workbench

Andrew Patterson

PHPUnit Test Workbench

Features

Requirements

Commands

Configuration options

Examples

Test organization

Group tests by test suite

Filter tests by tags

Display of failed tests

Debugging test scripts

Execute tests via commands

Release notes

v0.8.0 - 2024-09-06

v0.7.4 - 2024-05-07

v0.7.3 - 2024-05-05

v0.7.2 - 2024-05-02

v0.7.1 - 2024-05-01

v0.7.0 - 2024-04-22

v0.6.1 - 2024-02-26

v0.6.0 - 2024-02-26

v0.5.0 - 2023-05-17

v0.4.2 - 2023-03-29

v0.4.1 - 2023-03-29

v0.4.0 - 2023-03-28

v0.3.4 - 2022-12-12

v0.3.3 - 2022-12-05

v0.3.2 - 2022-12-02

v0.3.1 - 2022-12-01

v0.3.0 - 2022-11-28

v0.2.0 - 2022-10-19

v0.1.3 - 2022-10-17

v0.1.2 - 2022-10-15

v0.1.1 - 2022-10-15

v0.1.0 - 2022-10-14