Skip to content

AI context

github-actions[bot] edited this page Nov 19, 2026 · 4 revisions

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.


What this is

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)


Three packages

packages/core — @live-test-runner/core

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


packages/runner — @live-test-runner/runner

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=false

The 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's coverageProvider, coverageReporters: ['none'], empty collectCoverageFrom): the numbers are what jest --coverage reports
  • sessionTraceTransform.js at the front of the transform chain (light trace only, on the output of the project's transformer, which instruments for Jest's coverage — or instrumentLikeJest does when it cannot; a source map back to the file)
  • ltrCoverageSetup.js as the first setupFilesAfterEnv entry — coverage flush, per-test trace context (beginTest / endTest), test-start/end heartbeats for the hang watchdog
  • liveReporter.js as an extra reporter that appends a start record and one result record per file to a JSONL file, and each test file's coverage as Jest reports it (jestCoverage.perTestFile) to LTR_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: string

Deprecated aliases — JestJsonResult, JestFileResult, JestTestCaseResult, JestConsoleEntry remain exported for backward compatibility. Do not use in new code.


packages/vscode-extension — live-test-runner

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

Session lifecycle

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

  1. DiscoveryCache loaded from globalStorageUri/cache/<folderName>-<hash8>/discovery-cache.json (if exists). A session.lock PID file is written.
  2. TestDiscoveryService.start() → vscode.workspace.findFiles → list of test file paths
  3. onDiscoveryStarted(total) fired → sidebar shows ⟳ Discovering… 0 / N, Start Testing disabled
  4. 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/parser AST walk → result stored via DiscoveryCache.set(). Store populated via store.nodeDiscovered → onBatchDiscovered → sidebar rows appended incrementally via DocumentFragment (no full re-render per batch).
  5. cache.flush() writes dirty entries to disk after discovery completes.
  6. onDiscoveryComplete() → Start Testing re-enabled
  7. FileSystemWatcher activated — new/changed test files are re-discovered immediately (guard: skip files with running status); watcher also calls cache.flush() after re-discovery

User clicks Start Testing:

  1. SessionManager.start() → await discovery.awaitDiscovery() (no-op if already done)
  2. File list read from store.getAllFiles() — no second file scan needed
  3. onRunStarted pushed to UI with the already-populated pending tree
  4. _runFiles builds a batch queue: BATCH_SIZE = clamp(ceil(N / CONCURRENCY), 5, 50) files per batch; CONCURRENCY = max(1, floor(cpuCount / 4)) parallel Jest processes
  5. Each batch: files marked running in store → single Jest process via JestBatchRunner.runFiles with combined test+trace+coverage instrumentation; liveReporter.js streams per-file results as they complete; onFileDone notifies observers after each file
  6. After Jest exits: JestBatchRunner parses (a) the light-trace JSONL → updates ExecutionTraceStore; (b) Jest's per-test-file coverage → each test file's contribution in CoverageStore (_parseJestCoverage). Once the batches are done, jestCoverageCount.js has Jest count the files no test loads (also for files created or edited later, countSources)
  7. In parallel with step 5: SourceCounter AST-scans the source files that count toward coverage (the framework's CoverageScope — Vitest coverage.include/exclude, Jest collectCoverageFrom/coveragePathIgnorePatterns; built-in rules + git-ignore when the config is unreadable) and populates CoverageStore with '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)
  8. 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.


Data model

ResultStore

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

ExecutionTraceStore

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:

  • ResultStore answers "what happened" — pass/fail, output, failure messages
  • ExecutionTraceStore answers "what ran and where" — which source lines executed, which tests cover which files
  • CoverageStore answers "how much is covered" — statement/branch/function/line percentages; includes untouched files via SourceCounter
  • No store writes to another; SessionManager and JestBatchRunner coordinate all three

ScopedOutput

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.output set only
  • Suite/node rerun → that node's output set
  • Test rerun → TestNode.output set
  • 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

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 Jest location.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

Webview messaging

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.

scope-logs payload shape

{
  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 }>
    }>
  }
}

Editor decorations

Gutter icons

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.

Inline duration

Rendered via renderOptions.after on the same DecorationOptions as the gutter icon. Colour-coded by thresholds (see below).

CodeLens

Regex scan — no AST:

/^\s*(describe|it|test)\s*[\.(]/

Three lenses per matching line:

  • ▶ Run — always shown on describe, it, test
  • ▷ Debug — always shown on describe, it, test
  • ◈ Results — only on it/test lines that have a LineMap entry

Session guard: CodeLensProvider registered only while session is active. Disposing the registration removes all lenses.

Command behavior

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().

Test Results panel — 3 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>     │
└─────────────────┴──────────────────────────┴────────────────────────┘

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 ✓"

Duration colour thresholds

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


VS Code contribution points

All in packages/vscode-extension/package.json:

Commands:

  • liveTestRunner.startTesting
  • liveTestRunner.stopTesting
  • liveTestRunner.selectProjectRoot — pins the window to one root (writes liveTestRunner.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 / stopTesting accept 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 in out/guide/guide.html (copied from docs/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 page site/index.html and site/sitemap.xml
  • liveTestRunner.copyDiagnostics — "Copy Diagnostic Report": versions, project setup, settings, recent logs → clipboard + untitled doc
  • liveTestRunner.rerunFromEditor
  • liveTestRunner.debugFromEditor
  • liveTestRunner.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 the ai.bridge setting
  • 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.


Configuration settings

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 support

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

Key files by purpose

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

Rules that must not be broken

  1. Prefer --outputFile over stdout, but stdout is the fallback. Executor always 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.
  2. Never use react-scripts at run time. Extract config via --showConfig once, then run Jest directly.
  3. Never run binaries globally. Always resolve from the project's own node_modules.
  4. Never duplicate status/duration into LineMap. LineMap stores identity only. Query ResultStore at decoration time.
  5. Never back-fill suite/test output from file-level output. Empty output is correct for scopes that haven't been individually run.
  6. Never add business logic to extension.ts. It wires instances and registers commands only.
  7. SessionManager, ResultStore, views, and observers must be framework-agnostic. All framework differences live in IFrameworkAdapter implementations.
  8. Multi-Session Isolation is mandatory. Never use global shared temporary directories for runner configs or traces. Always use the window-local LTR_SESSION_TMP_DIR injected via constructors — per project, the ProjectContext.sessionDir (a sub-folder when the window has several projects).
  9. Per-project state lives in ProjectContext. Never add a window-wide store or framework bundle: a new store goes into ProjectContext. The Explorer / Results views bind to the selected project (bindProject); editor features resolve each file's own project (FileStoresResolver).
  10. 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.
  11. Persistent Templates. AST-discovered dynamic test headers (.each) are template nodes. They must survive cleanup and status rollups even when childless.
  12. 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.
  13. IInstrumentedRunner is the only abstraction for instrumented runs. extension.ts holds a reference typed as IInstrumentedRunner — never as the concrete JestInstrumentedRunner. Adding Vitest or Mocha timeline support = one new file implementing this interface.
  14. TimelineDecorationManager is separate from DecorationManager. It never touches pass/fail gutter icons — completely independent decoration types.
  15. Timeline Maps are serialised before postMessage. TimelineStore.variables and TimelineStore.logs are Map<number, ...> in the extension host. They are converted to plain objects (Object.fromEntries) before sending to webviews, since Maps are not JSON-serialisable.
  16. scope-logs and scope-changed are always separate messages. They have different lifecycles.
  17. 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>] msg on stderr. One info summary per run; per-file detail at debug/trace. See developer-guide → Logging.
  18. Session Jest runs pass --verbose=false. Jest auto-enables verbose for single-file runs, which stops console buffering and empties testResult.console (Results panel shows no logs).
  19. AI assistants never Start / Stop and never reach the network. AiTools acts only through SessionManager (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.ts scans out/mcp.js. New tools go in ai/catalog.ts and regenerate package.json's languageModelTools. One change is rerun once: SessionManager._rerunVersions (file → modified time, by session or assistant) lets runChangedFiles reuse 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/.

Clone this wiki locally