PHPUnit & Pest Test Explorer installs statistics

PHPUnit & Pest Test Explorer for VS Code

繁體中文

Run PHPUnit and Pest tests directly in VS Code using the native Test Explorer UI.

Quick Start

1. Install the extension from the VS Code Marketplace 2. Open a PHP project that contains a phpunit.xml or phpunit.xml.dist 3. Tests appear automatically in the Test Explorer sidebar — click to run

PHPUnit and Pest are auto-detected from vendor/bin. No configuration needed in most projects.

Features

• Test Explorer integration — discover, run, and debug tests from the sidebar • PHPUnit 7 – 12 & Pest 1 – 4 — broad version support • Auto-detect binary — reads composer.json to use vendor/bin/pest for Pest projects automatically • Auto-reload — reloads all tests when phpunit.xml or composer.lock changes • Colored output — syntax-highlighted results with embedded PHP source snippets • Clickable stack traces — jump to file:line directly from error output • Remote environments — Docker, SSH, Laravel Sail, DDEV via custom commands • Multi-workspace Docker — single shared container for multiple workspace folders • Parallel execution — ParaTest support • Xdebug debugging — step-through debugging with one click • Continuous runs — auto-run tests on file changes

Settings

Add to .vscode/settings.json. All settings use the phpunit.* prefix.

Configuration Examples

Local

For most local projects, zero configuration is needed. To use a different test runner:

Docker

When running tests inside a Docker container, you need two things:

1. phpunit.command — tells the extension how to execute commands in the container 2. phpunit.paths — maps your local file paths to container paths so the extension can locate test files and parse error output

Important: ${workspaceFolder} may not resolve correctly on macOS or WSL. If you encounter path issues, replace it with the actual absolute path (e.g. /home/user/myproject).

docker exec (existing container):

docker run (ephemeral container):

Docker Compose:

If your docker-compose.yml is not in the workspace root, use the -f flag:

Docker Multi-Workspace

When using a multi-root workspace with a single shared Docker container, use ${workspaceFolderBasename} to switch directories per folder:

Each project folder is mounted separately in the container under its basename:

The command cd /${workspaceFolderBasename} switches into the correct directory before running tests. Each folder should have its own phpunit.xml — the extension auto-detects it. Do not set --configuration with an absolute container path at workspace level (e.g. --configuration=/project-a/phpunit.xml), as this causes every folder to load the same config and discover duplicate tests.

Laravel Sail

SSH

DDEV

WSL + Docker

When using Docker from a WSL workspace, use the full WSL path as the local key:

Debugging with Xdebug

1. Add a launch configuration to .vscode/launch.json:

2. Set the configuration name in settings:

3. Click the Debug Test button in the Test Explorer.

Using xdebug.start_with_request=trigger in Docker:

Breakpoints not hit? Check that: • Xdebug is configured with xdebug.mode=debug and xdebug.start_with_request=yes (or trigger) • phpunit.debuggerConfig matches the exact name in launch.json • pathMappings in launch.json correctly maps container paths to local paths • The Xdebug port is not blocked by a firewall

Commands

| Command | Description | Keybinding |

| phpunit.reload | Reload tests | — | | phpunit.run-all | Run all tests | Cmd+T Cmd+S | | phpunit.run-file | Run tests in current file | Cmd+T Cmd+F | | phpunit.run-test-at-cursor | Run test at cursor | Cmd+T Cmd+T | | phpunit.run-by-group | Run tests by group | — | | phpunit.rerun | Repeat last test run | Cmd+T Cmd+L |

Keybinding Tips

Use VS Code's runCommands to combine opening the Test Results panel with running tests in a single shortcut:

Troubleshooting

${workspaceFolder} resolves to /

On some systems (macOS, WSL), ${workspaceFolder} may not resolve correctly. Replace it with the actual absolute path in phpunit.paths:

spawn ${php} ENOENT

Usually caused by another extension (e.g. DEVSENSE PHP Tools) injecting ${php} as a literal variable. Fix:

If that doesn't help, disable conflicting PHP extensions, then re-enable PHPUnit Test Explorer first.

Paths with spaces cause errors

Ensure your phpunit.command template quotes the variables (this is the default):

Test Results panel does not open automatically after a failure

By default VS Code does not automatically reveal the Test Results panel. To open it whenever a test fails (useful for inspecting dd() output or error messages):

Other values: "openOnTestStart" (open as soon as a run starts), "neverOpen" (never open automatically).

Note: dd() output appears in the Test Results panel as raw output, since it causes the PHP process to exit before producing any structured test results.

Duplicate tests in multi-root workspace

If the same tests appear under multiple workspace folders, check your phpunit.args setting. A --configuration flag pointing to an absolute container path (e.g. --configuration=/var/www/project-a/phpunit.xml) at workspace level causes every folder to load the same phpunit.xml.

Fix: Remove --configuration from phpunit.args and let each folder auto-detect its own phpunit.xml. See the Docker Multi-Workspace section for the correct setup.

Contributing

Found a bug? Have an idea? We welcome contributions!

• Report a bug • Request a feature • Development guide

License

MIT

Description from the VS Code Marketplace listing.