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.

{
  // Path to the PHP binary (default: "php")
  "phpunit.php": "php",

  // Path to PHPUnit or Pest binary
  // Auto-detected from composer.json: uses "vendor/bin/pest" if pestphp/pest is a dependency,
  // otherwise defaults to "vendor/bin/phpunit". Only set this if auto-detection is not sufficient.
  "phpunit.phpunit": "vendor/bin/phpunit",

  // Custom command template
  // Variables: ${php}, ${phpargs}, ${phpunit}, ${phpunitargs}, ${phpunitxml}, ${cwd}
  //   ${workspaceFolder}         — absolute path to the workspace folder
  //   ${workspaceFolderBasename} — folder name only (e.g. "myproject")
  //   ${userHome}                — user home directory
  //   ${pathSeparator}           — OS path separator ("/" or "\")
  "phpunit.command": "\"${php}\" ${phpargs} \"${phpunit}\" ${phpunitargs}",

  // Extra arguments passed to PHPUnit
  "phpunit.args": [],

  // Path mappings for remote environments { "local/path": "remote/path" }
  "phpunit.paths": {},

  // Environment variables set before running
  "phpunit.environment": {},

  // Save all open files before running tests (default: false)
  "phpunit.saveBeforeTest": false,

  // Output format preset: "collision" (detailed per-test), "progress" (dot-progress), or "pretty" (per-test without icons)
  "phpunit.output.preset": "collision",

  // Override individual format fields from the preset (see phpunit package docs)
  "phpunit.output.format": {},

  // Clear debug output channel before each run (default: true)
  "phpunit.clearDebugOutputOnRun": true,

  // Control when Test Results panel opens automatically (VS Code built-in setting):
  // - "openOnTestStart"    — open as soon as a run starts
  // - "openOnTestFailure"  — open only when a test fails (useful for seeing dd() output)
  // - "neverOpen"          — never open automatically
  // "testing.openTesting": "openOnTestFailure"

  // launch.json configuration name for debugging
  "phpunit.debuggerConfig": "",

  // Xdebug port, 0 = random (default: 0)
  "phpunit.xdebugPort": 0
}

Configuration Examples

Local

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

// Pest
{ "phpunit.phpunit": "vendor/bin/pest" }

// Laravel Artisan
{ "phpunit.phpunit": "artisan test" }

// ParaTest (parallel execution)
{ "phpunit.phpunit": "vendor/bin/paratest" }

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):

{
  "phpunit.command": "docker exec -t my_container /bin/sh -c \"${php} ${phpargs} ${phpunit} ${phpunitargs}\"",
  "phpunit.paths": {
    "${workspaceFolder}": "/app"
  }
}

docker run (ephemeral container):

{
  "phpunit.command": "docker run --rm -t -v ${PWD}:/app -w /app php:latest ${php} ${phpargs} ${phpunit} ${phpunitargs}",
  "phpunit.paths": {
    "${workspaceFolder}": "/app"
  }
}

Docker Compose:

{
  "phpunit.command": "docker compose exec -t app /bin/sh -c \"${php} ${phpargs} ${phpunit} ${phpunitargs}\"",
  "phpunit.paths": {
    "${workspaceFolder}": "/app"
  }
}

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