/phpunit-test-workbench

An extension to integrate PHPUnit with the native Test Explorer functionality within VS Code. Zero configuration required for common environment setups.

Primary LanguageTypeScriptMIT LicenseMIT

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

    Group tests by test suite

    Filter tests by tags

    Group tests by test suite

    Display of failed tests

    Display of failed tests

    Debugging test scripts

    Debugging test scripts

    Execute tests via commands

    Execute tests via commands

    Release notes

    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