Repository navigation
Architecture
Live Test Runner is a monorepo of three packages that form a layered system: a runner engine, shared session logic, and a VS Code extension that owns the entire UI.
This page is the big picture. How a single feature works end to end is in its own page under design/, for example on-save reruns.
The VS Code native Test Results panel has a Mac-specific bug where clicking an individual test shows "The test case did not report any output." even when output is appended correctly. This is a VS Code API limitation affecting all Mac versions.
The solution is a fully custom webview UI. This gives cross-platform control over the results experience and enables a Wallaby-style editor integration that the VS Code API cannot support.
packages/
├── core/ @live-test-runner/core Session state
├── runner/ @live-test-runner/runner Framework-agnostic execution engine
└── vscode-extension/ live-test-runner VS Code extension
Dependency direction: vscode-extension → core → runner. The runner has no knowledge of VS Code.
┌──────┬────────────────────────────────────────────┐
│ │ │
│ A │ Editor area │
│ c │ (gutter icons, inline duration, │
│ t │ CodeLens ▶ Run ▷ Debug ◈ Results) │
│ i ├────────────────────────────────────────────│
│ v │ Panel (bottom) │
│ i │ [ Output ] [ Test Results ] │
│ t │ │
│ y ├────────────────────────────────────────────┤
│ │ Status Bar │
└──────┴────────────────────────────────────────────┘
│ Primary sidebar
│ Live Test Runner (explorer view)
| VS Code zone | What lives there |
|---|---|
| Activity Bar | Beaker icon — opens the Explorer view |
| Primary sidebar | Explorer view — recursive file → node tree (unlimited nesting), summary counts, search; switches to Timeline sidebar (State / Watch / Call Stack) in timeline mode |
| Panel › Output |
Live Test Runner — levelled extension log (error / warning / info / debug / trace). Live Test Runner: Test Output — raw Jest output, ANSI-stripped, each line tagged [jest#N]
|
| Panel › Test Results | Results view — 3-column scoped view in normal mode; Timeline view (bar + controls + console/errors) in timeline mode |
| Editor gutter | Status icons (✓ / ✗ / ⟳ / ○) per test line; active-step highlight in timeline mode |
| Editor inline | Duration text after each test (normal mode); variable ghost text at current step (timeline mode) |
| Editor CodeLens |
▶ Run, ▷ Debug, ◈ Results, ⏱ Timeline above each block |
| Status Bar | Live summary: Live Tests: ✅ 12 passed
|
Owns the session's on / off state.
| File | Responsibility |
|---|---|
TestSession.ts |
Whether a project's session is on (activate / stop) and the runner it uses |
On-save reruns use the execution trace (Jest, Vitest), then the framework's related run (jest --findRelatedTests, vitest related). The old CoverageMap (always empty) and SelectionPolicy were removed in 3.3.0.
A self-contained, framework-agnostic execution engine. The VS Code layer depends only on the TestRunner interface — never on concrete classes.
JestRunner (orchestrator)
├── FrameworkDetector inspects package.json → picks adapter
├── FrameworkAdapter resolves binary + config per project type
├── BinaryResolver finds jest binary in project node_modules
├── Executor spawns Jest child process, reads --outputFile JSON on exit
└── ResultParser normalises JSON → RunResult
Each adapter implements FrameworkAdapter and names itself with a FrameworkId — an open string id (FRAMEWORK_IDS lists the shipped ones: jest, cra, vitest, pytest, unknown). An adapter's optional family (js default, python) keeps projects of different languages apart (findTestProjects drops a nested project only when it is the same family).
| Method | Purpose |
|---|---|
detect(projectRoot) |
Returns true if this adapter handles the project |
resolveBinary(projectRoot) |
Returns absolute path to the test runner binary |
resolveConfig(projectRoot) |
Returns path to a resolved config file, or undefined |
getExtraArgs(projectRoot) |
Any extra CLI flags the framework needs |
capabilities(projectRoot) |
FrameworkCapabilities at the installed version — callers check these, not the framework id |
Current adapters:
| Adapter | Handles | Notes |
|---|---|---|
JestAdapter |
Jest, Next.js + Jest | Reads jest.config.* or package.json#jest directly |
CRAAdapter |
Create React App | Runs --showConfig once per session to extract the hidden config; cached in memory |
VitestAdapter |
Vitest ≥ 3 (older best-effort) | A vitest dependency or Vitest config/workspace file, and no Jest dependency/config. Runs vitest/package.json#bin (vitest.mjs) with node — no .bin shim, no npx. Config: vitest.config.* > vite.config.*. Capabilities per installed major; refuses the editor's built-in Node when it fails Vitest's engines.node. Runner: VitestRunner. The test script's config-relevant flags are passed on, following nr / npm run / pnpm into other scripts (testScriptVitestArgs); its --config wins over the config files |
AngularAdapter |
Angular 21+ (Vitest through @angular/build:unit-test) |
An angular.json project whose test target uses the unit-test builder with the Vitest runner (Karma: a clear warning). Runs the project's @angular/cli/bin/ng.js test <project> (one Angular project per command) with --include / --filter / --list-tests, our reporters and a runner config in the session folder; CI=true keeps .angular/cache out. Priority 250, before Vitest. Runner AngularRunner (extends VitestRunner) |
PytestAdapter |
pytest ≥ 7 on Python ≥ 3.12 (family python) |
A pytest config (pytest.toml / pytest.ini / pyproject.toml [tool.pytest…] / tox.ini / setup.cfg), a root conftest.py, or pytest in the dependency files next to test files; priority 50, below every JS adapter. Binary: the project's interpreter, registered by the extension (setPythonFor / pythonFor, probed by probePython). Runner: PytestRunner (python -m pytest -p ltr_pytest …, node ids via pytestNodeIds.ts). Results, live events, per-test output, coverage and per-test contexts come from the shipped plugin framework/pytest/ltr_pytest.py (embedded as ltrPytestSource.ts) |
Adapters also own how a run is read: outputFileArg(file) (the result-file flag the Executor appends), parseResult(...) (raw JSON → RunResult; Jest and CRA use ResultParser, Vitest parseVitestResult — see the runner README for what differs between Vitest versions) and createRunner(...). The runner layer is CommandRunner (generic: binary/config/extra-arg assembly, chunking, kill, coverage) with one subclass per framework that only builds that framework's args per run kind (JestRunner, VitestRunner). Commands are [user-command words] [leadingArgs] [--config] [adapter extra args] [buildArgs] — leadingArgs holds a subcommand and its positionals (Vitest run <files>; empty for Jest). Each runner refuses another framework's project with refusingAdapter() (throws UnsupportedFrameworkError when a run starts).
FrameworkDetector tries the adapters of a FrameworkRegistry (default: CRA 300 → Angular 250 → Vitest 200 → Jest 100 → pytest 50, highest priority first) and returns the first match; detectWithReason() also says why. A project nothing matches falls back to plain Jest with one WARN per project root (matched: 'unknown'). VitestAdapter only matches when nothing marks the project as Jest (a jest dependency or a Jest config), so libraries that test with both run on Jest. JestRunner only runs Jest-family adapters (jest, cra); for any other project it keeps a stand-in adapter that throws UnsupportedFrameworkError when a run starts — setting the project root never fails.
Two different command shapes are used depending on context:
How Jest is started. Always node <jest/bin/jest.js> … — Jest's JS entry point resolved from the project (BinaryResolver.resolveJestEntry; CRA: the Jest react-scripts depends on), run with node from PATH (fallback: the editor's runtime with ELECTRON_RUN_AS_NODE=1) and no shell, so arguments (paths with spaces, ^…$ patterns, a|b) reach Jest verbatim. A shell is used only for a user jestCommand / npx, with every argument quoted. Executor.kill() ends the whole process tree. File paths are passed with forward slashes and an upper-case drive letter (Jest realpaths rootDir and compares case-sensitively).
Path spelling. Jest resolves rootDir with realpathSync.native, so a project opened through a symlink (macOS /var → /private/var, a symlinked checkout), a Windows 8.3 short name (RUNNER~1), a junction or a subst drive has two spellings. runner/src/resolution/RunnerPaths.ts records each project root's real path: everything sent to Jest uses it (toJestPathArg, generated configs' rootDir/roots, the transform pattern) and everything read back (--listTests, JSON results, reporter records, traces, coverage manifests, Timeline steps) is mapped to the editor's spelling with fromRunnerPath.
One file, several Jest projects. A multi-project config can run the same file more than once (e.g. under jsdom and node). Jest reports each run; mergeFileResults (runner) merges them so a test fails if it failed in any project.
Batch run — JestBatchRunner (initial run + on-save file reruns):
node jest.js --watchAll=false --forceExit --no-bail --runTestsByPath <file1> [file2 …] \
--config <transform cache>/ltr-jest-config-<hash>.js --cacheDirectory <per-project transform cache> \
--maxWorkers=1 --testLocationInResults --verbose=falseThe temp config starts from the project's config as Jest resolves it — JestProjectConfig runs jest --showConfig (CRA: react-scripts test --showConfig) once per session, so every config format, preset and multi-project setup works — and layers on sessionTraceTransform.js (light trace transform), ltrCoverageSetup.js (first setupFilesAfterEnv entry: coverage flush, per-test trace context, test heartbeats) and liveReporter.js (streaming reporter). The generated config is one file per content hash in the project's transform-cache folder (writeStableConfig), and its text holds nothing per batch or session (the reporter file and the resolved-config JSON come through LTR_REPORTER_FILE / LTR_JEST_RESOLVED_CONFIG): Jest names its transform cache and file map after the config's path, so every batch and later session reuses the compiled files instead of re-instrumenting the whole project. Results are polled from the reporter JSONL file every 200 ms while Jest runs — the UI updates per file rather than waiting for the whole batch.
Reported paths are mapped back to the store's own keys. A file shows ⟳ only once Jest starts it (reporter start record). The newest run of a file owns it: an older batch still running the same file is not killed, its result for that file is ignored. A single test running longer than hangTimeoutSeconds (setup-file heartbeats) stops the batch; that file is failed and the rest retried.
Run lifecycle — SessionManager. Every run (full suite, save, ▶ Run) registers on start and ends in a finally. Overlapping runs share one progress total (onRunProgress) and one onRunFinished, sent when the last run ends. A session token changes on Start / Stop; work started under an older token stops before its next batch, retry or fallback. At session start jest --listTests (the project's own config) decides which discovered files Jest runs — the others are shown as skipped and never run.
Coverage is Jest's own, with the project's provider: every batch runs with collectCoverage on (coverageProvider from the project, coverageReporters: ['none'], an empty collectCoverageFrom, so Jest does no untested-file pass per batch). Our transform adds only the trace on top:
source file
→ the project's transformer (babel-jest, ts-jest, @swc/jest, vue-jest, …)
'babel' provider: it instruments when it can (canInstrument), else we add
Jest's instrumentation the way ScriptTransformer._instrumentFile does
(babel-plugin-istanbul with the transformer's map as input)
→ our Babel pass on its output: __strace.step(line, file) before each statement
(locations moved back to the file through the maps; no counters, no rewrites)
→ generated with a source map back to the file (no retainLines: the map carries
the lines, and Jest's counters could leave a `return` alone on its line)
→ Jest runs it; 'v8' provider: V8 measures this code, mapped back through our map
-
liveReporter.jskeeps each test file's coverage as Jest would report it (jestCoverage.perTestFile: istanbul data remapped through input maps, ortestResult.v8Coveragethrough v8-to-istanbul, Jest's module wrapper left out as Jest's own map leaves it out), one line per test file, and empties the test result's copy so Jest's own coverage reporter has nothing to merge. - Files no test loads:
jestCoverageCount.js(a child process, once per session when the batches are done, and for files created or edited later) runs Jest's owngenerateEmptyCoveragewith the project's resolved config. - Test files are never instrumented (
jest.mockfactories hoisted above our code would break). - Without a coverage file (
LTR_JEST_COVERAGE_FILEunset) the transform falls back to its own counters (__covF, manifests,ltrCoverageSetup.jsflush).
--maxWorkers=1 keeps each Jest process single-threaded so batches can run in parallel without competing for CPU.
Single-test / scoped-rerun — JestRunner (CodeLens ▶ Run, suite/test reruns):
jest --config <resolved> --watchAll=false --forceExit --no-bail --json \
--outputFile=<tmpfile> --testLocationInResults [--testNamePattern <name>]-
--outputFile=<tmpfile>— avoids Windows pipe-buffering truncation for large JSON payloads - Stdout is captured as a fallback — CRA occasionally skips
--outputFileon bailed runs -
--no-bail— collects all failures in a single pass
CRA hides its Jest configuration. You cannot pass --json, --outputFile, or --no-bail to react-scripts test directly.
CRAAdapter solves this:
- Runs
react-scripts test --showConfig --passWithNoTestsonce per session - Extracts the embedded Jest config JSON from the output
- Writes it to a temp file
- All subsequent runs invoke Jest directly — never
react-scriptsat run time
The extracted config is cached in memory per session and invalidated if package.json changes. Transformer options are kept ([path, options]), and behaviour flags from the project's test script (e.g. react-scripts test --resetMocks) are passed on, so runs match npm test.
These are the normalised types returned by any runner implementation. They are framework-agnostic — a future VitestRunner or MochaRunner produces the same shapes.
RunResult
└── FileRunResult // per test file
└── TestCaseRunResult // per it/test case
├── status: 'passed' | 'failed' | 'pending' | 'todo' | 'skipped'
├── duration?: number
├── location?: { line: number, column: number }
├── failureMessages: string[]
└── ancestorTitles: string[] // suite hierarchy
ConsoleEntry // console output per file run
├── message: string
├── type: string // 'log' | 'warn' | 'error' | 'info' | 'debug'
└── origin: stringThe deprecated aliases JestJsonResult, JestFileResult, JestTestCaseResult, JestConsoleEntry remain exported from packages/runner/src/index.ts for backward compatibility but are not used in new code.
A self-contained feature that runs alongside the existing session system. It replays a single test case step by step, showing what lines executed, what variables held at each step, and where things went wrong.
Activation: ⏱ Timeline CodeLens on it/test lines, or the per-row ⏱ Timeline button in the Explorer sidebar. Both call liveTestRunner.openTimelineDebugger(filePath, testFullName).
Architecture:
IInstrumentedRunner (interface)
└── JestInstrumentedRunner
├── Writes temp Jest config that adds traceTransform.js to the transform chain
├── Sets TRACE_OUTPUT_FILE env var
├── Spawns Jest via Executor (reused as-is)
└── Reads JSONL trace file → parseEvents() → TimelineStore
traceTransform.js (CJS)
Injected into Jest's transform chain for the target file only.
Adds __trace.step(id, line, file, fn) before each statement
and __trace.var(id, name, value) after assignments.
traceRuntime.js
Provides __trace.* — writes each event as a JSON line to TRACE_OUTPUT_FILE synchronously.
TimelineStore
Held in extension host memory. Serialised (Maps → plain objects) before postMessage.
Contains: steps[], variables{stepId: VariableSnapshot[]}, logs{stepId: LogEntry[]}, errors[]
PlaybackEngine (webview)
Pure JS class in results.html. Owns currentStepId, play/pause timer, next/prev/jumpTo.
On each step change, sends { type: 'step-changed' } to the extension host.
TimelineDecorationManager
Dedicated TextEditorDecorationType (never touches DecorationManager.ts).
Highlights the active line; renders inline ghost text (variable values).
Registers a HoverProvider for variable history + [Add to Watch] / [Copy].
Webview routing: Both ResultsView and ExplorerView implement an internal JS router. On timeline activation, the extension sends { type: 'route', view: 'timeline' } to ResultsView and { type: 'route', view: 'timelineSidebar' } to ExplorerView. The router swaps view modules into <div id="app"> without reloading the page.
Shared components: logPanel.js and errorPanel.js are standalone JS modules used by both resultsView.js (normal mode) and timelineView.js (timeline mode). They accept a container element and a data payload, and render themselves with no view-specific knowledge.
Creates the views and the ProjectRegistry, registers VS Code commands and event handlers, and hands each command to the selected project's (or the file's project's) SessionManager. Contains no run logic.
A window holds one ProjectContext per test project (src/project/). Everything that used to exist once per window is per project:
Per project (ProjectContext) |
Shared by the window |
|---|---|
ResultStore, ExecutionTraceStore, CoverageStore
|
SelectionState, the views, decorations, CodeLens, hover (these resolve each file to its project) |
TestDiscoveryService + DiscoveryCache (keyed by root) |
Output channels, status bar item |
framework services (FrameworkRouter → Jest / Vitest bundle(s), each with its own batch runner) |
Timeline decorations |
SessionManager (fixed projectRoot), runnable-files cache entry (keyed by root) |
|
session folder (session-<pid>-<ts>/p<N>-<name>; the folder itself when there is one project) |
Detection (runner framework/projectDiscovery.ts, pure, unit-tested) — for each VS Code workspace folder:
- the folder has its own test config (
jest.config.*,package.json#jest,vitest.config.*/vite.config.*/vitest.workspace.*,react-scripts test) → one project at the folder; its config covers its packages (thejestrepo's rootprojects, vueuse / slidevtest.projects); - else a monorepo root (
pnpm-workspace.yamlpackages:,package.json#workspaces) → one project per workspace package with tests (a framework dependency, config, or a test script running jest / vitest / react-scripts); - else the folder, if a framework is detected there.
These are the JavaScript rules (jsProjectsInFolder). Python projects (pythonProjectsInFolder, 3.3.0) follow the same shape: a folder that configures pytest (a pytest config or a root conftest.py) → one project; else a uv workspace root ([tool.uv.workspace] members / exclude) → one project per member with tests (a pytest project itself, or test files when the root names pytest); else the folder, if it is a pytest project. Each member finds the workspace's shared .venv (the interpreter search walks up from the project to the workspace folder). A folder both families claim is one project, the JS one, whose router also runs pytest there (projectFrameworks adds pytest; JS + Python in one folder, 3.3.0). A folder with no Python of its own is searched two levels down for folders that configure pytest or are a uv workspace root (nestedPythonRoots) — each is a Python project by these rules.
Projects inside another project's root of the same language family are dropped; a single folder with nothing recognised is still the project (plain Jest, as before). liveTestRunner.projectRoot pins the window to that one root.
ProjectRegistry owns the contexts and the selected project. Nothing runs automatically: only the selected project's static discovery starts at activation, others on first selection or Start. Each project's SessionManager notifies one observer, the project's ProjectObserverGate: it records the project's live state (session active, discovering) for the switcher row and forwards every event to the window's observers only while the project is selected. Switching (onDidChangeSelection) rebinds the Explorer and Results views to the new project's stores (bindProject) and sends them a fresh init (with running progress when the project is mid-run). Editor features are per file, not per selection: DecorationManager, CodeLensProvider, CoverageDecorationManager and CoverageHoverProvider take a FileStoresResolver (editor/FileStores.ts → ProjectRegistry.forFile) and decorate every file from its own project; they are editorObservers, to which every project's gate forwards regardless of selection. Opening a file of a not-yet-discovered project starts that project's discovery (nothing runs); CodeLens ▶ Run / ▷ Debug go to the file's project (explicit clicks work without a session). Background projects keep running and rerunning on save (onDidSaveTextDocument goes to the file's project). Start / Stop act on the selected project; liveTestRunner.maxRunningProjects (auto = 2, or 1 with ≤ 4 cores / < 8 GB total memory) caps how many sessions are active at once — Start on one more is refused with a message naming the running projects.
Why one SessionManager per project instead of one manager over contexts: the manager's run bookkeeping (_token for Stop, _activeRuns, progress, save timers, runnable set) is per session by nature. Keeping it per project made the phase a re-wiring (fixed root, a status sink, a gated observer list) instead of a rewrite, and every single-project path is unchanged.
The status bar shows the selected project: Live Tests: ✅ 12 passed with one project (unchanged), Live Tests: web · ✅ 12 passed · 2 running with several. The Explorer's switcher row (projects message; only with two or more projects) lists each project with its state (● running 3/10, ● live, ⟳ discovering) and ✓ / ✗ counts; clicking one runs liveTestRunner.selectProject. Files of a Vitest config with several test.projects carry FileResult.group (Vitest's projectName from vitest list --json, cached with the runnable list) and the test list groups them under one collapsible row per Vitest project.
All result consumers implement IResultObserver. After each file result arrives, SessionManager calls every registered observer. This decouples the run engine from the UI completely.
interface IResultObserver {
onSessionStart(): void
onRunStart(filePath: string): void
onFileResult(result: FileRunResult, store: ResultStore): void
onSessionStop(): void
// Optional — discovery events (called by TestDiscoveryService)
onDiscoveryStarted?(total: number): void
onDiscoveryProgress?(file: unknown, discovered: number, total: number): void
onDiscoveryComplete?(): void
}The discovery methods are optional so existing observers don't need to implement them. TestDiscoveryService checks for their presence before calling.
Registered observers: ExplorerView, ResultsView, DecorationManager, CodeLensProvider, CoverageDecorationManager.
ResultStore — the single source of truth for all result data. Uses a flat node pool (Map<string, TestNode>) for O(1) lookups with tree relationships managed via parentId/children. Supports unlimited nesting depth.
ResultStore
├── files: Map<filePath, FileResult>
│ └── FileResult
│ ├── filePath, name, status, duration
│ ├── output: ScopedOutput ← console lines captured at file level
│ └── rootNodeIds: string[] ← top-level nodes in this file
│
└── nodes: Map<nodeId, TestNode> ← flat pool, O(1) lookup
└── TestNode
├── id, type ('suite' | 'test' | 'template')
├── name, fullName, status, duration
├── parentId: string | null
├── children: string[] ← dynamic variations attached here
├── line?: number
├── output: ScopedOutput ← populated only on scoped reruns
└── failureMessages: string[]
Node IDs follow a stable path convention: {filePath}::{suite1}::…::{name}. Status rolls up via bubbleUpStatus() in O(depth). Summary counter is incremental (O(1)). Empty template nodes are ignored by status rollups to prevent ancestors from showing incorrect passed/failed status during partial child execution.
Nested Branch Compatibility: The recursive node tree supports arbitrary depth (10+ levels) of describe blocks. When a test result arrives deep within a nested branch, the ResultStore automatically bubbles the status up the chain. For partial runs (where only a specific nested test is executed), the extension correctly resets the status of every ancestor in the branch to running before applying the new result, ensuring that high-level "failed" or "passed" icons don't stick when their children are still in flight.
DiscoveryCache — persistent on-disk cache for Babel AST parse output. Lives at globalStorageUri/cache/<folderName>-<sha256(workspacePath)[0:8]>/discovery-cache.json. Each entry stores { mtime, result } keyed by absolute file path. On load, stale entries (mtime changed or file deleted) are dropped; only changed files are re-parsed. A session.lock PID file marks active sessions so LRU rotation skips them.
- Batch size adapts:
BATCH_SIZE_COLD = 5(no cache, Babel parse per file) vsBATCH_SIZE_WARM = 25(cache hits, stat-only check) -
flush()is called once after discovery completes and after each watcher re-discovery -
rotateAndCheckCapacity()evicts inactive LRU projects when >500 MB or >10 projects - Single-project installs are never capped; over-cap with all sessions active shows a warning modal
ExecutionTraceStore — derived indexes built from per-test JSONL trace files. The trace files on disk are the source of truth; these are fast-lookup caches rebuilt after each instrumented run.
ExecutionTraceStore
├── traceIndex: Map<testId, string>
│ testId = full test name ("Suite > test") → absolute .jsonl path
│ Written to a window-unique trace directory within the user's temp storage.
│ Used by: Timeline Debugger
│
├── coverageIndex: Map<filePath, Set<lineNumber>>
│ Every source line executed by any test in the session.
│ Accumulates across runs — never resets mid-session.
│
├── lineToTests: Map<sourceFilePath, Map<line, Map<testFilePath, fullName[]>>>
│ The tests that ran each line (coverage hover). Per test file, so a
│ batch adds or forgets only its own files' entries: a flat list per
│ line made each batch scan every earlier test of a shared component.
│
└── sourceToTests: Map<sourceFilePath, SourceTestMapping>
{
[testFilePath]: {
[suiteName]: {
isSharedVars: boolean // true → run whole suite when source changes
sharedVarNames: string[]
testCases: string[] // full test names
}
}
}
Populated after each batch (applyTraceRecords; setSourceTests updates one test file's entry in place).
Used by SessionManager._runAffectedBySourceFile() for smart on-save reruns.
CoverageStore — in-memory store for statement/branch/function/line coverage metrics. Lives in src/coverage/. Separate from ExecutionTraceStore because it has its own lifecycle (populated by SourceCounter + JestBatchRunner._parseCoverage()).
CoverageStore
entries: Map<filePath, CoverageEntry>
CoverageEntry is one of:
{ state: 'counted', statements, branches, functions, lines }
{ state: 'measured', manifestPath, counters: LiveCov, pct: CoveragePct }
{ state: 'measured-stale', manifestPath, counters: LiveCov, pct: CoveragePct }
onDidChange: EventEmitter<void> — fired on any mutation; observers redraw badge + gutter
_scanComplete: boolean — set to true when SourceCounter finishes
Key reads:
getTotals(): CoverageTotals — one-pass aggregate across all entries; 'counted' entries
contribute denominator only (covered = 0 until measured)
getFileRows() — returns all entries as { filePath, state, pct } rows
for the coverage table; 'counted' rows with all-zero
counts (Babel parse failed) are omitted
isScanComplete(): boolean — true once SourceCounter has processed all source files
isAllMeasured(): boolean — true once every entry has been promoted from 'counted'
Key writes:
setCountedEntry(filePath, counts) — called by SourceCounter per source file
setMeasuredEntry(filePath, data) — called by JestBatchRunner._parseCoverage()
markFileStale(filePath) — 'measured' → 'measured-stale' on save (rerun pending)
clearStale(filePath) — 'measured-stale' → 'measured' if rerun is aborted without
completing (e.g. session stopped mid-rerun)
markScanComplete() — called by SourceCounter when its scan loop finishes
clear() — full reset on session stop
CoverageTotals — aggregate type returned by getTotals():
interface CoverageTotals {
statements: { covered: number; total: number; pct: number }
branches: { covered: number; total: number; pct: number }
functions: { covered: number; total: number; pct: number }
lines: { covered: number; total: number; pct: number }
scanComplete: boolean // mirrors CoverageStore._scanComplete for consumer convenience
}Entry lifecycle:
-
'counted'— set bySourceCounterat session start (0 hits, denominator only) -
'measured'— promoted byJestBatchRunner._parseCoverage()after a run touches the file -
'measured-stale'— set bySessionManagerwhen the file is saved and a rerun is pending - Back to
'measured'— when the rerun completes and_parseCoverage()fires again
CoverageReport (src/coverage/CoverageReport.ts): Stateless calculate(manifest, counters): CoveragePct function. Reads a coverage manifest (statement/branch/function IDs with location) and a live counter snapshot, and returns the four-metric CoveragePct. Called wherever an entry is built (the store, the batch runners) — not a class; no side effects. When test files measured one file with different maps (Vitest 3's v8 maps depend on what ran), mergeIstanbul (coverageRules.ts) merges them as istanbul-lib-coverage does, so the numbers equal the framework's merged report.
CoverageDecorationManager (src/editor/CoverageDecorationManager.ts): Implements IResultObserver. Subscribes to CoverageStore.onDidChange and refreshes all visible editors on every change. For each editor it reads the CoverageStore entry and — for measured or measured-stale entries — loads the manifest from disk to classify every line into one of four states:
| State | Decoration | Condition |
|---|---|---|
| covered | green left edge | statement hit count > 0 and all branch arms hit |
| partial | amber left edge | statement hit > 0 but at least one branch arm missed |
| uncovered | red left edge | statement hit count = 0 |
Each bar is a thin, faded 1px left border of an isWholeLine decoration: nothing is inserted into the text (code never shifts) and the gutter stays free for breakpoints and test status icons. Lines in no statement get nothing. When the entry is measured-stale an additional full-file grey background tint is applied. The overview ruler mirrors the green/amber/red states so uncovered regions are visible in the scrollbar.
Unsaved edits (src/editor/MeasuredLines.ts, lineMatch.ts): the manifest's lines are the file as it was measured. MeasuredLines remembers that text per measurement (keyed by the entry's counters object, read from disk the first time it is seen) and matches the editor's current lines against it — common prefix and suffix, then a longest-common-subsequence match of the changed middle (skipped above 2M cells). Lines compare with their indentation exact but inner and trailing spacing ignored (normalizeLine), so formatting keeps bars while code wrapped in a new if loses them. A move (a distinctive line removed in one place and added in another) clears the matches between the two places, so moved code never keeps a bar. When less than half the measured non-blank lines remain (keptShare), the file shows no bars until it is measured again. Bars are drawn on each measured line's current position; edited and new lines get none until the next measurement — a wrong bar is worse than no bar. Typing redraws after 150 ms. CoverageHoverProvider uses the same mapping (current line → measured line), so the hover and Show All Covering Tests follow the edit too.
Show / hide: liveTestRunner.showCoverageInEditor (default on), toggled by the hideCoverageInEditor / showCoverageInEditor commands — eye buttons in the editor title while the file has coverage (context keys liveTestRunner.editorHasCoverage, liveTestRunner.coverageInEditorShown). Hidden clears bars and stale tint and turns the coverage hover off.
CoverageHoverProvider (src/editor/CoverageHoverProvider.ts): Registered as a vscode.HoverProvider for all JS/TS source files. On hover it:
- Looks up the
CoverageStoreentry for the file; returns nothing if the file has no coverage data. - Returns a stale warning if the entry is
measured-stale. - For
measuredentries, reads the manifest to check whether the hovered line is covered and whether any branches on that line have missed arms. - Builds a
MarkdownStringwith:- Branch arm hit/miss table for partial lines (e.g.
if/else: ✓ then / ✗ else) - A list of up to 5 tests that cover the line, each showing pass/fail icon, duration, a clickable link to reveal the test in the Results panel (
liveTestRunner.revealTestInPanel), and a file-open link (liveTestRunner.openTestFile).
- Branch arm hit/miss table for partial lines (e.g.
- Test status is read from
ResultStore.findNodeByFullName()at hover time — never cached — so it always reflects the latest run.
Coverage Explorer tab (src/webview/views/coverageExplorerView.js): A router view mounted in explorer.html when the user clicks the "Coverage" tab. Shows a four-column project totals row (Stmts / Branch / Fns / Lines) and a scrollable per-file breakdown table. Clicking a file row sends an openFile message to the extension host, which opens the file in the editor. The tab is only shown when a session is active and coverage data is available.
Coverage manifest (src/session/instrumentation/sessionTraceTransform.js writes these):
<LTR_SESSION_TMP_DIR>/coverage/manifests/<sha256(filePath)[0:16]>.json
Written once per source file per transformed run. Contains every statement/branch/function with IDs and line locations. The manifest + counters together drive the four metrics. CoverageStore holds only the path string — the file is read on demand (gutter decorations, _parseCoverage merging) to keep heap flat on large projects.
SourceCounter (src/coverage/SourceCounter.ts):
Runs at session start in parallel with the first test run. AST-parses the source files that count toward coverage (via vscode.workspace.findFiles + @babel/parser), counts statements/branches/functions/lines, and populates CoverageStore with 'counted' entries. This ensures untouched files (never imported by any test) still contribute to the denominator — giving correct aggregate percentages rather than inflated ones. Which files count is the framework's CoverageScope (src/coverage/coverageScope.ts, from IProjectConfig.coverageScope(root)), so the totals match the CLI report: Vitest's resolved coverage.include / exclude (read by the runner's config probe), or Jest's collectCoverageFrom / coveragePathIgnorePatterns / test and setup files (from --showConfig). With no include list (no Vitest coverage.include, no Jest collectCoverageFrom) the CLI reports only loaded files, so the scan is skipped. The same scope filters measured files in both batch runners. When the config cannot be read, the built-in exclusion list (node_modules, test files, config files, dist/, etc.) applies and git-ignored files are skipped. Yields to the event loop every 10 files (YIELD_EVERY = 10) to keep the UI responsive. Emits progress and done events for the badge scanning indicator. Respects the liveTestRunner.coverageExclude setting (array of glob patterns, always excluded from the scan).
Relationship between the stores:
-
ResultStoreanswers "what happened" — pass/fail, output, failures -
ExecutionTraceStoreanswers "what ran and where" — which lines executed, which tests cover which files -
CoverageStoreanswers "how much is covered" — statement/branch/function/line percentages per file and in aggregate - The trace files and coverage manifests are the ground truth on disk; the stores are derived caches.
LineMap — inside ResultStore:
LineMap: Map<filePath, Map<lineNumber, LineEntry>>
LineEntry: { nodeId, fileId } // identity only — never status or duration
LineMap stores identity only. DecorationManager always queries ResultStore.getNode(nodeId) for status and duration at decoration time — they are never duplicated into the map, so they are never stale.
LineMap lifecycle:
-
Discovery —
TestDiscoveryService._populateSuiteTree()builds the initial map from AST line numbers. Gutter icons and CodeLens lenses are available immediately. -
Run —
JestAdapter._applyFileResult()replaces the map for that file with Jest's authoritativelocation.linevalues. This is more accurate than AST line numbers (Jest accounts for comments, blank lines, etc.). -
Session stop —
clearAll()wipes decoration state but the map is retained until the next run or discovery pass. Pending icons from discovery persist across session stop/start cycles.
ScopedOutput:
interface ScopedOutput {
lines: OutputLine[] // captured log lines
capturedAt: number | null // Date.now() when stored; null = never run at this scope
}
interface OutputLine {
text: string
level: 'log' | 'info' | 'warn' | 'error'
timestamp: number
}Output scoping rules: Jest JSON reports console output at file level only. When a file runs, only FileResult.output is set. Node output is set only when that scope is individually rerun via --testNamePattern. Output is never back-filled or fabricated for scopes that haven't been run individually.
Vitest is different: the runner's reporter (framework/vitestReporter.ts, loaded with --reporter=<file> next to default and json) records each console call with the task that made it, so ConsoleEntry.scope is file / suite / test with the scope's full name. RunnerBackedAdapter then sets every touched test's output to exactly its own lines (empty for a quiet test that ran), a suite's to its hooks' lines, and — on a whole-file run — the file's to all lines. Scoped reruns update only the scopes they ran.
SelectionState — tracks which row the user has selected in the results panel. Emits scope-changed messages when selection changes.
Runs on extension activate — before the user clicks Start Testing.
-
start(projectRoot, store, log, callbacks)— finds all test files viavscode.workspace.findFiles, then parses them in batches of 8 with asetImmediateyield between batches. This keeps the extension host responsive on large projects (500+ files, 3000+ tests). -
Per-file — reads source, runs
discoverTests()(AST walker intestDiscovery.js), recursively walks the returned suite tree callingstore.nodeStarted/store.nodeResultto build the hierarchical node tree. Rebuilds theLineMapfor that file, and emits a serialised file object viaonFileDiscoveredcallback. -
awaitDiscovery()— returns the internalPromise;SessionManager.start()awaits this so it never re-discovers files that are already populated. -
PID Cleanup — during activation, the service scans the shared temporary root and prunes session folders whose owning process ID is no longer active (verified via
process.kill(pid, 0)). -
FileSystemWatcher— monitors**/*.{test,spec}.{js,ts,jsx,tsx,mjs,cjs}. New files appear immediately on create. On change/save the watcher skips files with status'running'(a run is already in progress for that file); for all other statuses it callsstore.removeFile()and re-populates so newly added or renamed tests appear straight away without waiting for a run.
testDiscovery.js (pure AST walker, no code injection):
- Uses the project's own
@babel/parser+@babel/traverse(lazy-loaded from the project root at first use) - Handles:
describe/it/test,.only/.skip,.each([...])(name, fn)(curried call pattern),.concurrent.*, deepMemberExpressionchains - Template literals: interleaves quasi text with
…placeholders so interpolated names still appear in the tree ("accepts valid severity …") - Returns
{ suites, rootTests }with accuratelinenumbers for every node
Everything cached lives outside the project: the user cache folder (<folder>-<hash8>/ discovery caches with a session.lock, ltr-cra-config-*.json) and the temp folder (session-<pid>-<time>/ per window, runnable-files-*.json, vitest-config-*.json (what the Vitest config probe read), transform-cache-*/ with coverage manifests). Storage.ts knows every path: Stop Testing and Clear Cache deletes all of a project's entries; Clear All Cached Data deletes everything except other live windows' session folders and locked discovery caches; on activation pruneUnused deletes entries unused for 30 days (transform caches, runnable lists and Vitest config answers are touched on use). A window's session folder is deleted in deactivate, dead windows' on activation; Open Cached Data Folder opens both base folders; discovery caches are also capped at 10 projects / 500 MB (LRU, on Start).
-
Start Testing — awaits
TestDiscoveryService.awaitDiscovery()(no-op if discovery already finished), reads file paths directly fromResultStore, clearsCoverageStore, firesSourceCounter(background, parallel), runs all test files, enables on-save listener -
On save — debounced (default 300ms); classifies file as test or source; for source files calls
CoverageStore.markFileStale()then_runAffectedBySourceFile()(the execution trace, else the framework's related run)-
Changed on disk —
extension.tswatches**/*;session/ExternalChanges.tsdrops the editor's own saves (onWillSave/onDidSave, 2 s), dirty documents,node_modulesand.git, batches events for 500 ms and hands each project its files (onFilesChangedOnDisk). Same path as a save (onFileChanged); more than 20 files restart the session; changes during a run are queued (_diskQueue) and rerun when the last run ends (_runQueuedDiskChanges) — a file that changed again during its own queued rerun is not queued again (_lastDiskRerun, a test writing it would loop).
-
Changed on disk —
-
Stop Testing — kills child processes, clears decorations, calls
CoverageStore.clear(), disables on-save
After each file batch, JestBatchRunner parses the light-trace JSONL (updates ExecutionTraceStore) and then parses the coverage counters JSONL (promotes CoverageStore entries from 'counted' to 'measured'). Both happen in the same post-Jest-exit phase — no extra process or phase needed.
The budget starts at liveTestRunner.speed (setSpeedLevel / totalWorkers, runner utils/resources.ts; balanced = half the cores) and, unless liveTestRunner.speedStrict, adapts before each test process to what the machine's other programs leave free (workersNow, between Light's budget and adaptiveCeiling, gated per process by its workers in SessionManager._memoryForAnotherBatch): parallel batches up to maxBatchSlots() (CONCURRENCY in SessionManager._runFiles), Vitest's workers per batch so that all batches together stay within it (workersPerBatch), and per framework by its batchPolicy (pytest: one process). Another batch starts only while memory is not low (memoryLow, SessionManager._memoryForAnotherBatch), and every test process runs below normal priority (lowerPriority in Executor). See test runs.
IFrameworkAdapter adds VS Code-specific methods on top of the runner's adapter concept:
| Method | Purpose |
|---|---|
detect(projectRoot) |
Detect the framework |
discoverTests(projectRoot, log) |
Run --listTests, return file paths |
isTestFile(filePath) |
Classify a saved file |
runFile(...) |
Run a file and write to ResultStore
|
runTestCase(...) |
Run a single test by name |
runRelatedTests(store, sourceFile, root, log) |
The framework's related run for a source file no trace knows |
getDebugConfig(...) |
VS Code debug launch config for ▷ Debug
|
Adding a new framework = one file implementing IFrameworkAdapter, plus that framework's batch runner and project config, bundled as FrameworkServices. SessionManager, ResultStore, all views, and all observers require zero changes.
SessionManager never builds framework classes. It gets an IFrameworkServicesProvider (servicesFor(fileOrRoot), all()) and asks it for the FrameworkServices of a file or project root (framework/FrameworkServices.ts):
| Member | Interface | Jest implementation | Vitest implementation |
|---|---|---|---|
adapter |
IFrameworkAdapter |
framework/JestAdapter.ts |
framework/VitestAdapter.ts |
projectConfig |
IProjectConfig (get(root), reset()) |
session/JestProjectConfig.ts (jest --showConfig) |
session/VitestProjectConfig.ts (the config file path) |
batchRunner |
IBatchRunner (runFiles(BatchRunOptions), optional runRelated(RelatedRunOptions), kill(), reset()) |
session/JestBatchRunner.ts (results + trace + coverage, streamed) |
session/VitestBatchRunner.ts (results streamed per file from the runner's Vitest reporter; per-test hang limit + no-progress fallback; Vitest's own coverage → coverage/istanbulCoverage.ts → CoverageStore; execution trace through VitestTrace's wrapper config → traceRecords.ts) |
instrumentedRunner |
IInstrumentedRunner (Timeline), optional |
timeline/JestInstrumentedRunner.ts |
— |
createSessionRunner() |
runner TestRunner for core's TestSession
|
runner JestAdapter.createRunner() → JestRunner
|
runner VitestAdapter.createRunner() → VitestRunner
|
Both adapters extend framework/RunnerBackedAdapter.ts, which holds everything that only needs a runner's RunResult: single-file, test-case and related runs, and mapping FileRunResults into the ResultStore (suites, .each templates, scoped reruns, output, and a file's own failure — its tests are failed with failureMessage when nothing ran). The adapters add detection, their runner (with the user's command setting) and the debug launch config.
Each ProjectContext composes its own FrameworkRouter (framework/FrameworkRouter.ts; one per project, so two projects never share a batch runner). prepare() (every Start) detects the root's main framework (runner FrameworkDetector) and whether the root is mixed (runner projectFrameworks: a Jest marker plus a vitest.config.* / vitest.workspace.* of its own), and reads liveTestRunner.frameworks. A single-framework project gets one bundle (createJestServices or createVitestServices) and lists its files as before. A mixed project (or one where a setting glob sends a discovered file to the other framework) lists with both frameworks in parallel and places every file once — runner assignFrameworks:
-
liveTestRunner.frameworks(first matching glob); - only one framework's list holds the file → that one (also when the other listing failed);
- both list it → an import from
vitest/ avi.call → Vitest,@jest/globals/ ajest.call → Jest (frameworkHint); - nothing says → the main framework, one WARN naming the setting.
servicesFor(file) then returns the file's bundle (source files and the root: the main framework). The placement is stored with the runnable-files cache (frameworks: { file: "vitest:hint" }); placements that came from a file's content are read again on restore and on save (fileChanged). Each runner refuses a root detected as the other framework unless the router called allowFrameworkAt(root, fw). In SessionManager batches are queued per framework (never mixed), a source-file save reruns each framework's dependents (owns filter: results of the other framework's files are ignored), and any framework's config file restarts the session. A source file loaded by tests of both frameworks gets its coverage merged by line (coverageRules.combineWithEntry). The Timeline command goes through a delegating IInstrumentedRunner that asks the test file's framework (Vitest: "not available yet"). Stop kills the batch runners of all() bundles.
Static discovery (instrumentation/shared/testDiscovery.js) uses the project's own @babel/parser / @babel/traverse when it has them (every Jest project), else out/vendor/babel-parser.js (shipped by esbuild.js) with a built-in call-expression walker.
A pytest project (DetectedProject.framework === 'pytest') gets the same FrameworkRouter as every project — its primary framework is pytest, so it builds only createPytestServices (framework/pytestServices.ts) — and the Python TestFileDiscoverer (session/discovery/pythonDiscovery.ts, a line scanner — python_files under testpaths, Test* classes without __init__, unittest.TestCase subclasses, @pytest.mark.parametrize → template name[…]). The bundle:
| Member | Implementation |
|---|---|
adapter |
framework/PytestAdapter.ts — RunnerBackedAdapter with runNamed → node ids, buildDebugConfig (type: debugpy, module: pytest, the project's interpreter; getDebugConfig adds the Python Debugger check) |
projectConfig |
session/PytestProjectConfig.ts — the config file pytest uses; coverage scope = what coverage.py reports minus test files / conftest.py; sourceExtensions py, pyi
|
batchRunner |
session/PytestBatchRunner.ts — one pytest process per batch, the plugin's events polled (file-start / heartbeats / file-end with a ready FileRunResult), per-test hang limit, coverage → applyIstanbulCoverage, per-test contexts (trace.jsonl) → applyTraceRecords; runRelated = static import graph (session/pythonImports.ts) |
batchPolicy |
{ maxParallel, maxFilesPerBatch: 300, workersPerProcess: 1 } — one pytest process at a time unless the project runs pytest-xdist itself (-n in its pytest config: then the budget's); batches sized up to 300 files |
whyNotReady |
no usable interpreter → SessionManager.start runs nothing |
configFileNames |
pytest config files + conftest.py pass the save filter → isConfigFile restarts the session |
The interpreter comes from python/PythonInterpreters.ts (order: selected → pythonPath → project venvs → poetry / pipenv / uv → Python extension → activated env inside the project → PATH), probed once per root and registered with the runner. The Explorer shows it on a chip for the pytest project shown (python/pythonEnvChip.ts: "Python 3.12.4 · .venv · pytest 9.1.1", amber with the reason when it can't run the tests; click → Select Python Interpreter): extension.ts probes quietly when the project is shown (ensure(root, { quiet: true }) — debug log only, no notification) and refreshes on PythonInterpreters.onDidChange; the first run that uses the interpreter logs it at INFO (or warns and notifies once). Nothing is installed or written into the project: the plugin lives in the session folder (pytest-plugin/ltr_pytest.py) and is named only with -p on our command line; runs add -o cache_dir=<session>, --no-cov (pytest-cov), -n 0 (xdist), --continue-on-collection-errors, and run without the JS environment (ExecutorCommand.jsEnv: false).
Plugin protocol ($LTR_PYTEST_EVENTS, JSON lines): {ev:"config", capture, rootdir, inifile, pytest, python, coverage, coverageError}, {ev:"file-start", file}, {ev:"test-start", file, nodeid, name}, {ev:"test-end", file, nodeid, status}, {ev:"file-end", file, result: FileRunResult}, {ev:"coverage", file} / {ev:"coverage-off", reason}, {ev:"session-end", exit}. --ltr-result=<file>: the RunResult (+ exitStatus); $LTR_PYTEST_LIST: {files, errors, rootdir, inifile, python_files, testpaths} of a --collect-only run; $LTR_PYTEST_COVERAGE=<dir>: coverage-final.json (istanbul-shaped) and trace.jsonl (T per test from CoverageData.contexts_by_lineno, H hk:"file" for import-time lines).
The files that run inside the test process live in src/session/instrumentation/ and are copied, with the same layout, to out/instrumentation/ (they cannot be bundled; the runners pass their absolute paths to the framework):
| Folder | File | Role |
|---|---|---|
shared/ |
sessionTraceRuntime.js |
The __strace runtime — framework-neutral |
shared/ |
testDiscovery.js |
Static AST test discovery (bundled into the extension, not run in the test process) |
jest/ |
sessionTraceTransform.js |
Jest transform: Babel-instruments source files with __strace.step() calls and __cov counters, writes coverage manifests |
jest/ |
ltrCoverageSetup.js |
setupFilesAfterEnv: opens/closes the trace context around each test, flushes __cov on exit, test heartbeats |
jest/ |
liveReporter.js |
Reporter: one JSONL record per finished file (start record when a file begins) |
vitest/ |
vitestTraceConfig.js |
Helper of the wrapper config (--config): loads the project's config with its own Vite, adds the plugin to every test.projects entry, writes per-project wrappers, reports to LTR_VITEST_TRACE_MARKER
|
vitest/ |
vitestTracePlugin.js |
Vite plugin live-test-runner:trace: setup file first in test.setupFiles, server.fs.allow, resolveId('vitest') for the setup file, enforce: 'post' transform |
shared/ |
sourceMapLookup.js |
Reads a v3 source map back (generated → original line / column; other sources ignored) — Jest and Vitest transforms |
vitest/ |
vitestTraceTransform.js |
Pure: parse (@babel/parser), splice globalThis.__strace?.step(L, F) calls, source map; withoutTrace() undoes it |
vitest/ |
vitestTraceSetup.mjs |
Setup file: per-test trace context (beforeAll / beforeEach / afterEach / afterAll), F record, Function.prototype.toString without the inserted calls |
Vitest's results come from the runner's reporter (framework/vitestReporter.ts) and its coverage from Vitest's own provider; only the trace uses vitest/. The contract a framework keeps:
-
globalThis.__strace(defined once per worker bysessionTraceRuntime.js):beginFile(testFile)— module-level code of the test file starts;beginTest(name, testFile)/endTest(testFile)— around each test body (between tests the context ishook);enterTest/exitTest/enterHook(type, testFile)/exitHook— injected wrappers, nest into the open context;step(line, file)— instrumented code hit a line;finish()— flush the last context.var()/log()are no-ops here (Timeline only). -
Trace records — JSONL appended to
SESSION_TRACE_FILE, one per test body / hook block:{"type":"T","tf":"<test file>","tn":"<full test name>","fh":{"<source file>":[lines…]}}and{"type":"H","tf":…,"hk":"file"|"hook"|<hook name>,"fh":{…}}; Vitest's setup adds{"type":"F","tf":…}when it ran for a test file. WithLTR_TRACE_PER_WORKER(Vitest's parallel workers) each worker appends to<SESSION_TRACE_FILE>.<pid>-<threadId>.tnis the space-joined full name (ResultStore's). Paths are the runner's real paths;session/traceRecords.ts(applyTraceRecords, both frameworks) maps them back (fromRunnerPath) and builds theExecutionTraceStoreindexes. -
Vitest trace on/off —
VitestTrace(extension) writes the wrapper per root and session, or keeps it off with a reason (liveTestRunner.vitestTrace, Vitest < 3, no Vite, the marker'sok: false, a traced batch with no result → rerun as configured, a result without anFrecord — type-check results, taggedtypecheckby the reporter, are exempt). Vitest 3 workspaces (vitest.workspace.*,test.workspace) are loaded by the wrapper and passed inline astest.workspace, each entry wrapped liketest.projects. -
Source files beyond JS / TS (
session/sourceFiles.ts) — a save reruns tests for the list (.vue,.svelte,.astro,.marko,.mdx,.coffee, …), the Jest config'smoduleFileExtensions(IProjectConfig.sourceExtensions) or any file the trace saw run; never forNON_SOURCE_EXTENSIONS. The coverage scan counts untested components from their<script>blocks (scriptOf). Vitest: the plugin has no list — it instruments any compiled module whose combined map leads back to the file (mapsBackTo), after its Vite plugin. Jest: the batch config routes them to the session transform only for extensions the project transforms; it runs the project's transformer (sync, orprocessAsync/import()for ESM-only ones) and instruments the output with every location moved back through the transformer's map (remapLocations; unmapped compiler code is not counted; a Vue render function marks the<template>lines as run — trace only). Both read maps withshared/sourceMapLookup.js. -
Module graph (Vitest) — the trace plugin writes Vite's module graph when Vitest closes its server (
LTR_VITEST_DEPS→traceRecords.applyDependencyFiles→ExecutionTraceStore.addImporters); a save of a file no line of which ran (HTML,?raw, plugin-read templates) rerunsgetDependentTestFiles. Jest has no graph: a non-JS file nothing knows reruns the tests of same-folder sources that name it ('./x.html',SessionManager.referencingSources). A Vitest root with type-check files also runsvitest related <src> --typecheck.onlyafter a trace rerun. -
Jest: our files are never transformed —
transformIgnorePatternsgets the extension's instrumentation folder (ownFilesPattern). Transformers that reject instrumented code (type-checking: ts-jest, jest-preset-angular, or seen failing) are compiled first; their map (returned or inline) moves locations back to the source. -
Jest ESM mode — the test script's and
.npmrc's Node options (runnertestScriptNodeOptions/npmrcNodeOptions/jestNodeEnv;jestEsmHintfor load errors) go intoNODE_OPTIONSof every Jest the extension starts (runtimeArgswhen debugging); withsupportsStaticESMthe transform loads the runtime withimportinstead ofrequire.FrameworkServices.traceOffReason(root)exposes it toSessionManager(saves usevitest related) and the hover. -
Coverage (Jest) — instrumented code counts into
globalThis.__cov[<file hash>].s/b/f; on exit each worker appends{"workerPid":…, "cov":{…}}toCOVERAGE_OUTPUT_FILE; the transform writes a manifest per file (statement / branch / function locations) toLTR_MANIFEST_DIR, named by path + content hash. -
Per-file results — JSONL appended to
LTR_REPORTER_FILE:{"ltrEvent":"start","testFilePath","at"}when a file begins, then the file's result (testFilePath,status,testResults[],console[],startTime/endTime) when it ends; the batch runner polls this file every 200 ms. -
Logging —
[LTR:<level>] messagelines on stderr, filtered byLTR_LOG_LEVEL(see developer guide → Logging).
DecorationManager owns all TextEditorDecorationType instances. Applied to visible editors after each run, after discovery, and when an editor becomes active.
Gutter icons are SVG files in resources/icons/:
| Icon | File | Meaning |
|---|---|---|
| ✓ green | passed.svg |
Test passed |
| ✗ red | failed.svg |
Test failed |
| ⟳ amber | running.svg |
Test running (SVG animateTransform) |
| ○ grey | pending.svg |
Not yet run / discovered but not run |
Inline duration text appears after each test line, colour-coded by configurable thresholds.
Lifecycle:
- Extension activates →
CodeLensProviderregistered;TestDiscoveryServicestarts - Discovery progresses →
DecorationManager.onDiscoveryProgress()→_refreshAll()applies pending icons to visible editors;CodeLensProvider.onDiscoveryProgress()→refresh()surfaces▶ Run/▷ Debuglenses immediately - Discovery completes → same refresh path
- File result arrives →
LineMaprebuilt with Jest's authoritativelocation.line, decorations refreshed for that file - Editor becomes active → decorations applied from existing
LineMap - Session stops →
decorationManager.clearAll()resets all icons (decoration types are kept alive so pending icons from discovery survive)
CoverageDecorationManager (src/editor/CoverageDecorationManager.ts) — dedicated manager for coverage gutter decorations. Completely separate from DecorationManager; uses its own TextEditorDecorationType instances.
Three thin vertical bar states per executable line (3px wide rect, distinct from debug breakpoints which are filled circles):
| Decoration | Trigger | Visual |
|---|---|---|
| Covered | Line executed, all branches taken | Solid green bar |
| Partial | Line executed, ≥1 branch arm never taken | Amber bar |
| Uncovered | Line never executed | Dim red bar |
| Stale tint |
'measured-stale' entry (file saved, rerun pending) |
Subtle grey backgroundColor tint over entire file — bars remain visible underneath |
| Not yet run |
'counted' entry |
Nothing shown |
Line classification reads the coverage manifest (statement IDs + locations, branch IDs + arm counts) and counters (s, b, f) from CoverageEntry. A line is partial when it has ≥1 branch whose arm count array contains a zero; otherwise if hit count > 0 it is covered; if hit count = 0 it is uncovered. Functions without dedicated decoration — an uncovered function's declaration line shows as uncovered (red bar).
Subscribes to CoverageStore.onDidChange and redraws all visible editors on each change. Reads the coverage manifest from disk on demand (path stored in the CoverageEntry) to get per-line hit data. Clears on session stop.
CodeLensProvider scans files with a regex (no AST) to find describe, it, and test blocks:
/^\s*(describe|it|test)\s*[\.(]/
Three lenses per block:
-
▶ Run— reruns this scope (liveTestRunner.rerunFromEditor) -
▷ Debug— launches Jest under debugger (liveTestRunner.debugFromEditor) -
◈ Results— focuses the results panel (liveTestRunner.focusResult) — only onit/testlines with a known result
CodeLensProvider is registered on extension activate (not on session start). It is always present — lenses appear as soon as discovery populates a LineMap entry for the file. Disposing the provider registration only happens on full extension deactivation.
Both views extend BaseWebviewProvider, which handles webview lifecycle, postMessage routing, and the IResultObserver base.
ExplorerView (sidebar) — always visible during a session. Shows the recursive file → node tree (unlimited nesting) with live status icons, duration badges, search, and per-row rerun buttons.
ResultsView (editor panel) — three resizable columns:
┌─────────────────┬──────────────────────────┬────────────────────────┐
│ Col 1: Tests │ Col 2: Output │ Col 3: Errors │
│ │ [All][Log][Info][Warn] │ │
│ File │ [Error] │ ✗ test name │
│ Suite │ │ <failure message> │
│ ✓ test │ 📄 file.test.ts just now│ │
│ ✗ test │ console.log output here │ ✗ test name 2 │
│ │ │ <failure message> │
│ │ 🔹 failing test 5s ago │ │
│ │ console.log from test │ │
└─────────────────┴──────────────────────────┴────────────────────────┘
Column 1 — same test list layout as the sidebar. Clicking a row scopes columns 2 and 3. Selection syncs between both views — selecting in either the sidebar or results panel highlights the same row in both.
Column 2 — log output scoped to the selected row, filtered by level tab (All / Log / Info / Warn / Error). Each scope that has output shows a header with icon, label, and timestamp. Empty scopes show a placeholder.
Column 3 — failure entries scoped to the selected row. Each entry shows the test name (red) and raw failure message in a monospace block.
Scoping rules:
| Selection | Output sections shown | Errors shown |
|---|---|---|
| File row | File section always. Suite/test sections only if individually rerun. | All failures in the file |
| Suite row | Suite section always (placeholder if empty). Test sections only if individually rerun. | All failures in the suite |
| Test row | Test section always (placeholder if empty). | That test's failure, or "No failures" |
Copilot, Cursor and terminal agents (Claude Code, Codex, Gemini CLI…) read results and run tests through one set of LTR_ tools: ai/catalog.ts defines them, ai/tools.ts (AiTools) answers them from the stores and acts through SessionManager (rerunScope, runFiles, runChangedFiles). Two ways in:
-
VS Code language-model tools (Copilot):
AiBridgeregisters each catalog tool withvscode.lm.registerTool(feature-detected; package.json'slanguageModelToolsis generated from the catalog). In-process, no transport. -
MCP (Cursor, terminal agents):
out/mcp.js, a stateless stdio relay bundled on its own (onlyfs/os/path/crypto), forwards eachtools/callthrough a file mailbox in the window's session folder (bridge.json,bridge/requests/,bridge/responses/). Cursor registers it withvscode.cursor.mcp.registerServerand the exact session folder; terminal agents start it through a launcher in the extension'sglobalStorage(stable across updates), which finds the window whose folders hold the agent's folder.
AiBridge is an editor observer (results, Start, Stop); nothing is built before a request arrives. No socket, no port, no AI call (rule 11). Failing tests are also published as Diagnostics (editor/FailureDiagnostics.ts), so editors' own AI quick fixes apply; Fix with AI opens the chat (workbench.action.chat.open) or copies the failure. Details: AI assistants: design.
| Type | Direction | Purpose |
|---|---|---|
full-file-result |
Extension → both | Complete file result tree; drives column 1 |
scope-changed |
Extension → both | Row selection changed; highlights new row |
scope-logs |
Extension → results only | Log + error data for the selected scope; drives columns 2 & 3 |
run-started |
Extension → both | Resets UI for a full run |
files-rerunning |
Extension → both | Marks specific files as running (partial rerun) |
init |
Extension → both | Sends configurable thresholds on session start |
select |
Webview → extension | User clicked a row |
rerun |
Webview → extension | User clicked a rerun button |
open-file |
Webview → extension | User wants to open a file in the editor |
ready |
Webview → extension | Webview signals it has initialised |
route |
Extension → both | Switch view: { type: 'route', view: 'timeline' | 'results' | ... }
|
timeline-loading |
Extension → ResultsView | Show spinner while instrumented run is in progress |
timeline-ready |
Extension → both | Instrumented run complete; carries serialised TimelineStore
|
timeline-error |
Extension → ResultsView | Instrumented run failed |
timeline-exited |
ResultsView → extension | User navigated away from timeline mode |
step-changed |
ResultsView → extension | User stepped to a new step; carries stepId, filePath, line
|
step-update |
Extension → ExplorerView | Forward of step-changed to sync sidebar panels |
timeline-rerun |
ExplorerView → extension | User clicked Re-run in the timeline sidebar |
projects |
Extension → ExplorerView | Project list + live state for the switcher row (also in init) |
select-project |
ExplorerView → extension | User picked a project in the switcher (liveTestRunner.selectProject) |
scope-logs and scope-changed are always sent as separate messages.
Key design boundary: playback state lives entirely in the ResultsView webview (PlaybackEngine). The extension host receives step-changed events and reacts (editor highlight, sidebar sync). The extension host never drives playback. Column 1 updates on every run. Columns 2 and 3 update on selection changes or when a run completes for the currently selected scope. Keeping them separate avoids unnecessary re-renders.
Per-level, user-configurable via liveTestRunner.durationThresholds.*:
| Level | Green | Amber | Red |
|---|---|---|---|
| test | < 100 ms | 100–500 ms | > 500 ms |
| suite | < 500 ms | 500–2000 ms | > 2000 ms |
| file | < 1000 ms | 1000–5000 ms | > 5000 ms |
Threshold logic lives in src/utils/duration.ts (TypeScript) and is mirrored in src/webview/utils.js (plain JS globals for the webview sandbox). The extension reads current settings via getThresholds() and passes them to each webview in the init message.
Extension activates
→ extension.ts
→ CodeLensProvider registered (always active)
→ TestDiscoveryService.start()
→ vscode.workspace.findFiles → test file paths
→ Batches of 8 files, setImmediate yield between batches:
→ Read source → discoverTests() (AST) → store.fileDiscovered/suiteDiscovered/testDiscovered
→ LineMap built from AST line numbers
→ onFileDiscovered callback → IResultObserver.onDiscoveryProgress()
→ ExplorerView.postMessage(discovery-progress) → test tree builds live
→ ResultsView.postMessage(discovery-progress) → test list builds live
→ DecorationManager._refreshAll() → pending ○ icons appear
→ CodeLensProvider.refresh() → ▶ Run / ▷ Debug lenses appear
→ onComplete → IResultObserver.onDiscoveryComplete()
→ Start Testing re-enabled
User clicks "Start Testing"
→ extension.ts → SessionManager.start()
→ TestDiscoveryService.awaitDiscovery() (no-op — already done)
→ file paths read from ResultStore
→ SessionManager._runFiles(all) warm-up run
→ For each file (up to 3 in parallel):
→ JestRunner
→ FrameworkDetector detects: jest | cra | …
→ FrameworkAdapter resolves binary + config
→ Executor spawns jest --json --outputFile=<tmp>
→ ResultParser parses JSON → RunResult
→ JestAdapter._applyFileResult() writes to ResultStore + LineMap (replaces AST line numbers with Jest's authoritative location.line)
→ IResultObserver.notify() → ExplorerView, ResultsView, DecorationManager
→ On-save listener enabled
**Session Isolation** — every window uses a unique `session-<pid>-<ts>` directory. The extension host creates this on startup and injects it into all internal components (`SessionManager`, `JestAdapter`, `JestBatchRunner`). This ensures that multiple VS Code windows never conflict on shared temporary filenames.
User saves a file
→ SessionManager.onSave(filePath) debounced 300ms
→ services.isConfigFile(filePath)? (jest.config.* / vitest.config.* / vite.config.* / the script's --config)
→ Yes: restart the session — config, runnable files and every result re-read
→ isTestFile(filePath)?
→ Yes: run that file
→ No: _runAffectedBySourceFile(filePath)
ExecutionTraceStore.getAffectedTestFiles(filePath)?
→ Has trace data:
isSharedVars:true → run whole test file
isSharedVars:false → run individual test cases
(combined --testNamePattern, one Jest process per file)
(a file where every non-skipped test is affected runs whole, as a batch)
→ No trace data, or the framework's trace is off for the root
(services.traceOffReason — Vitest: see VitestTrace):
batchRunner.runRelated? (Vitest: `vitest related <src> --run` as a live batch —
files claimed on file-start, results streamed, coverage measured,
started-without-result files retried through _runFiles)
else adapter.runRelatedTests (plain `jest --findRelatedTests`) → whole files
User clicks "▶ Run" CodeLens
→ liveTestRunner.rerunFromEditor(filePath, lineNumber)
→ it/test line: LineMap lookup → rerun that test via --testNamePattern
→ describe line: regex extracts suite title → reruns suite via --testNamePattern
→ unresolved: runs whole file
User clicks "▷ Debug" CodeLens
→ liveTestRunner.debugFromEditor(filePath, lineNumber)
→ resolves scope same as rerun
→ vscode.debug.startDebugging({
program: jest binary,
args: [filePath, --runInBand, --no-coverage, --testNamePattern <name>],
})
User clicks "◈ Results" CodeLens
→ liveTestRunner.focusResult(fileId, suiteId, testId)
→ reveals Test Results panel
→ selectionState.select() → scope-changed broadcast → row highlighted in both webviews
User stops session
→ decorationManager.clearAll() gutter icons cleared; decoration types kept alive
→ child processes killed
→ on-save listener disabled
(CodeLensProvider remains registered; LineMaps and pending icons are preserved)
| Decision | Reason |
|---|---|
--outputFile preferred over stdout |
Prevents Windows pipe-buffering from truncating large JSON. Stdout is still captured and used as a fallback — CRA occasionally writes JSON to stdout on a bailed run instead of to the output file. |
CRA: extract config via --showConfig, run Jest directly |
Full flag control — --json, --outputFile, --no-bail all work; react-scripts strips them |
All binaries resolved from project node_modules
|
Never a global binary; projects with different Jest versions don't conflict |
| In-memory CRA config cache per session |
--showConfig takes 2–3s; cached, invalidated if package.json changes |
FrameworkAdapter interface in both packages |
Adding a framework = one file in each package, nothing else |
TestRunner interface for extension-runner boundary |
Extension never imports concrete runner classes |
scope-logs separate from scope-changed
|
Different lifecycles — avoids unnecessary re-renders in columns 2 and 3 |
| Output stored at run scope, never back-filled | Jest JSON only reports console at file level; correct attribution, no fabricated data |
| Custom webview, not VS Code Test Explorer API | Avoids a Mac-specific API bug; full cross-platform control |
| Regex line scan for CodeLens (no AST) | Simpler, no parse overhead; sufficient for line-level describe/it/test detection |
| Static AST discovery on activate, not on Start Testing | Full test tree (with line numbers, pending icons, and CodeLens) appears immediately on project open. Start Testing only needs to run tests — it skips discovery entirely by awaiting the already-resolved awaitDiscovery() promise. |
Batch + setImmediate yield for discovery |
Parsing 500+ files in one synchronous pass would block the extension host. Batches of 8 with a yield between each keep the UI responsive while the tree builds progressively. |
| Watcher re-discovers on any non-running status | Skipping only 'running' files (not pending/passed/failed) means newly added tests appear in the tree on the next save, without waiting for a full re-run. |
fileStarted preserves pre-discovered structure |
When a file is already in the store (from discovery), fileStarted reuses the existing node tree and only marks entries running. The tree never disappears or resets mid-run. |
DecorationManager.clearAll() instead of dispose() on session stop |
Decoration types stay alive so pending icons from discovery survive session stop/start cycles. dispose() is reserved for full extension deactivation. |
LineMap stores identity only |
Status and duration always read from ResultStore — single source of truth, never stale |
extension.ts ≤ 110 lines |
Wires instances and registers commands only; no business logic |
| Parallel batches = a quarter of the CPU cores | Balances throughput against system load; the machine stays responsive |
| Session guard on all background behavior | No surprise background work; resource usage is predictable |
One ProjectContext (stores, discovery, services, SessionManager) per project; views bound to the selected one |
File ids stay naturally namespaced, background projects keep running untouched, single-project behaviour is unchanged |
| A root with its own test config is one project, never split per package | Its config already runs its packages (Jest projects, Vitest test.projects); splitting would run tests twice or with the wrong config |
Projects are detected, never started automatically; maxRunningProjects caps active sessions |
A monorepo with 30 packages must not spawn 30 test runners on open |
step-changed boundary: playback in webview, editor in host |
PlaybackEngine drives the timeline UI inside the webview sandbox. The extension host only reacts to step-changed — it never drives playback. This keeps the playback loop fast (no round-trips) and the editor highlight authoritative. |
TimelineDecorationManager separate from DecorationManager
|
Timeline decorations (whole-line highlight, ghost text, hover) never touch pass/fail gutter icons. Two completely independent TextEditorDecorationType sets. |
| Webview router instead of new tabs | Both ResultsView and ExplorerView implement an internal JS router. Timeline mode is a view swap inside an existing panel — no new VS Code panel is registered. |
| AI assistants: a file mailbox, not a socket; a stateless stdio relay; one handler class for LM tools and MCP | Keeps "no net module" absolute; all logic stays in the window; tools cannot drift between Copilot and MCP agents (design) |
logPanel.js / errorPanel.js as shared components |
Same rendering code in both normal and timeline modes. Extracted from resultsView.js and consumed by timelineView.js without modification. |
Source: docs/development/architecture.md. This Wiki is generated from the repository; to change a page, open a pull request that edits its file in docs/.
Features
- Test runs
- Test Explorer and editor
- On-save reruns
- Results panel
- Coverage
- Debugging
- Monorepos and mixed frameworks
- AI assistants
Requirements
- Project-wide requirements
- Test runs: requirements
- Test Explorer and editor: requirements
- On-save reruns: requirements
- Results panel: requirements
- Coverage: requirements
- Debugging: requirements
- Monorepos and mixed frameworks: requirements
- AI assistants: requirements
Development
- Developer Guide
- Architecture
- Framework feature matrix
- AI context
- Feature designs
Generated from docs/. Edits made here are overwritten: change a page with a pull request.