Repository navigation
AI context
Paste this document into a conversation to give an AI assistant complete knowledge of the Live Test Runner codebase — what it is, how it works, where everything lives, and the rules that govern it.
Live Test Runner is a VS Code extension that runs Jest tests automatically on file save and shows results directly in the editor. It is a Wallaby-lite tool — session-based, explicit start/stop, focused on speed.
Current version: 1.5.0
Language: TypeScript
Package manager: pnpm (monorepo)
src/
└── TestSession.ts Whether a session is on (activate / stop) + its runner
Which tests a saved source file reruns is decided in the extension (SessionManager._runAffectedBySourceFile): the execution trace, then the framework's related run. (The old CoverageMap / SelectionPolicy were dead code and were removed in 3.3.0.)
Framework-agnostic execution engine. VS Code layer depends only on the TestRunner interface.
src/
├── types.ts Framework enum, Status enum, result types
├── TestRunner.ts Interface the extension uses (+ RunnerOptions)
├── CommandRunner.ts Generic CLI runner: binary/config/extra args, chunking, kill, coverage; abstract buildArgs(RunRequest)
├── JestRunner.ts extends CommandRunner — Jest flags only
├── VitestRunner.ts extends CommandRunner — `run|list|related` + files as leadingArgs; toVitestNamePattern (" " → "(?: > | )")
├── framework/
│ ├── FrameworkRegistry.ts register(adapter, priority); default(): CRA 300 → Vitest 200 → Jest 100 (built lazily)
│ ├── FrameworkDetector.ts First matching registry adapter; detectWithReason(); unknown → plain Jest + one WARN
│ └── adapters/
│ ├── FrameworkAdapter.ts Interface: detect, resolveBinary, resolveConfig, getExtraArgs, outputFileArg, parseResult, capabilities, createRunner
│ ├── JestAdapter.ts Plain Jest + Next.js + Jest
│ ├── CRAAdapter.ts Create React App
│ ├── AngularAdapter.ts Angular: angular.json unit-test builder (Vitest runner) → ng.js test <project>; runner = AngularRunner (extends VitestRunner; per-project commands, runner config in the session folder, CI=true)
│ └── VitestAdapter.ts Vitest: detect (no Jest marker), vitest.mjs, config, version → capabilities, Node check; runner = VitestRunner
│ ├── UnsupportedFrameworkError.ts
│ ├── refusingAdapter.ts stand-in adapter a runner keeps for another framework's project
│ ├── vitestConfig.ts testScriptVitestArgs: config-relevant flags of the test script (follows nr/npm run/pnpm)
│ ├── vitestProjects.ts vitestProjects(): projects + browser flag via the project's own Vitest node API (browser-mode guard)
│ └── vitestTrace.ts viteEntryFor / vitestDirFor: the project's own Vite for the trace wrapper config
├── resolution/
│ ├── BinaryResolver.ts Finds jest binary in project node_modules
│ └── RunnerPaths.ts Symlinked roots: editor path ↔ the test runner's realpath
├── execution/
│ └── Executor.ts Spawns the runner (below normal priority), reads its result file (flag from adapter.outputFileArg) on exit
└── parsing/
├── ResultParser.ts Parses Jest JSON output → RunResult (adapter.parseResult for Jest/CRA)
├── VitestResultParser.ts parseVitestResult: Vitest 1–5 json reporter → RunResult (fixtures: test/fixtures/vitest)
├── runResults.ts emptyRunResult / mergeRunResults — any framework
└── mergeFileResults.ts Merges reports of one file run by several Jest projects
Process model: Jest is always node <jest/bin/jest.js> (BinaryResolver.resolveJestEntry, CRA: resolveCraJestEntry) with no shell — Windows .cmd shims broke arguments and paths with spaces. nodeRuntime() prefers node on PATH. Executor.kill() kills the process tree; timeoutMs stops a hanging run. Path arguments: forward slashes + upper-case drive (toJestPathArg).
Batch run command (JestBatchRunner — initial run and 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 generated config starts from the project's config as Jest resolves it (JestProjectConfig: jest --showConfig / react-scripts test --showConfig, once per session, JSON in the session dir, path passed as LTR_JEST_RESOLVED_CONFIG) plus the items below. Its text is the same for every batch and session (writeStableConfig, file named by content hash): Jest keys its transform cache and file map on the config path, so a per-batch path meant no reuse at all.
- Jest's own coverage on (
collectCoverage, the project'scoverageProvider,coverageReporters: ['none'], emptycollectCoverageFrom): the numbers are whatjest --coveragereports -
sessionTraceTransform.jsat the front of the transform chain (light trace only, on the output of the project's transformer, which instruments for Jest's coverage — orinstrumentLikeJestdoes when it cannot; a source map back to the file) -
ltrCoverageSetup.jsas the firstsetupFilesAfterEnventry — coverage flush, per-test trace context (beginTest/endTest), test-start/end heartbeats for the hang watchdog -
liveReporter.jsas an extra reporter that appends astartrecord and one result record per file to a JSONL file, and each test file's coverage as Jest reports it (jestCoverage.perTestFile) toLTR_JEST_COVERAGE_FILE
The parent process polls that JSONL file at 200 ms intervals via Executor.runWithReporterPolling, firing a callback per record so the UI updates while Jest is still running. Reported and traced paths are mapped back to store keys.
Run lifecycle (SessionManager): runs register in a registry — one onRunProgress total and one onRunFinished across overlapping runs; a session token makes Stop final. jest --listTests at session start decides which discovered files are runnable (others: skipped, file.excluded).
Single-test / scoped-rerun command (JestRunner — CodeLens and individual reruns):
jest --config <resolved> --watchAll=false --forceExit --no-bail --json \
--outputFile=<tmpfile> --testLocationInResults [--testNamePattern <name>]--outputFile is mandatory here. Never parse Jest's stdout — on Windows, large JSON is silently truncated through pipes.
CRA: CRAAdapter.resolveConfig() runs react-scripts test --showConfig --passWithNoTests once per session, extracts the hidden Jest config JSON, writes it to a temp file, then all runs invoke Jest directly. react-scripts is never used at run time. Config is cached in memory; invalidated if package.json changes.
Result types (framework-agnostic — all runners produce these shapes):
RunResult
FileRunResult
TestCaseRunResult
status: 'passed' | 'failed' | 'pending' | 'todo' | 'skipped'
duration?: number
location?: { line: number, column: number }
failureMessages: string[]
ancestorTitles: string[]
ConsoleEntry // console output per file; Vitest adds scope ('file'|'suite'|'test') + scopeName
message: string
type: string // 'log' | 'warn' | 'error' | 'info' | 'debug'
origin: stringDeprecated aliases — JestJsonResult, JestFileResult, JestTestCaseResult, JestConsoleEntry remain exported for backward compatibility. Do not use in new code.
src/
├── extension.ts Entry point — wires views + ProjectRegistry, registers commands
├── project/ Monorepos & multi-root workspaces
│ ├── ProjectRegistry.ts Detects the projects (runner findTestProjects / projectRoot setting), owns one ProjectContext each, the selected one, status bar text, start limit
│ ├── ProjectContext.ts Per project: ResultStore / ExecutionTraceStore / CoverageStore, TestDiscoveryService + DiscoveryCache, FrameworkRouter, SessionManager, session dir; ProjectObserverGate (forwards events only while selected)
│ └── projectLimits.ts maxRunningProjects: auto (2, or 1 with ≤ 4 cores / < 8 GB total memory) and the refusal message (pure)
├── IResultObserver.ts Interface: onSessionStart/Stop, onRunStart, onFileResult,
│ onDiscoveryStarted/Progress/Complete (optional)
├── store/
│ ├── ResultStore.ts In-memory File→Node tree (recursive) + LineMap + ScopedOutput
│ ├── ExecutionTraceStore.ts Trace indexes: traceIndex, coverageIndex, sourceToTests, lineToTests; forgetTestFiles() before a whole-file rerun's records
│ └── SelectionState.ts Tracks selected row; broadcasts scope-changed
├── coverage/
│ ├── types.ts Manifest, FileCov, LiveCov, CoveragePct, CoverageTotals, CoverageEntry
│ ├── CoverageStore.ts One contribution per test file (latest run, on disk in coverage-contrib/), summed per source version and replaced on rerun; 'counted' → 'measured' → 'measured-stale' (changed, its tests not rerun yet); outdatedContributors() drives SessionManager's coverage refresh
│ ├── SourceCounter.ts Background scan at session start; populates CoverageStore with 'counted' entries; countFile() for files created / edited later
│ ├── coverageScope.ts Which files count toward coverage, from the project's coverage config (IProjectConfig.coverageScope)
│ └── CoverageReport.ts Stateless metric calculation (statements/branches/functions/lines)
├── cache/
│ └── DiscoveryCache.ts Persistent Babel parse cache (mtime-keyed, per-project, LRU rotation)
├── session/
│ ├── SessionManager.ts Session lifecycle, batched run pool (parallelBatches(): cpus/4; another batch waits while memoryLow()), on-save, rerun
│ ├── batchQueue.ts A run's batch queue: per framework, open test files first (full run), promote a file opened while it waits
│ ├── ExternalChanges.ts Files changed on disk outside the editor (git pull, branch switch): drops the editor's own saves, batches 500 ms → SessionManager.onFilesChangedOnDisk (>20 files restart, never for changes from our own runs; changes during our runs — by queue, or by modified time when reported late — rerun once when they end; files no test loaded and unrun test fixtures are dropped)
│ (cache/Storage.ts) Every cached path in one place: per-project clear (Stop and Clear Cache), Clear All Cached Data, 30-day pruning on activation
│ ├── IProjectConfig.ts Interface: the project's resolved runner config (get / reset)
│ ├── JestProjectConfig.ts IProjectConfig for Jest: `jest --showConfig` once per session
│ ├── IBatchRunner.ts Interface: runFiles(BatchRunOptions) / kill / reset — SessionManager's only view of batch runs
│ ├── JestBatchRunner.ts Runs combined test+trace+coverage batches; populates ResultStore + ExecutionTraceStore + CoverageStore
│ │ instrumentation/ (protocol: docs/development/architecture.md → Session instrumentation protocol)
│ │ ├── shared/
│ │ │ ├── sessionTraceRuntime.js __strace global: accumulates hit-maps per test/hook; flushes T/H records to JSONL — framework-neutral
│ │ │ ├── sourceMapLookup.js reads a source map back (generated → original line/column) — Jest + Vitest transforms (TS, components)
│ │ │ └── testDiscovery.js Static AST test discovery (bundled; used by TestDiscoveryService)
│ │ ├── jest/
│ │ │ ├── sessionTraceTransform.js Jest transform: injects __strace.step() (trace) on the project transformer's output (which carries Jest's coverage); a source map back to the file; components via the project's transformer + its map; processAsync (ESM). Own __cov counters only without Jest's coverage
│ │ │ ├── ltrCoverageSetup.js setupFilesAfterEnv: trace context per test, __cov flush per test file (tagged `tf`), heartbeats
│ │ │ ├── liveReporter.js Custom Jest reporter: one JSON record per completed file, and its coverage as Jest reports it
│ │ │ ├── jestCoverage.js Jest's coverage per test file, converted as Jest's CoverageReporter does (babel / v8); files no test loads via Jest's generateEmptyCoverage
│ │ │ └── jestCoverageCount.js child process: counts files no test loads with jestCoverage.countUntested
│ │ └── vitest/ Vitest execution trace
│ │ ├── vitestTraceConfig.js wrapper-config helper: project config via its own Vite + plugin into every test.projects / Vitest 3 workspace entry
│ │ ├── vitestTracePlugin.js Vite plugin: setup file first, enforce:'post' transform of project sources (JS/TS + .vue/.svelte/.astro/.marko)
│ │ ├── vitestTraceTransform.js splices globalThis.__strace?.step(L,F) (lines via the incoming source map); withoutTrace()
│ │ ├── vitestTraceSetup.mjs per-test context (beforeEach/afterEach), F record, Function.prototype.toString without the calls
│ │ └── vitestCoverageProvider.mjs coverage.provider=custom: the project's own v8 / istanbul provider, plus coverage per test file (its generateCoverage per coverageFiles entry); Vitest via the trace wrapper, Angular via its runner config
│ ├── VitestBatchRunner.ts IBatchRunner for Vitest: one process per batch, results streamed per file (reporter events), per-test hang limit, Vitest coverage → CoverageStore, execution trace (per-worker trace files → traceRecords)
│ ├── VitestTrace.ts Vitest trace on/off per root + the wrapper config (ltr.vitest.config.mjs → instrumentation/vitest/)
│ ├── sourceFiles.ts which files are source code: JS/TS + components (.vue/.svelte/.astro/.marko); scriptOf() for the coverage scan
│ ├── traceRecords.ts applyTraceRecords: T/H/F trace records → ExecutionTraceStore (Jest and Vitest)
│ ├── VitestProjectConfig.ts IProjectConfig for Vitest: the config file path
│ └── TestDiscoveryService.ts Static AST discovery on activate + FileSystemWatcher (BATCH_SIZE_COLD=5, BATCH_SIZE_WARM=25)
├── framework/
│ ├── IFrameworkAdapter.ts detect, discoverTests, isTestFile, runFile, runTestCase,
│ │ runRelatedTests, getDebugConfig
│ ├── FrameworkServices.ts FrameworkServices bundle + IFrameworkServicesProvider (servicesFor / all / prepare / listTestFiles / restore / fileChanged / fingerprint / isMixed / frameworks) + SingleFrameworkProvider (unit tests)
│ ├── FrameworkRouter.ts Per project: one bundle, or Jest + Vitest in a mixed project — places each test file (setting → configs' lists → imports / calls → main framework + WARN)
│ ├── jestServices.ts createJestServices(): the Jest bundle (adapter, JestProjectConfig, JestBatchRunner, JestInstrumentedRunner, session runner)
│ ├── vitestServices.ts createVitestServices(): adapter, VitestProjectConfig, VitestBatchRunner (+ VitestTrace), features.trace, traceOffReason, no instrumented runner
│ ├── RunnerBackedAdapter.ts Shared IFrameworkAdapter half: file / test-case / related runs, FileRunResult → ResultStore
│ ├── JestAdapter.ts Jest detection, JestRunner (jestCommand / runMode), debug config
│ ├── AngularAdapter.ts / angularServices.ts Angular: debug via ng test, AngularBatchRunner (split by Angular project over VitestBatchRunner; saves → importing test files via session/jsImporters.ts), html as source (templateUrl)
│ └── VitestAdapter.ts Vitest detection, VitestRunner (vitestCommand), debug config (autoAttachChildProcesses)
├── editor/
│ ├── CodeLensProvider.ts ▶ Run / ▷ Debug / ◈ Results / ⏱ Timeline via regex line scan
│ ├── DecorationManager.ts Gutter icons + inline duration text
│ (views/copyText.ts: Copy all / Copy for AI / Copy Failing Test Names texts; ResultsView.copyFailures → vscode.env.clipboard)
│ ├── updateSnapshot.ts Update snapshot (hover link): modal dialog naming the file (never skipped outside e2e), then rerunScope({ updateSnapshots }) → RunRequest.updateSnapshots (Jest --ci=false --updateSnapshot, Vitest --update)
│ ├── failureInfo.ts / FailureDecorations.ts A failed test's message after its failing line (test + thrown-from source line); hover: message, Show diff (ltr-failure: docs → vscode.diff), Open in Results, Dismiss; hidden on edited lines; liveTestRunner.showFailuresInEditor
│ ├── CoverageDecorationManager.ts Coloured left-edge bar (whole-line border, no text shift) per executable line: green=covered, amber=partial, red=uncovered; stale overlay (grey tint) when rerun is pending; follows unsaved edits via MeasuredLines; hidden by liveTestRunner.showCoverageInEditor
│ ├── MeasuredLines.ts / lineMatch.ts Matches the editor's current lines to the lines coverage was measured on (prefix/suffix + LCS), shared by bars and hover
│ └── CoverageHoverProvider.ts HoverProvider for JS/TS files: shows which tests cover the hovered line (with status + duration + clickable links), and branch arm hit/miss detail for partially-covered lines. First 5 shown inline; "Show all N" link fires liveTestRunner.showCoveringTests → Quick Pick with fuzzy search over all covering tests
├── utils/
│ └── duration.ts durationLabel, durationColorVar, getThresholds
├── views/
│ ├── BaseWebviewProvider.ts Webview lifecycle + postMessage routing + IResultObserver base
│ ├── ExplorerView.ts Sidebar: file/suite/test tree
│ └── ResultsView.ts Panel: 3-column detail view (or timeline view)
├── timeline/ Timeline Debugger — step-by-step test replay
│ ├── IInstrumentedRunner.ts Framework-agnostic interface for instrumented runs
│ ├── JestInstrumentedRunner.ts Jest implementation: spawns Jest with traceTransform, parses JSONL
│ ├── TimelineStore.ts Interfaces: TimelineStore, Step, VariableSnapshot, LogEntry, ErrorEntry
│ ├── TimelineEvent.ts Union type for STEP / VAR / LOG / ERROR / ASSERT events
│ ├── TimelineDecorationManager.ts Active-line highlight + inline ghost text + hover provider
│ ├── instrumentation/
│ │ ├── traceTransform.js Jest transform (CJS): injects __trace.step/var calls via AST
│ │ ├── traceRuntime.js __trace global: writes events as JSONL to TRACE_OUTPUT_FILE
│ │ └── testDiscovery.js AST walker: extracts describe/it/test names + line numbers
│ └── __fixtures__/
│ └── sample-events.jsonl Hand-written fixture for parseEvents smoke tests
└── webview/ Browser-side assets (not compiled by tsc)
├── explorer.html
├── results.html
├── router.js Single-page router: mount/unmount views on { type: 'route' }
├── testListLayout.js Shared test list renderer used by both views
├── utils.js JS mirror of duration.ts; exposes window.LiveTestUtils
├── styles.css
├── timeline/
│ └── PlaybackEngine.js Webview playback: currentStepId, next/prev/jumpTo/play/pause
├── components/
│ ├── logPanel.js Shared log output component (mount/update/unmount)
│ └── errorPanel.js Shared error output component (mount/update/unmount)
└── views/
├── resultsView.js Normal results view (uses logPanel + errorPanel)
├── timelineView.js Timeline bar + controls + console/errors right panel
├── testListView.js Sidebar test list view
├── coverageExplorerView.js Coverage tab in Explorer sidebar: project totals + per-file breakdown; clicking a row opens the file in the editor
└── timelineSidebar.js Sidebar State / Watch / Call Stack panels for timeline mode
Projects: on activate ProjectRegistry.refresh() detects the test projects (one per workspace folder with its own test config; one per workspace package with tests under a monorepo root without one; Python: a folder configuring pytest is one, a uv workspace root without a pytest config gives one per member with tests (pythonProjectsInFolder, 3.3.0); the liveTestRunner.projectRoot setting pins one root) and builds a ProjectContext each — none is started. The first (or remembered / active-editor) project is selected; the views show it, Start / Stop act on it, and only its discovery runs now (the others on first selection or Start). Everything below happens per project. Several projects may run at once, up to liveTestRunner.maxRunningProjects; a background project keeps running and rerunning on save, its events held back from the Explorer / Results by its ProjectObserverGate until it is selected again. Mixed projects: a project with a Jest config and its own vitest.config.* lists with both frameworks at Start and its FrameworkRouter places each test file with one of them; batches, plain runs, ▶ Run / ▷ Debug and on-save reruns use the file's framework, and a source-file save reruns both frameworks' dependents. Editor features (gutter, inline durations, CodeLens, coverage bars, hover) always resolve each file to its own project (editor/FileStores.ts) and get every project's events (editorObservers).
On extension activate (before any user action):
-
DiscoveryCacheloaded fromglobalStorageUri/cache/<folderName>-<hash8>/discovery-cache.json(if exists). Asession.lockPID file is written. -
TestDiscoveryService.start()→vscode.workspace.findFiles→ list of test file paths -
onDiscoveryStarted(total)fired → sidebar shows⟳ Discovering… 0 / N, Start Testing disabled - Files parsed in batches — cold (no cache): 5 files per batch; warm (cache present): 25 files per batch. Each file:
DiscoveryCache.get(filePath)checks mtime → cache hit skips readFile + Babel entirely; cache miss reads source →@babel/parserAST walk → result stored viaDiscoveryCache.set(). Store populated viastore.nodeDiscovered→onBatchDiscovered→ sidebar rows appended incrementally viaDocumentFragment(no full re-render per batch). -
cache.flush()writes dirty entries to disk after discovery completes. -
onDiscoveryComplete()→ Start Testing re-enabled -
FileSystemWatcheractivated — new/changed test files are re-discovered immediately (guard: skip files withrunningstatus); watcher also callscache.flush()after re-discovery
User clicks Start Testing:
-
SessionManager.start()→await discovery.awaitDiscovery()(no-op if already done) - File list read from
store.getAllFiles()— no second file scan needed -
onRunStartedpushed to UI with the already-populated pending tree -
_runFilesbuilds a batch queue:BATCH_SIZE = clamp(ceil(N / CONCURRENCY), 5, 50)files per batch;CONCURRENCY = max(1, floor(cpuCount / 4))parallel Jest processes - Each batch: files marked
runningin store → single Jest process viaJestBatchRunner.runFileswith combined test+trace+coverage instrumentation;liveReporter.jsstreams per-file results as they complete;onFileDonenotifies observers after each file - After Jest exits:
JestBatchRunnerparses (a) the light-trace JSONL → updatesExecutionTraceStore; (b) Jest's per-test-file coverage → each test file's contribution inCoverageStore(_parseJestCoverage). Once the batches are done,jestCoverageCount.jshas Jest count the files no test loads (also for files created or edited later,countSources) - In parallel with step 5:
SourceCounterAST-scans the source files that count toward coverage (the framework'sCoverageScope— Vitestcoverage.include/exclude, JestcollectCoverageFrom/coveragePathIgnorePatterns; built-in rules + git-ignore when the config is unreadable) and populatesCoverageStorewith'counted'(0-hit) entries so untouched files are included in coverage denominators — a placeholder until the framework counts them its own way (Jest: generateEmptyCoverage; Vitest: the first batch's untested pass through the provider wrapper; pytest: coverage.py). Skipped when the config has no include list (the CLI then reports only loaded files) - On-save listener enabled
On save (debounced 300ms):
if (isTestFile(savedFile))
→ run that file
else (source file saved)
→ _runAffectedBySourceFile(savedFile)
1. Check ExecutionTraceStore.getAffectedTestFiles(savedFile)
If trace data exists:
For each affected test file:
suites with isSharedVars:true → run whole file
suites with isSharedVars:false → run individual test cases
(single Jest invocation with combined --testNamePattern)
If no trace data:
→ the framework's related run: jest --findRelatedTests / vitest related (whole files)
Stop: kill child processes, clearAll() on decorations (types kept alive), resultStore.clearAllLineMaps(), disable on-save.
Single source of truth for all test results. All views read from here.
Uses a flat node pool (Map<string, TestNode>) with tree relationships managed via parentId and children arrays. Supports unlimited nesting depth.
ResultStore
├── files: Map<filePath, FileResult>
│ FileResult
│ ├── filePath, name, status, duration
│ ├── output: ScopedOutput
│ └── 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
└── failureMessages: string[]
Node IDs follow a stable, path-based convention: {filePath}::{suite1}::{suite2}::…::{name}. Static discovery and Jest results automatically match without a lookup table.
Status rollup: bubbleUpStatus(nodeId) propagates worst-case status from a leaf node up through all ancestors in O(depth). Priority: running > failed > passed > skipped > pending. Empty template nodes are ignored during rollup.
Incremental summary: A running counter tracks test counts so getSummary() is O(1), not O(n).
Derived indexes built from per-test JSONL trace files written by JestBatchRunner after each instrumented run. These are read-only caches — the trace files on disk are the source of truth. All three indexes are rebuilt from traces and cleared together on session reset.
ExecutionTraceStore
├── traceIndex: Map<testId, string>
testId (full test name, e.g. "Suite > test name") → absolute path to .jsonl trace file
One file per test case written to session-specific trace directory.
│
├── coverageIndex: Map<filePath, Set<lineNumber>>
│ Every source file line executed by any test in the session.
│ Accumulates across all runs — never decrements mid-session.
│ Used for session-wide gutter coverage decorations.
│
└── sourceToTests: Map<sourceFilePath, SourceTestMapping>
SourceTestMapping: {
[testFilePath: string]: {
[suiteName: string]: {
isSharedVars: boolean // true → must run whole suite on rerun
sharedVarNames: string[] // variable names that are shared (for display)
testCases: string[] // full test names in this suite
}
}
}
Populated by JestBatchRunner after each file run.
Used by SessionManager._runAffectedBySourceFile() to scope on-save reruns
to the specific test cases that actually executed code from the changed file.
Relationship between the stores:
-
ResultStoreanswers "what happened" — pass/fail, output, failure messages -
ExecutionTraceStoreanswers "what ran and where" — which source lines executed, which tests cover which files -
CoverageStoreanswers "how much is covered" — statement/branch/function/line percentages; includes untouched files viaSourceCounter - No store writes to another;
SessionManagerandJestBatchRunnercoordinate all three
interface ScopedOutput {
lines: OutputLine[]
capturedAt: number | null // null = never run at this scope
}
interface OutputLine {
text: string
level: 'log' | 'info' | 'warn' | 'error'
timestamp: number
}Output attribution:
- Full file run →
FileResult.outputset only - Suite/node rerun → that node's
outputset - Test rerun →
TestNode.outputset - Never back-fill node output from file-level output
- Vitest attributes output (
ConsoleEntry.scope): every test that ran gets its own lines (possibly none), suites their hooks' lines — attribution, not back-fill
LineMap: Map<filePath, Map<lineNumber, LineEntry>>
LineEntry: { nodeId: string, fileId: string }Identity only — never status or duration. DecorationManager always queries ResultStore.getNode(nodeId) for those values.
Lifecycle:
- Discovery →
clearLineMap(filePath)then populate from AST line numbers — pending icons appear immediately - File result arrives →
clearLineMap(filePath)then repopulate from Jestlocation.line— replaces AST lines with authoritative run-time lines - Session stop →
clearAllLineMaps() -
clearAllLineMaps()is not called at run start — discovery-sourced lines stay valid until each file's own result arrives
| Type | Direction | Purpose |
|---|---|---|
batch-file-results |
Extension → both views | Batched file results (up to 50 ms window); preferred over full-file-result for runs |
full-file-result |
Extension → both views | Single file result (legacy; still handled); complete file result tree |
scope-changed |
Extension → both views | Row selection; highlights row in column 1; also sent in init as selection field for restore on visibility |
scope-logs |
Extension → results only | Log + error data for selected scope; drives columns 2 & 3 |
run-started |
Extension → both | Resets UI for full run |
files-rerunning |
Extension → both | Marks files as running (partial rerun) |
init |
Extension → both | Sends thresholds on session start |
select |
Webview → extension | User clicked a row |
rerun |
Webview → extension | User clicked rerun button |
open-file |
Webview → extension | User wants to open a file |
ready |
Webview → extension | Webview initialised |
route |
Extension → both | Switch view: { type: 'route', view: 'timeline' | 'results' | 'testList' | 'timelineSidebar' }
|
timeline-loading |
Extension → ResultsView | Show spinner while instrumented Jest run is in progress |
timeline-ready |
Extension → both | Instrumented run complete; carries serialised TimelineStore
|
timeline-error |
Extension → ResultsView | Instrumented run failed; carries error message |
timeline-exited |
ResultsView → extension | Timeline view unmounted (user navigated away) |
step-changed |
ResultsView → extension | User stepped to a new step; carries stepId, filePath, line
|
step-update |
Extension → ExplorerView | Forward of step-changed; sidebar syncs State/Watch/Call Stack |
add-to-watch |
Extension → ExplorerView | Add a variable to the sidebar Watch panel |
timeline-rerun |
ExplorerView → extension | User clicked Re-run in the timeline sidebar |
projects |
Extension → ExplorerView | Switcher row: ProjectSummary[] (name, framework, state idle/discovering/running/watching, counts, progress, selected) — also in init; shown with 2+ projects |
select-project |
ExplorerView → extension | User picked a project → liveTestRunner.selectProject
|
init also carries running ({completed,total,failed} or null) so a project switched to mid-run shows its progress. File objects carry group (Vitest project name) when the config has several test.projects.
Rule: scope-logs and scope-changed are always sent as separate messages. Different lifecycles; keeping them separate prevents double-renders.
{
type: 'scope-logs',
payload: {
logSections: Array<{
label: string
scope: 'file' | 'suite' | 'test'
capturedAt: number | null
lines: Array<{ text: string, level: string, timestamp: number }>
}>
errorSections: Array<{
label: string
scope: 'file' | 'suite' | 'test'
errors: Array<{ testName: string, failureMessages: string[], capturedAt: number | null }>
}>
}
}SVG files in resources/icons/. One TextEditorDecorationType per state:
| File | Colour | Meaning |
|---|---|---|
passed.svg |
Green | Test passed |
failed.svg |
Red | Test failed |
running.svg |
Amber | Currently running |
pending.svg |
Grey | Not yet run |
DecorationManager applies decorations to visible editors after each file result and when an editor becomes active (onDidChangeActiveTextEditor). All types cleared and disposed on session stop.
Rendered via renderOptions.after on the same DecorationOptions as the gutter icon. Colour-coded by thresholds (see below).
Regex scan — no AST:
/^\s*(describe|it|test)\s*[\.(]/
Three lenses per matching line:
-
▶ Run— always shown ondescribe,it,test -
▷ Debug— always shown ondescribe,it,test -
◈ Results— only onit/testlines that have aLineMapentry
Session guard: CodeLensProvider registered only while session is active. Disposing the registration removes all lenses.
| Command | Scope resolution |
|---|---|
liveTestRunner.rerunFromEditor |
it/test line → LineMap lookup → --testNamePattern. describe line → regex extracts title → --testNamePattern. Unresolved → run whole file. |
liveTestRunner.debugFromEditor |
Same resolution. Launches vscode.debug.startDebugging with --runInBand --no-coverage. |
liveTestRunner.focusResult |
Reveals Results panel, calls selectionState.select(). |
┌─────────────────┬──────────────────────────┬────────────────────────┐
│ 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> │
└─────────────────┴──────────────────────────┴────────────────────────┘
Column 1 — test tree; drives selection; syncs with sidebar.
Column 2 — log output scoped to the selected row. Each scope with output gets a header (icon + label + timestamp). The [All][Log][Info][Warn][Error] tabs filter all sections simultaneously. Empty scopes show a placeholder. Auto-scrolls; locks if user scrolls up.
Column 3 — failure entries scoped to the selected row. Each entry: test name (red) + raw failure message in monospace.
Scoping rules:
| Selection | Output sections | Errors |
|---|---|---|
| File | File section always. Suite/test sections only if individually rerun. | All failures in file |
| Suite | Suite section always (placeholder if empty). Test sections only if individually rerun. | All failures in suite |
| Test | Test section always (placeholder if empty). | That test's failure or "No failures ✓" |
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 |
Logic: src/utils/duration.ts (TypeScript) + src/webview/utils.js (plain JS mirror). Extension reads via getThresholds() and sends in init message. Webviews call LiveTestUtils.setThresholds(msg.thresholds).
All in packages/vscode-extension/package.json:
Commands:
liveTestRunner.startTestingliveTestRunner.stopTesting-
liveTestRunner.selectProjectRoot— pins the window to one root (writesliveTestRunner.projectRoot; "Detect all projects" clears it) -
liveTestRunner.selectProject— "Select Project": switch the project the views show (quick pick, or an id / name argument; the Explorer switcher row uses it) -
liveTestRunner.stopAllProjects— "Stop All Projects" -
liveTestRunner.startTesting/stopTestingaccept an optional project id (root) argument; without it they act on the selected project -
liveTestRunner.showOutput— "Show Test Output": raw Jest / Vitest output channel -
liveTestRunner.showLogs— "Show Logs": levelled extension log channel -
liveTestRunner.openGuide— "Open Guide": the user guide shipped inout/guide/guide.html(copied fromdocs/live-test-runner-guide.html) in a webview tab (views/GuidePanel.ts); the same page is on GitHub Pages at/guide/(.github/workflows/pages.yml), next to the landing pagesite/index.htmlandsite/sitemap.xml -
liveTestRunner.copyDiagnostics— "Copy Diagnostic Report": versions, project setup, settings, recent logs → clipboard + untitled doc liveTestRunner.rerunFromEditorliveTestRunner.debugFromEditorliveTestRunner.focusResult-
liveTestRunner.openTimelineDebugger— opens the Timeline Debugger for a specific test -
liveTestRunner.addToWatch— adds a variable to the sidebar Watch panel (used by hover command links) -
liveTestRunner.copyValue— copies an inline variable value to the clipboard (used by hover command links) -
liveTestRunner.connectAI— "Connect Your AI Assistant": setup page per assistant (ai/ConnectAiPanel.ts); also a sparkle icon on the Results panel title and a command link in theai.bridgesetting -
liveTestRunner.fixWithAI— "Fix Failing Test with AI" (AiBridge.fixWithAI): opens the chat with a request naming the tools, else copies the failure; from the ✨ CodeLens, the Results panel's Errors pane and the Problems quick fix
Language-model tools: contributes.languageModelTools — the 23 LTR_ tools, generated from src/ai/catalog.ts (UPDATE_LM_TOOLS=1 npx jest test/aiCatalog.test.ts), when: config.liveTestRunner.ai.bridge. Tool names are a public API (renames need a changelog line).
Views:
-
liveTestRunner.explorerView— sidebar, Activity Bar (beaker icon) -
liveTestRunner.resultsView— editor panel (Test Results tab)
Status bar item: bottom left; updates throughout session.
Configuration: liveTestRunner.* — see contributes.configuration.properties in package.json.
| Setting | Default | Description |
|---|---|---|
liveTestRunner.projectRoot |
"" |
Pin the window to one project root; empty = detect every test project |
liveTestRunner.maxRunningProjects |
"auto" |
Projects running at once: auto = 2, or 1 with ≤ 4 CPU cores or < 8 GB total memory; or a number ≥ 1 |
liveTestRunner.pythonPath |
"" |
pytest: the interpreter that runs the tests; empty = automatic (selected, project venv, Python extension, PATH) |
liveTestRunner.pytestArgs |
[] |
pytest: extra arguments for every run |
liveTestRunner.vitestTrace |
true |
Vitest execution trace (covering tests, precise source-file reruns); off → Vitest runs as configured, saves use vitest related
|
liveTestRunner.frameworks |
{} |
Jest + Vitest projects: glob (relative to the workspace folder) → "jest" / "vitest"; first match wins; also makes a Jest project mixed when it sends a file to Vitest |
liveTestRunner.runMode |
"auto" |
"auto": extension calls Jest directly (full structured output). "npm": delegates to npm test -- from your package.json scripts (limited structured output — see below). |
liveTestRunner.jestCommand |
"" |
Override Jest binary/command. Only used when runMode is "auto". |
liveTestRunner.onSaveDebounceMs |
300 |
Debounce delay (ms) |
liveTestRunner.speed |
balanced |
Where the budget starts: full 3/4 of the cores, balanced half, light one process ≤ 2 workers (setSpeedLevel); adapts per process (workersNow) unless speedStrict
|
liveTestRunner.speedStrict |
false |
Keep the budget at the level (setSpeedStrict) |
liveTestRunner.ai.bridge |
true |
AI assistants get the LTR_ tools (LM tools in VS Code, MCP in Cursor, the mailbox for terminal agents) |
liveTestRunner.ai.allowRuns |
"always" |
always / ask (modal per run) / never (read-only) for assistant runs |
liveTestRunner.ai.fixWithAI |
true |
✨ Fix with AI on failing tests (CodeLens, Errors pane, Problems quick fix) |
liveTestRunner.showFailuresInProblems |
true |
Failing tests as Diagnostics (editor/FailureDiagnostics.ts) |
liveTestRunner.durationThresholds.testAmberMs |
100 |
Test amber threshold |
liveTestRunner.durationThresholds.testRedMs |
500 |
Test red threshold |
liveTestRunner.durationThresholds.suiteAmberMs |
500 |
Suite amber threshold |
liveTestRunner.durationThresholds.suiteRedMs |
2000 |
Suite red threshold |
liveTestRunner.durationThresholds.fileAmberMs |
1000 |
File amber threshold |
liveTestRunner.durationThresholds.fileRedMs |
5000 |
File red threshold |
| Framework | Status |
|---|---|
| Jest | Fully supported |
| Create React App | Fully supported (via --showConfig + direct Jest invocation) |
| Vitest | Supported since 3.0.0 (Vitest 3+; 1–2 results only) — run, pass/fail, per-test output, failures, live progress, coverage, related tests on save. Execution trace / "covering tests" + precise source-file reruns since 3.1.0. Vitest 3 workspaces, type-check files and components (.vue / .svelte / .astro / .marko, both frameworks — Jest through the project's transformer + its source map, shared/sourceMapLookup.js) included; Jest ESM mode from the test script's NODE_OPTIONS or .npmrc (runner jestNodeEnv, jestEsmHint). Loaded files rerun their tests: Vitest module graph (LTR_VITEST_DEPS, ExecutionTraceStore.addImporters), Jest same-folder referrers (referencingSources); type-check files via vitest related --typecheck.only. Real-repo matrix includes vue-testing-library, vue-multiselect, jest-preset-angular example (Angular 22), svelte-testing-library (repo-components). Not yet: Timeline. See docs/development/framework-features.md
|
| pytest | Since 3.2.0 — pytest ≥ 7 / Python ≥ 3.12: run, pass/fail, per-test output, failures, live progress, hang limit, Stop, ▶ Run / ▷ Debug (debugpy) by node id, saved-test reruns, coverage (coverage.py, istanbul-shaped), covering tests + precise source-save reruns (per-test coverage contexts → trace records), import-graph fallback. Shipped plugin runner/src/framework/pytest/ltr_pytest.py loaded only with -p; interpreter from python/PythonInterpreters.ts (Select Python Interpreter, liveTestRunner.pythonPath; shown on the Explorer's environment chip, python/pythonEnvChip.ts); one pytest process at a time (FrameworkServices.batchPolicy). uv workspaces (3.3.0): one project per member, the shared .venv found above the member (venvRoots). JS + Python in one folder (3.3.0): the JS project's router adds the pytest bundle (projectFrameworks), mixedDiscoverer, saves rerun only their language (FrameworkServices.language), a framework that cannot run is left out (disable); a Python subfolder with a pytest config is its own project (nestedPythonRoots). Not yet: Timeline |
| Jest + Vitest in one project | Since 3.1.0 — a Jest root with its own vitest.config.* (or a liveTestRunner.frameworks rule) runs each test file with its own framework; FrameworkRouter
|
| Purpose | File |
|---|---|
| Wire everything | packages/vscode-extension/src/extension.ts |
| Projects of the workspace (detection rules) | packages/runner/src/framework/projectDiscovery.ts |
| Which framework runs a test file (mixed projects) |
packages/runner/src/framework/frameworkRouting.ts (rules), packages/vscode-extension/src/framework/FrameworkRouter.ts
|
| Per-project state, selected project, gate |
packages/vscode-extension/src/project/ProjectRegistry.ts, ProjectContext.ts
|
| Timeline contracts | packages/vscode-extension/src/timeline/IInstrumentedRunner.ts |
| Timeline data model | packages/vscode-extension/src/timeline/TimelineStore.ts |
| Timeline event union | packages/vscode-extension/src/timeline/TimelineEvent.ts |
| Jest trace runner | packages/vscode-extension/src/timeline/JestInstrumentedRunner.ts |
| Active-line highlight | packages/vscode-extension/src/timeline/TimelineDecorationManager.ts |
| Jest transform (CJS) | packages/vscode-extension/src/timeline/instrumentation/traceTransform.js |
| Trace runtime | packages/vscode-extension/src/timeline/instrumentation/traceRuntime.js |
| Webview playback | packages/vscode-extension/src/webview/timeline/PlaybackEngine.js |
| Webview router | packages/vscode-extension/src/webview/router.js |
| Shared log renderer | packages/vscode-extension/src/webview/components/logPanel.js |
| Shared error renderer | packages/vscode-extension/src/webview/components/errorPanel.js |
| Run lifecycle | packages/vscode-extension/src/session/SessionManager.ts |
| All result data | packages/vscode-extension/src/store/ResultStore.ts |
| Execution trace indexes | packages/vscode-extension/src/store/ExecutionTraceStore.ts |
| Per-file trace runner | packages/vscode-extension/src/session/JestBatchRunner.ts |
| Selection tracking | packages/vscode-extension/src/store/SelectionState.ts |
| Jest-specific logic | packages/vscode-extension/src/framework/JestAdapter.ts |
| Gutter + inline | packages/vscode-extension/src/editor/DecorationManager.ts |
| Run/Debug/Results buttons | packages/vscode-extension/src/editor/CodeLensProvider.ts |
| Duration utils (TS) | packages/vscode-extension/src/utils/duration.ts |
| Sidebar UI | packages/vscode-extension/src/views/ExplorerView.ts |
| Results panel UI | packages/vscode-extension/src/views/ResultsView.ts |
| Webview base | packages/vscode-extension/src/views/BaseWebviewProvider.ts |
| Shared list renderer | packages/vscode-extension/src/webview/testListLayout.js |
| Duration utils (JS) | packages/vscode-extension/src/webview/utils.js |
Jest spawn (line-buffered, UTF-8 safe, [LTR:level] routing) |
packages/runner/src/execution/Executor.ts |
| Extension logger (LogOutputChannel, ring buffer) | packages/vscode-extension/src/utils/logger.ts |
| Runner/core logger + sink | packages/runner/src/utils/logger.ts |
| Diagnostic report | packages/vscode-extension/src/utils/diagnostics.ts |
| User guide tab | packages/vscode-extension/src/views/GuidePanel.ts |
| Vitest coverage → CoverageStore | packages/vscode-extension/src/coverage/istanbulCoverage.ts |
| Which lines a statement's coverage bar covers | packages/vscode-extension/src/coverage/statementLines.ts |
| Vitest batches | packages/vscode-extension/src/session/VitestBatchRunner.ts |
| Vitest-specific logic |
packages/vscode-extension/src/framework/VitestAdapter.ts, packages/runner/src/VitestRunner.ts
|
| Framework detection | packages/runner/src/framework/FrameworkDetector.ts |
| CRA config extraction | packages/runner/src/framework/adapters/CRAAdapter.ts |
| Source save → which tests rerun |
SessionManager._runAffectedBySourceFile, store/ExecutionTraceStore.ts
|
| AI assistants: tools, handlers, transport |
src/ai/catalog.ts (tools, prompts), src/ai/tools.ts (AiTools), src/ai/AiBridge.ts (LM tools, Cursor, Fix with AI), src/ai/mailbox.ts + protocol.ts (file mailbox), src/ai/mcp/ (stdio relay → out/mcp.js), src/ai/launcher.ts (globalStorage launcher) |
| All user settings |
packages/vscode-extension/package.json → contributes.configuration
|
| Per-feature docs (what it does · requirements with their tests · design) |
docs/features/, docs/requirements/, docs/development/design/, listed in docs/README.md — update them with every behaviour change |
-
Prefer
--outputFileover stdout, but stdout is the fallback.Executoralways appends--outputFile=<tmpfile>and reads that file on exit. Stdout is still captured in parallel — if the output file is missing or empty (CRA occasionally writes JSON to stdout on a bailed run instead), stdout is used. Do not remove the stdout capture. -
Never use
react-scriptsat run time. Extract config via--showConfigonce, then run Jest directly. -
Never run binaries globally. Always resolve from the project's own
node_modules. -
Never duplicate status/duration into
LineMap.LineMapstores identity only. QueryResultStoreat decoration time. - Never back-fill suite/test output from file-level output. Empty output is correct for scopes that haven't been individually run.
-
Never add business logic to
extension.ts. It wires instances and registers commands only. -
SessionManager,ResultStore, views, and observers must be framework-agnostic. All framework differences live inIFrameworkAdapterimplementations. -
Multi-Session Isolation is mandatory. Never use global shared temporary directories for runner configs or traces. Always use the window-local
LTR_SESSION_TMP_DIRinjected via constructors — per project, theProjectContext.sessionDir(a sub-folder when the window has several projects). -
Per-project state lives in
ProjectContext. Never add a window-wide store or framework bundle: a new store goes intoProjectContext. The Explorer / Results views bind to the selected project (bindProject); editor features resolve each file's own project (FileStoresResolver). -
Safe Cleanup. On activation, the extension host must only delete stale session folders belonging to dead processes (verified via
process.kill(pid, 0)). Never perform recursive blind deletions in the base temp root. -
Persistent Templates. AST-discovered dynamic test headers (
.each) aretemplatenodes. They must survive cleanup and status rollups even when childless. - Nested Branch Compatibility. The recursive tree must support arbitrary depth. High-level status rollups must be reliable even when only deep-nested leaves are rerun. Always bubble status changes up the full ancestor chain.
-
IInstrumentedRunneris the only abstraction for instrumented runs.extension.tsholds a reference typed asIInstrumentedRunner— never as the concreteJestInstrumentedRunner. Adding Vitest or Mocha timeline support = one new file implementing this interface. -
TimelineDecorationManageris separate fromDecorationManager. It never touches pass/fail gutter icons — completely independent decoration types. -
Timeline Maps are serialised before postMessage.
TimelineStore.variablesandTimelineStore.logsareMap<number, ...>in the extension host. They are converted to plain objects (Object.fromEntries) before sending to webviews, since Maps are not JSON-serialisable. -
scope-logsandscope-changedare always separate messages. They have different lifecycles. -
Logging goes through the logger, never
console.*or the Test Output channel. Extension:logger.scope('Area'). runner/core:createLogger('Area'). Instrumentation inside Jest:[LTR:<level>] msgon stderr. Oneinfosummary per run; per-file detail atdebug/trace. See developer-guide → Logging. -
Session Jest runs pass
--verbose=false. Jest auto-enables verbose for single-file runs, which stops console buffering and emptiestestResult.console(Results panel shows no logs). -
AI assistants never Start / Stop and never reach the network.
AiToolsacts only throughSessionManager(rerunScope,runFiles,runChangedFiles) and existing commands (Clear Cache and Restart while on, the Update snapshot dialog). The relay talks to the window through files only;noNetwork.test.tsscansout/mcp.js. New tools go inai/catalog.tsand regenerate package.json'slanguageModelTools. One change is rerun once:SessionManager._rerunVersions(file → modified time, by session or assistant) letsrunChangedFilesreuse the session's on-save rerun and the on-save rerun skip a change an assistant already verified; assistant runs wait for runs in flight.
Source: docs/development/ai-context.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.