unit-tests

Running Unit Tests

Preferred: Use the runTests tool

If the runTests tool is available, prefer it over running shell commands. It provides structured output with detailed pass/fail information and supports filtering by file and test name.

• Pass absolute paths to test files via the files parameter.
• Pass test names via the testNames parameter to filter which tests run.
• Set mode="coverage" to collect coverage.

The tool runs tests discovered by VS Code's registered test controllers; it does not compile the repository or invoke a shell test command. If discovery is unavailable, pending, or reports no executed tests, treat the request as unvalidated and use the repository's configured test command. Review per-file and test-name diagnostics for partially matched requests instead of repeatedly checking the same paths.

Example (conceptual): run tests in src/vs/editor/test/common/model/model.test.ts with test name filter "should split lines".

Fallback: Shell scripts

When the runTests tool is not available (e.g. in CLI environments), use the platform-appropriate script from the repo root:

• macOS / Linux: ./scripts/test.sh [options]
• Windows: .\scripts\test.bat [options]

These scripts download Electron if needed and launch the Mocha test runner.

Commonly used options

Bare file paths - Run tests from specific files

Pass source file paths directly as positional arguments. The test runner automatically treats bare .ts/.js positional arguments as --run values.

./scripts/test.sh src/vs/editor/test/common/model/model.test.ts

.\scripts\test.bat src\vs\editor\test\common\model\model.test.ts

Multiple files:

./scripts/test.sh src/vs/editor/test/common/model/model.test.ts src/vs/editor/test/common/core/range.test.ts

--run <file> - Run tests from a specific file (explicit form)

Accepts a source file path (starting with src/). The runner strips the src/ prefix and the .ts/.js extension automatically to resolve the compiled module.

./scripts/test.sh --run src/vs/editor/test/common/model/model.test.ts

Multiple files can be specified by repeating --run:

./scripts/test.sh --run src/vs/editor/test/common/model/model.test.ts --run src/vs/editor/test/common/core/range.test.ts

--grep <pattern> (aliases: -g, -f) - Filter tests by name

Runs only tests whose full title matches the pattern (passed to Mocha's --grep).

./scripts/test.sh --grep "should split lines"

Combine with --run to filter tests within a specific file:

./scripts/test.sh --run src/vs/editor/test/common/model/model.test.ts --grep "should split lines"

--runGlob <pattern> (aliases: --glob, --runGrep) - Run tests matching a glob

Runs all test files matching a glob pattern against the compiled output directory. Useful for running all tests under a feature area.

./scripts/test.sh --runGlob "**/editor/test/**/*.test.js"

Note: the glob runs against compiled .js files in the output directory, not source .ts files.

--coverage - Generate a coverage report

./scripts/test.sh --run src/vs/editor/test/common/model/model.test.ts --coverage

--timeout <ms> - Set test timeout

Override the default Mocha timeout for long-running tests.

./scripts/test.sh --run src/vs/editor/test/common/model/model.test.ts --timeout 10000

--workers <count> - Run test files in parallel processes

Spreads a run of all test files, or of the files of --runList, across <count> worker processes. The count is required, and capped at one worker per CPU and per 2 GB of memory, because every worker loads all test files of the run. Every worker loads all test files of the run and runs the files it claims, in the usual order. With --runList, it starts one worker per 75 of the listed test files that the runner runs, but at least 2, because one slow test file would otherwise hold up all the others, and never more than there are files. It is ignored, and the run uses a single window or process, with --run, --runGlob, bare file paths, --grep, --coverage or --dev. With --rerun-failed-files, the failures of all workers are rerun in a single window or process. When a worker fails, the runner prints the test files it ran, in order, to pass to --run to reproduce the failure. pnpm run test-node and pnpm run test-browser accept it as well; the browser runner starts its own browser in every worker, runs the browsers one at a time, and ignores it with --debug.

./scripts/test.sh --workers 4
./scripts/test.sh --workers 4 --runList .build/affected-tests.txt
pnpm run test-node --workers 4
pnpm run test-browser --browser chromium --workers 4

--isolate - Run every test file alone

Runs every test file of the run (--run, --runList, --runGlob or all) alone in a fresh window, as many at once as --workers allows, and fails when a file fails alone. A run of several files loads all of them before running any, so a test file can pass there only because another one registers what it reads (for example, a test file that imports a *.contribution.ts). In pull requests, the Linux Electron unit test job runs the selected test files that the pull request adds, changes or renames this way. Electron runner only; --tfs results are not written.

./scripts/test.sh --isolate --run src/vs/sessions/contrib/chatWindow/test/browser/chatEditor.test.ts
./scripts/test.sh --isolate --workers 4 --runList .build/affected-tests.txt

Integration tests

Integration tests (files ending in .integrationTest.ts or located in extensions/) are not run by scripts/test.sh. Use scripts/test-integration.sh (or scripts/test-integration.bat) instead. See the integration-tests skill for details.

Compilation requirement

Tests run against compiled JavaScript output. Reuse current output from an existing VS Code - Build task when available; otherwise refresh client output with pnpm run build-fast --client-only before running tests. This supports cold and incremental builds without a persistent watcher or extension builds. Use pnpm run build-fast when extension and Copilot outputs are also needed. Fast builds transpile rather than type-check, so run appropriate explicit type checks when warranted by the change. Do not rebuild between test selections when inputs have not changed. Test failures caused by stale output are a common pitfall.