Skip to content

Developer Guide

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

Developer Guide

Everything you need to build, extend, and publish Live Test Runner.


Prerequisites

  • Node.js 22+ (CI uses 24)
  • pnpm — the version is pinned in package.json (packageManager); with Corepack (corepack enable) or pnpm 10+ installed, the right version is used automatically. Build scripts allowed to run are listed under allowBuilds in pnpm-workspace.yaml.
  • VS Code

Getting started

git clone https://github.com/eshandias/live-test-runner
cd live-test-runner
pnpm install

# Start TypeScript watch (extension only)
pnpm start

# Press F5 in VS Code to launch the Extension Development Host

The Extension Development Host opens a second VS Code window where the extension runs live. Changes to extension source files are picked up after recompilation (watch mode handles this automatically).


Build commands

# Build all packages
pnpm run build

# Clean rebuild — removes dist/ and .tsbuildinfo files
pnpm run rebuild

# Run all tests
pnpm run test

# Build individual packages
cd packages/core && pnpm run build
cd packages/runner && pnpm run build
cd packages/vscode-extension && pnpm run compile

# Watch mode (extension only)
pnpm start

Project layout

live-test-runner/
├── README.md               Overview and quick start
├── ARCHITECTURE.md         Full system design and data flow
├── DEVELOPER_GUIDE.md      This file
├── AI_CONTEXT.md           Paste-in doc for AI assistants
├── packages/
│   ├── core/               @live-test-runner/core
│   │   └── README.md
│   ├── runner/             @live-test-runner/runner
│   │   └── README.md
│   └── vscode-extension/   live-test-runner (the extension)
│       ├── README.md       User-facing docs
│       └── DEVELOPER_GUIDE.md  Points to this file
└── pnpm-workspace.yaml

Core patterns and practices

Observer pattern — how results propagate

All result consumers implement IResultObserver. SessionManager calls every registered observer after each file result. The UI never pulls — it only receives.

interface IResultObserver {
  onSessionStart(): void
  onRunStart(filePath: string): void
  onFileResult(result: FileRunResult, store: ResultStore): void
  onSessionStop(): void
}

To add a new panel, decoration layer, or any feature that reacts to test results:

  1. Create a class implementing IResultObserver
  2. Instantiate it in extension.ts
  3. Call sessionManager.addObserver(instance)

Nothing else changes.

Adapter pattern — framework support

Two adapter interfaces exist in the codebase:

  • FrameworkAdapter in packages/runner/ — handles binary resolution and config extraction. No VS Code dependency.
  • IFrameworkAdapter in packages/vscode-extension/ — adds VS Code-specific methods (test discovery, debug config, file classification).

The separation means the runner can be used independently of VS Code.

On the extension side a framework is a services bundle (FrameworkServices: adapter, projectConfig: IProjectConfig, batchRunner: IBatchRunner, instrumentedRunner, createSessionRunner()). SessionManager asks an IFrameworkServicesProvider for the bundle of a file or root (servicesFor) and never constructs framework classes; each project composes a FrameworkRouter with a factory per routable framework (Jest createJestServices, Vitest createVitestServices, pytest createPytestServices); it builds the bundle of the project's framework — or several in a mixed project, where it places every test file with one framework (see architecture.md → framework services). Adapters that run through a packages/runner CommandRunner extend RunnerBackedAdapter and add only detection, their runner and the debug config.

Adding a framework = an adapter in each package plus the extension-side bundle (batch runner, project config). SessionManager, ResultStore, all views, and all observers require zero changes.

Two stores, one source of truth per concern

ResultStore is the only place where test results live (pass/fail, output, failures). Uses a flat node pool (Map<string, TestNode>) with tree relationships via parentId/children, supporting unlimited nesting.

  • Node Types: Supports suite, test, and template.
  • Templates: Dynamic test headers (.each) are template nodes. They act as persistent anchors and are never removed by cleanupStaleNodes even if they have zero variations.
  • LineMap: Inside the store; stores only identity references — { nodeId, fileId } — never status or duration. DecorationManager always queries ResultStore.getNode(nodeId) at decoration time; decorations are never stale.

ExecutionTraceStore holds three derived indexes built from per-test JSONL trace files:

  • traceIndex — testId → path to .jsonl trace file
  • coverageIndex — source file → set of line numbers executed (session-accumulated)
  • sourceToTests — source file → test file → suite → { isSharedVars, testCases[] }

The trace files on disk are the ground truth. The store entries are caches. Rule: indexes are always rebuilt from trace files, never written independently. Clear both together on session reset.

JestBatchRunner populates ExecutionTraceStore after each file run (fire-and-forget background pass). SessionManager reads from it in _runAffectedBySourceFile when a source file is saved. Neither store writes to the other.

Output attribution

The runner reports console output at the file level only (this is a Jest/CRA limitation — test runners don't attribute individual console.log calls to specific tests). When a file runs, FileResult.output is set. Suite and test output are set only when that scope is individually rerun by name pattern.

Never back-fill. A test section that was never individually run shows a placeholder — it does not inherit the file-level output. This is correct behaviour, not a limitation.

Child process isolation

Jest always runs in a child process via Executor.ts. The extension host never imports or executes Jest code. This keeps the extension host memory-stable and prevents one failing project from crashing another.

Multi-Session Isolation (PID-based)

To support multiple concurrent VS Code windows, every extension instance must operate in a strictly isolated temporary directory.

  1. Partitioning: Session directories are named session-<pid>-<timestamp>.
  2. Injection: All runners and managers receive this directory via constructor injection. NEVER use global temporary constants for file writes.
  3. Safe Cleanup: On activate, scan the temp root and prune only session folders whose owning PID is inactive (verified via process.kill(pid, 0)).
  4. Per project: with several test projects in the window (monorepo / multi-root) each ProjectContext gets its own sub-folder session-<pid>-<ts>/p<N>-<name>; with one project it is the session folder itself.

Projects (monorepos, multi-root workspaces)

A window holds one ProjectContext per test project (src/project/): its own ResultStore, ExecutionTraceStore, CoverageStore, TestDiscoveryService + cache, framework services and SessionManager. The views, decorations and CodeLens are bound to the selected project (ProjectRegistry.select → bindProject / bind); each project's events reach them through its ProjectObserverGate only while it is selected.

  • Detection rules are pure and unit-tested in the runner (framework/projectDiscovery.ts, test/projectDiscovery.test.ts), per language family: jsProjectsInFolder — a folder with its own test config is one project; a monorepo root without one is split into its workspace packages that have tests; pythonProjectsInFolder — a folder configuring pytest (config or root conftest.py) is one project; a uv workspace root without one is split into its members with tests. Nested projects of the same family are dropped.
  • New per-project state goes into ProjectContext, never a window-wide singleton; anything a view shows must be re-bindable.
  • The Explorer, Results panel and status bar follow the selected project; editor features (gutter icons, inline durations, CodeLens, coverage bars, coverage hover) resolve each file to its own project (editor/FileStores.ts, ProjectRegistry.forFile) and hear every project's events (editorObservers — the gate forwards to them regardless of selection).
  • Commands act on the selected project; commands that get a file (rerunScope, rerunFromEditor, debugFromEditor, openTimelineDebugger, saves) go to the file's project (ProjectRegistry.forFile).
  • Try it: node e2e/run.js monorepo-select monorepo-run monorepo-stop pytest-monorepo (fixtures monorepo-jest, monorepo-vitest, monorepo-pytest).

Use spawn, never exec. exec has a buffer limit that silently truncates large outputs. spawn streams.

Logging

Two output channels, two purposes:

Channel Written by Content
Live Test Runner (LogOutputChannel) logger.scope('Area') The extension's own log — levelled, timestamped
Live Test Runner: Test Output (plain) Executor raw sink Jest process output, ANSI-stripped, line-buffered, tagged [jest#N]

How to log

// extension
import { logger } from '../utils/logger';
const log = logger.scope('Session');
log.info('Session started — 58 test file(s)');
log.warn('Falling back to plain Jest', err);   // err → " — <message>"
log.error('Could not start Jest', err);        // err → message + 6 stack frames

// runner / core (no vscode dependency)
import { createLogger } from './utils/logger';
const log = createLogger('Executor');

runner's setLogSink() is installed by logger.init(), so runner/core logs land in the same channel.

Choosing a level

Level Use for Example
error Broken, needs action Jest binary not found, cannot read results
warn Degraded but recovered, or a user problem that blocks results Fallback to plain Jest, test file failed to run, file not instrumented
info Milestones — about one line per user action Activation, discovery summary, Run #N … summary
debug Details useful when diagnosing Batch start/end, spawn/exit, coverage merge counts
trace Per-file chatter Instrumenting x.ts, cache hit, per-file coverage %

Rules:

  • One summary line per run, not one per file. Per-file detail belongs at debug/trace.
  • Put the cause in the message: when Jest fails, include its stderr tail (tail() from runner).
  • Never write extension diagnostics to the Test Output channel. It holds only Jest's output, plus ──── Run #N ──── separators.
  • Correlation tags: Run #N (SessionManager), bN (JestBatchRunner batch), jest#N (Executor process).

Logging from inside the Jest / Vitest process (instrumentation .js / .mjs files, incl. the Vitest trace's wrapper-config helper and plugin): write [LTR:<level>] message\n to stderr. Executor routes those lines to the log at that level and strips them from captured stderr. LTR_LOG_LEVEL (set from the channel level) lets the scripts skip debug/trace writes:

const _LTR_RANK = { trace: 0, debug: 1, info: 2, warn: 3, error: 4 };
const _ltrMin = _LTR_RANK[process.env.LTR_LOG_LEVEL] ?? _LTR_RANK.info;
function _ltrLog(level, msg) {
  if (_LTR_RANK[level] < _ltrMin) { return; }
  // One line per message — continuation lines would leak into the raw output
  const text = String(msg).replace(/\s*Require stack:[\s\S]*$/, '').replace(/\s*\r?\n\s*/g, ' ↵ ');
  process.stderr.write(`[LTR:${level}] ${text}\n`);
}

Diagnostics — Live Test Runner: Copy Diagnostic Report builds a Markdown report (versions, project setup, settings, last 300 debug+ log lines from an in-memory ring buffer, even when the channel is at info). Ask users for it in bug reports.

Session guard

All on-save behavior and CodeLens buttons are session-guarded. Nothing runs in the background. Users explicitly start and stop sessions. This keeps resource usage predictable and prevents surprise background work.

Smart on-save reruns

On-save runs are debounced at 300ms (configurable). Rapid successive saves only trigger one run.

When a source file (non-test) is saved, the rerun scope is determined by _runAffectedBySourceFile:

  1. Trace data available (after at least one full run, Jest and Vitest): ExecutionTraceStore.sourceToTests is queried. For each affected test file, suites with isSharedVars: false rerun only their specific affected test cases (one process per file with a combined --testNamePattern / -t); a file where every test that is not skipped is affected reruns whole (a batch, coverage measured again). Suites with isSharedVars: true rerun the whole file.
  2. No trace data yet, or the trace is off for the root (FrameworkServices.traceOffReason — Vitest: setting off, Vitest < 3, a failed wrapper; see session/VitestTrace.ts): the framework's related run reruns whole test files. A batch runner with runRelated (Vitest) runs it as a live batch — vitest related <src> --run, files show running as Vitest starts them, coverage of the saved file is measured again; otherwise the adapter's plain runRelatedTests (jest --findRelatedTests).

When the framework's config file is saved (FrameworkServices.isConfigFile: jest.config.*, vitest.config.*, vite.config.*, vitest.workspace.* in the root, or the config the test script names), the session restarts: config, runnable files and every result are re-read.

When a test file is saved, the whole file always reruns — discovery handles any structural changes.

Static test discovery

TestDiscoveryService runs automatically on extension activate — before the user clicks Start Testing.

  • Uses @babel/parser + @babel/traverse (lazy-loaded from the project's own node_modules). No extra dependencies.
  • Parses files in batches of 8 with a setImmediate yield between batches. Safe on 500+ file projects.
  • Dynamic Anchors: discoverTests identifies .each calls and creates template nodes. These provide a stable UI target even before Jest runs.
  • Calls store.nodeStarted / store.nodeResult to build the hierarchical node tree — no-ops if the entry already exists so live run results are never overwritten.
  • Calls IResultObserver.onDiscoveryProgress on every file. Observers are free to ignore it if they don't implement the optional methods.
  • SessionManager.start() awaits discovery.awaitDiscovery() instead of running its own discovery. On a normal project load this is already resolved; it only blocks if Start Testing is clicked during the first discovery pass.

CodeLens registration

The CodeLensProvider is registered with vscode.languages.registerCodeLensProvider on extension activate — not on session start. Lenses appear as soon as TestDiscoveryService populates the first LineMap entry. The provider calls refresh() on every onDiscoveryProgress event so buttons appear incrementally as files are parsed.


Using the Timeline Debugger

The Timeline Debugger runs a single test case through an instrumented Jest transform, records every executed line and variable state, then lets you step through the replay.

Activate from the editor:

  1. Start a Live Test Runner session (▶ Start Testing)
  2. Click the ⏱ Timeline CodeLens that appears above any it() or test() line

Activate from the sidebar:

  • Click the ⏱ button on any test row in the Explorer sidebar

On activation the Results panel switches to Timeline mode and a loading spinner appears while the trace runs. When complete:

  • The timeline bar shows one box per executed step. Click any box or use the playback controls (⏮ ◀ ▶ ▶| ⏭ ⏸) to step through.
  • The editor highlights the active line and shows variable values as ghost text inline.
  • The sidebar shows State (variables at the current step), Watch (pin variables), and Call Stack.
  • The Console and Errors tabs in the right column show logs and failures.

Zoom: scroll the mouse wheel over the timeline bar to zoom between line / function / file grouping levels.

Re-run: click the ↺ Re-run button in the sidebar header to run the trace again.

Exit: click any normal test row in the sidebar to return to normal mode. All timeline decorations are cleared.


Adding a new instrumented framework

The Timeline Debugger uses IInstrumentedRunner as its framework boundary. Adding Vitest or Mocha timeline support = one new file. Nothing else changes.

// packages/vscode-extension/src/timeline/VitestInstrumentedRunner.ts
import { IInstrumentedRunner } from './IInstrumentedRunner'
import { TimelineStore } from './TimelineStore'

export class VitestInstrumentedRunner implements IInstrumentedRunner {
  async run(options: { filePath: string; testFullName: string; projectRoot: string }): Promise<TimelineStore> {
    // 1. Create a temp file for JSONL trace output
    // 2. Configure Vitest to load your instrumentation transform
    // 3. Spawn Vitest via Executor or directly
    // 4. Parse the JSONL trace into a TimelineStore (reuse parseEvents logic)
    // 5. Return the store
  }

  cancel(): void { /* kill the child process */ }
}

In extension.ts, swap new JestInstrumentedRunner() for new VitestInstrumentedRunner() — or add auto-detection logic based on the project root.

Key files to understand:

  • timeline/instrumentation/traceTransform.js — the Jest regex-based transform (adapt for Vitest's transform API)
  • timeline/instrumentation/traceRuntime.js — the __trace runtime (reuse as-is — it just writes JSONL)
  • timeline/JestInstrumentedRunner.ts — the full Jest implementation to follow as a reference

Adding a new framework

Supporting Vitest, Mocha, or any other framework requires one class in each of two packages. No other files change.

A framework that is not JavaScript (pytest is the example): give the runner adapter a family (python), return an absolute executable from resolveBinary (the Executor spawns it directly, no shell), turn off the JS environment (CommandRunner.jsEnv), override runNamed in the extension adapter when tests are selected by id rather than a name pattern, give the bundle a TestFileDiscoverer (ProjectContext), projectConfig.sourceExtensions (which saves rerun tests), configFileNames (config files that are not source files), and a batchPolicy when its projects cannot run two processes side by side. whyNotReady stops a Start that cannot run (a missing interpreter).

Step 1 — Runner package

Create packages/runner/src/framework/adapters/YourAdapter.ts (the sketch below uses Vitest; the shipped VitestAdapter.ts is the real reference — it resolves package.json#bin with node instead of a .bin shim, gates capabilities() on the installed version, and checks the Node runtime):

import { FrameworkAdapter } from './FrameworkAdapter'
import { FrameworkCapabilities, FrameworkId } from '../../types'
import * as fs from 'fs'
import * as path from 'path'

export class VitestAdapter implements FrameworkAdapter {
  readonly framework: FrameworkId = 'vitest'   // open string id — add it to FRAMEWORK_IDS if shipped

  detect(projectRoot: string): boolean {
    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'))
    return !!(pkg.dependencies?.vitest || pkg.devDependencies?.vitest)
  }

  resolveBinary(projectRoot: string): string {
    return path.join(projectRoot, 'node_modules', '.bin', 'vitest')
  }

  async resolveConfig(projectRoot: string): Promise<string | undefined> {
    return undefined  // vitest discovers its own config
  }

  getExtraArgs(projectRoot: string): string[] {
    return []
  }

  capabilities(projectRoot: string): FrameworkCapabilities {
    return { results: true, nameFilter: true, listTests: true, related: true, liveStream: false, coverage: true }
  }

  outputFileArg(file: string): string[] {
    return [`--outputFile=${file}`]   // the runner's own "write JSON here" flag
  }

  parseResult(passed: boolean, raw: string, stderr: string): RunResult {
    return parseVitestJson(passed, raw, stderr)
  }

  createRunner(options?: RunnerOptions): TestRunner {
    return new VitestRunner(options?.command, options?.logger, options?.tmpDir)
  }
}

// VitestRunner extends CommandRunner and only builds Vitest's args:
//   detectAdapter(root), buildArgs({ kind: 'list' | 'full' | 'files' | 'testCase' | 'related' }),
//   parseTestList(result, root), coverageFile(root)

Register it in FrameworkRegistry.default() (packages/runner/src/framework/FrameworkRegistry.ts) — higher priority is tried first:

new FrameworkRegistry()
  .register(new CRAAdapter(), ADAPTER_PRIORITIES.cra)      // 300
  .register(new VitestAdapter(), ADAPTER_PRIORITIES.vitest) // 200 — before Jest
  .register(new JestAdapter(), ADAPTER_PRIORITIES.jest)    // 100

Export from packages/runner/src/index.ts.

Step 2 — Extension package

Create packages/vscode-extension/src/framework/VitestAdapter.ts:

export class VitestAdapter implements IFrameworkAdapter {
  async detect(projectRoot: string): Promise<boolean> { ... }

  async discoverTests(projectRoot: string, log: OutputChannel): Promise<string[]> {
    // run vitest --listTests equivalent
  }

  getFileGlob(): string {
    return '{**/*.test.*,**/*.spec.*}'
  }

  isTestFile(filePath: string): boolean {
    return /\.(test|spec)\.[jt]sx?$/.test(filePath)
  }

  async runFile(store: ResultStore, filePath: string, projectRoot: string, log: OutputChannel): Promise<void> { ... }

  async runTestCase(store: ResultStore, filePath: string, fullName: string, projectRoot: string, log: OutputChannel): Promise<void> { ... }

  getDebugConfig(projectRoot: string, filePath: string, testFullName?: string): DebugConfiguration {
    return {
      type: 'node',
      request: 'launch',
      name: 'Debug Vitest',
      program: path.join(projectRoot, 'node_modules', '.bin', 'vitest'),
      args: [filePath, '--testNamePattern', testFullName ?? ''],
      cwd: projectRoot,
      // Started by the debugger itself, output in the Debug Console: a command
      // typed into the integrated terminal can be lost (Debugging: design, D8).
      console: 'internalConsole',
      outputCapture: 'std',
    }
  }
}

Step 3 — Services bundle

Write packages/vscode-extension/src/framework/vitestServices.ts returning a FrameworkServices (see jestServices.ts): the adapter above, an IProjectConfig, an IBatchRunner, an IInstrumentedRunner, createSessionRunner() (the runner adapter's createRunner()), displayName and settingsFingerprint(). Register it with the router: add the id to ROUTED_FRAMEWORKS (runner framework/allowedFrameworks.ts) and its factory to the FrameworkRouter in ProjectContext (one router per project, so projects never share a batch runner). When a root can hold it next to another framework, add its marker to projectFrameworks (runner framework/frameworkRouting.ts) — the router then lists with every framework in play and places each file once. If its runner refuses roots of other frameworks, check isFrameworkAllowedAt(root, '<id>') as JestRunner / VitestRunner do. SessionManager needs no change.

Checklist

Runner package (packages/runner):

  • FrameworkAdapter implemented — detect, resolveBinary, resolveConfig, getExtraArgs, outputFileArg, parseResult, capabilities (per installed version, never throws), createRunner
  • A CommandRunner subclass — detectAdapter (another framework's project → refusingAdapter(adapter)), buildArgs for every RunRequest kind (list, full, files, testCase, related; testCase.updateSnapshots → the framework's snapshot-update flag, or ignore it if the framework has no snapshots), parseTestList, coverageFile; leadingArgs if the CLI needs a subcommand first; processLabel for the [label#N] output tag
  • Registered in FrameworkRegistry.default() at the right priority (a project several adapters claim goes to the higher one)
  • Exported from src/index.ts
  • Conformance suite — one describeAdapterConformance({ … }) call in test/adapterConformance.test.ts (matching / non-matching projects, a canned result with one passing and one failing test); it must pass unchanged
  • Command-line snapshot tests for the new runner (like test/jestRunnerArgs.test.ts)

Extension package (packages/vscode-extension):

  • IFrameworkAdapter implemented
  • IProjectConfig, IBatchRunner and (or a "not available" stand-in for) IInstrumentedRunner
  • A services bundle, composed in extension.ts
  • Instrumentation that runs inside the test process in src/session/instrumentation/<framework>/, keeping the protocol in docs/development/architecture.md → Session instrumentation protocol (reuse shared/), and copied by esbuild.js
  • SessionManager, ResultStore, views and observers untouched

Verification:

  • An e2e fixture + scenarios (e2e/fixtures/<framework>-basic, full run / scoped run / stop / hang / on-save / debug)
  • Real repositories in e2e/real-repos.js; the regression gate (build, lint, unit, e2e/run.js --all, real repos) green
  • Docs: framework feature matrix (README + guide), both CHANGELOGs, docs/development/architecture.md, docs/development/ai-context.md

Adding an AI-assistant tool

  1. Add the tool to TOOLS in src/ai/catalog.ts: an LTR_ name, a description that says when to use it (agents choose tools by it), an input schema, acts: true if it starts or changes anything.
  2. Answer it in AiTools._dispatch (src/ai/tools.ts). Read through BridgeHost / BridgeProject (src/ai/host.ts); act only through the session's own methods or existing commands. Keep the answer small (limits, caps, ids) and include this._freshFlags().
  3. Regenerate package.json's languageModelTools: UPDATE_LM_TOOLS=1 npx jest test/aiCatalog.test.ts (from packages/vscode-extension).
  4. Test it in test/aiTools.test.ts (real stores, fake host); the relay needs no change (it lists the catalog).
  5. Tool names are a public API: a rename or removal needs a changelog line. Anything new it shares goes in PRIVACY.md.

To try the relay by hand: build, open a project in the Extension Development Host, then from that project's folder run node <globalStorage>/mcp/live-test-runner-mcp.js and type {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"LTR_get_status","arguments":{}}}. The launcher path is on the Connect Your AI Assistant page.

Adding a new observer (panel, decoration, etc.)

  1. Implement IResultObserver from src/IResultObserver.ts
  2. Instantiate in extension.ts
  3. Add it to the observers array there — it receives the selected project's events (each project's ProjectObserverGate forwards them while that project is shown). If it holds a store reference, give it a bind(...) and call it from the onDidChangeSelection handler so it follows a project switch.

The observer receives:

  • onSessionStart() — session began
  • onRunStart(filePath) — a file started running
  • onFileResult(result, store) — a file's results are available
  • onSessionStop() — session ended

Read from ResultStore to get any data you need. Never cache a copy of result data in your observer — query the store at use time.


Webview communication

Webviews communicate with the extension host via postMessage. The routing is in BaseWebviewProvider._onMessage().

Extension → webview:

this._panel.webview.postMessage({ type: 'full-file-result', payload: { ... } })

Webview → extension:

window.vscode.postMessage({ type: 'rerun', payload: { filePath } })

Rules:

  • Use distinct type strings. Never infer intent from payload shape.
  • scope-logs and scope-changed are always sent separately — they have different lifecycles.
  • full-file-result drives column 1 on every run.
  • scope-logs drives columns 2 and 3 only when selection changes or a run completes for the selected scope.

Duration thresholds

Thresholds are per-level and user-configurable. The logic lives in two places:

  • src/utils/duration.ts — TypeScript; used by DecorationManager and passed to webviews via the init message
  • src/webview/utils.js — plain JS mirror; exposes window.LiveTestUtils; used inside the webview sandbox

The extension reads thresholds via getThresholds() on session start and sends them in the init message. Webviews call LiveTestUtils.setThresholds(msg.thresholds) on receipt.

Never hardcode thresholds in the webview. Always use LiveTestUtils.


Configuration

All user settings are in packages/vscode-extension/package.json under contributes.configuration.properties.

Read in extension code:

const config = vscode.workspace.getConfiguration('liveTestRunner')
const debounce = config.get<number>('onSaveDebounceMs', 300)

Do not hardcode defaults in extension code — always read from config with a sensible fallback so users can override.

hangTimeoutSeconds (default 300) is the longest a single test may run in an instrumented batch before the batch is stopped and that file failed (measured from the setup file's heartbeats, so loading a file does not count). Plain fallback runs get 3× that as a wall-clock limit.

runMode — npm test integration

liveTestRunner.runMode controls how tests are invoked:

Value Behaviour
"auto" (default) Extension resolves Jest directly and calls it with --json --outputFile --no-bail --testLocationInResults. Full structured output: per-test durations, console capture, gutter icons, scope-level reruns, ◈ Results.
"npm" Extension delegates to npm test --. Works for projects where the Jest binary is wrapped or the test script is non-standard. Limitation: the extension appends --json but cannot guarantee npm test passes it through unchanged. Per-test durations, console capture, and location data may be absent or degraded. jestCommand is ignored in this mode.

Handled in JestAdapter._getCommand() — returns "npm test --" when runMode is "npm", otherwise returns jestCommand (or empty string for auto-detection).


Branching and pull requests

Flow: main → release/x.y.z (created from main) ← feat/*, bugfix/*, hotfix/* via PR. When the batch is ready, one PR release/x.y.z → main carries the version bump and changelogs. Merging it releases.

  • Never commit, push or merge directly to main or release/*. Create a branch for all work.
  • Branch names start with release/, feat/, hotfix/ or bugfix/.
  • main accepts PRs only from release/* and hotfix/*.
  • release/* accepts PRs from feat/*, bugfix/*, hotfix/* and dependabot/*.
  • bugfix/* PRs target a feat/* or release/* branch, never main.
  • feat/* branches can branch from other feat/* branches and PR back into that feature or into a release/*.
  • Dependency updates: Dependabot (.github/dependabot.yml) opens one grouped PR a week per ecosystem (npm, GitHub Actions) for minor and patch versions, a separate PR for each major version (test and fix it on its own), and security fixes as they come. Major versions of @babel/parser are never offered: it ships inside the extension and runs on the user's Node. @types/vscode and @types/node majors follow Supported versions, not the latest release. They open against main, where Branch rules fails them with a note; change the base to the release/* branch they should ship in, then merge.
  • Supply chain: pnpm-workspace.yaml sets minimumReleaseAge (7 days), so pnpm will not install a version published less than a week ago; wait, or list the package in minimumReleaseAgeExclude for an urgent security fix. Its overrides pin vulnerable packages that only our dev tooling pulls in to their first fixed version in the same major; drop an entry once its parent depends on a fixed one (check with pnpm audit). Before taking an update, check whether it ships in the extension (@babel/parser, picomatch — bundled into out/) or only runs here: shipped code runs on the user's Node and VS Code, so it needs the full e2e suite.
  • PRs fail if tests fail. PRs to main fail if the version has not been bumped.

.github/workflows/pr-checks.yml enforces this on every PR with three jobs: Branch rules (name prefix and allowed targets), Tests (pnpm test, plus the docs-link and supported-versions checks), and Version bump (PRs to main) (root and extension package.json versions must be higher than on main).

One-time GitHub setup (Settings → Branches): add a rule for main and another for release/*. For both: require a pull request before merging, require status checks Branch rules and Tests, and disallow direct pushes and force pushes (include administrators). On main also require Version bump (PRs to main). .github/CODEOWNERS names the maintainer as owner of every file, and both rules require a code owner's approval, so every contributor's PR into main or release/* needs the maintainer's approval. Only the maintainer can create release/* branches. GitHub doesn't let authors approve their own PRs, so the maintainer merges their own PRs through the admin bypass.

Supported versions

The oldest VS Code and Node the extension supports follow one rule, from official release data: a Node major is supported until 2 years after its end of life (the Node.js release schedule). The minimum VS Code is the first release whose bundled Node (its Electron's) is still supported. Code that runs in the user's own test process — the shipped Babel parser, the instrumentation — must run on the oldest supported Node major.

node scripts/support-floor.js prints the window and checks the repository against it (data in scripts/support-floor.json; --update refreshes it from the Node schedule, Electron's release list and VS Code's release tags):

  • engines.vscode (root and extension) is not above the minimum — raising it early drops users the policy still covers;
  • @types/vscode equals engines.vscode, @types/node (extension, runner) and the esbuild targets (esbuild.js, jest.esbuild.js) match the Node inside that VS Code — newer types allow APIs the oldest supported VS Code lacks;
  • every third-party package the build ships (SHIPPED in the script, cross-checked against esbuild.js) declares an engines.node that the oldest supported Node satisfies, and is not an ES module.

The PR checks run it (--check). The monthly workflow support-floor.yml opens an issue when the minimum may be raised; raising it is done in a release branch (the issue lists the steps) and goes in both changelogs. Users on an older VS Code keep the last extension version that supports it.

Security checks

.github/workflows/security.yml runs on every PR, on main and weekly:

  • Dependency audit — node scripts/security-audit.js (pnpm audit, GitHub's advisory database). Fails on any advisory in code that ships in the extension (scripts/shipped-packages.js) and on high or critical ones anywhere else; lower ones in dev tooling are listed. Fix by updating, by an overrides entry in pnpm-workspace.yaml, or — only when no fix exists — by auditConfig.ignoreGhsas there, with a comment saying why.
  • Dependency review (PRs) — GitHub's action blocks a PR that adds a package with a high advisory or a license outside the allow list.
  • CodeQL — static security analysis (security-extended queries) of our JS / TS, the Python pytest plugin and the workflows; findings in Security → Code scanning.

No network calls (project rule G12) is a unit test, packages/vscode-extension/test/noNetwork.test.ts, so it runs in Tests: the bundle may require only the Node modules in its BUNDLE_MODULES allowlist (each with its reason), sources and shipped code may use no network module or API (http, https, http2, net, tls, dgram, dns, fetch, XMLHttpRequest, WebSocket, sendBeacon, EventSource; Python socket, urllib, requests…) and no telemetry package, runtime dependencies are only workspace packages, and every webview CSP lists only local sources. The guide that ships in the extension is built by src/guide/offlineGuide.js (from copyGuide() in esbuild.js): remote pictures become links to the online guide, and any other remote resource fails the build. To check by hand: grep -oE 'require\("[^"]+"\)' packages/vscode-extension/out/extension.js | sort -u.

Alongside: Dependabot (weekly updates, security fixes as they come), minimumReleaseAge (no version younger than 7 days), secret scanning with push protection (repository settings), and private vulnerability reports (SECURITY.md).

Publishing

Releases are automatic. Merging a release/* (or hotfix/*) PR into main runs .github/workflows/release.yml: build → test → publish to VS Code Marketplace and Open VSX → on success, create the vX.Y.Z tag and a GitHub Release. If publishing fails no tag is created; fix and re-run the workflow. Do not push release tags manually.

Before opening the release/* → main PR:

  1. Bump the version in the root package.json and packages/vscode-extension/package.json
  2. Update both CHANGELOG.md files
  3. Run pnpm run build from the root to verify everything compiles

To test a package locally: cd packages/vscode-extension && pnpm run build && vsce package (produces a .vsix).

Website. .github/workflows/pages.yml publishes the project website to GitHub Pages when site/, the guide, the screenshots or the workflow change on main (release branches do not publish — the site shows what is released): site/index.html (marketing landing page) and site/sitemap.xml at https://eshandias.github.io/live-test-runner/, docs/live-test-runner-guide.html at /guide/, packages/vscode-extension/resources/images/*.png at /images/, and the slider's resources/gifs/scene-*.gif at /gifs/. One-time setup: repository Settings → Pages → Source: GitHub Actions. SEO: the landing page carries the meta description, canonical URL, Open Graph / Twitter tags and JSON-LD (SoftwareApplication + FAQPage; keep its FAQ text in sync with the visible FAQ). Add the Google Search Console verification tag where the comment in <head> says, then submit sitemap.xml there; update the sitemap's lastmod when the pages change. A robots.txt is not used: on a github.io project site it would sit under /live-test-runner/, where crawlers don't look. Reviews can't be posted from the site (both marketplaces need sign-in on their own pages), so it links to the VS Code Marketplace and Open VSX review pages. The same file is copied to out/guide/guide.html by esbuild.js and shown by the Open Guide command (views/GuidePanel.ts), so the guide links to the other docs with absolute GitHub URLs. Links that leave a page (external URLs, and the site's links to the guide) open in a new tab (target="_blank" rel="noopener"); in-page #anchor links don't. Keep the guide (and, for headline features, the landing page) up to date with every important change — see CLAUDE.md → Documentation Maintenance.

Wiki. The Wiki is generated from docs/; never edit it on GitHub. Wiki editing is restricted to collaborators, and .github/workflows/wiki.yml replaces every page on each publish, so an edit made there is lost. To change a page, edit its file in docs/ in a pull request. scripts/build-wiki.js turns each file into a page named after its # heading (docs/README.md becomes Home), rewrites the links between them, builds the sidebar in the order of docs/README.md, and adds a footer that links each page to its source. The PR checks run node scripts/build-wiki.js --check, which fails on a broken link.

When it updates: on every push to main that touches docs/, i.e. with each release, as the website does, so the Wiki describes the version users have installed. A docs-only fix that shouldn't wait for the next release (a wrong instruction, a broken link): merge it into the open release/* branch, then Actions → Publish Wiki → Run workflow on that branch. That publishes the branch's docs/ as it is, including pages for anything else already merged there, so check that the branch holds nothing unreleased first.

What goes into the .vsix is set by packages/vscode-extension/.vscodeignore (npx @vscode/vsce ls --no-dependencies lists it). Sources are bundled into out/, but the webviews load their HTML / JS / CSS from src/webview at runtime, so that folder must stay in the package.


Testing

Run all tests:

pnpm run test

Per-package:

cd packages/runner && pnpm run test

Unit tests live in packages/*/test/*.test.ts and import src/ directly — the root jest.esbuild.js transformer compiles TypeScript with esbuild (no build step). Runner: Executor (arguments verbatim, process-tree kill, timeouts), config helpers. Extension: modules without a VS Code dependency (ResultStore, utils/testNames). Keep VS Code-free logic in such modules so it stays unit-testable.

pnpm lint uses the root eslint.config.mjs (ESLint flat config, TypeScript files only); both run in the PR checks.

End-to-end tests

e2e/ drives the real extension inside a real VS Code against real Jest:

pnpm build                                   # the e2e run uses packages/vscode-extension/out
node e2e/run.js --all                        # every scenario whose workspace is available
node e2e/run.js basic-stop basic-hang        # selected scenarios
LTR_E2E_DEBUG=1 node e2e/run.js basic-hang   # debug-level logs (also inside Jest)
# Test what is actually published: package, unpack, point the suite at it
(cd packages/vscode-extension && npx @vscode/vsce package --no-dependencies -o /tmp/ltr.vsix)
unzip -q /tmp/ltr.vsix -d /tmp/ltr-vsix && LTR_E2E_EXTENSION_DIR=/tmp/ltr-vsix/extension node e2e/run.js --all
  • Launcher (e2e/run.js) starts VS Code with --extensionDevelopmentPath, an isolated user-data dir and --extensionTestsPath=e2e/lib/hostEntry.js, and prints the report. VS Code: VSCODE_EXE, else the local install, else (or with LTR_E2E_VSCODE=download|stable|<version>) a build downloaded into .vscode-test/ by @vscode/test-electron. Full logs land in LTR_E2E_RUNS_DIR (default %TEMP%\ltr-e2e-runs on Windows, /tmp/ltr-e2e elsewhere — short, because VS Code's IPC socket path must stay under ~103 characters): <scenario>/extension.log, jest-output.log, report.json. After each scenario (and on Ctrl+C or a timeout) it kills every process naming that run's user-data dir, with their descendants (e2e/lib/leftovers.js): the launched process can exit while its window keeps running. diag-* scenarios are investigation tools and are not part of --all.

  • Copies in the temp folder: fixture copies (<tmp>/ltr e2e) and real-repo clones (<tmp>/ltr real repos) are kept between runs. macOS empties temp files untouched for 3 days and keeps the folders, so the scripts check a copy first (e2e/lib/emptied.js: packages whose package.json, main or bin file is gone, beyond those already so right after the install or in the original; top-level files the original has) and reinstall or copy again. scripts/perf-measure.js does the same for its copies in <tmp>/ltr perf.

  • CI: the E2E job in .github/workflows/pr-checks.yml runs --all on Windows, Linux (under xvfb-run) and macOS with a downloaded stable VS Code, and uploads the logs when it fails.

  • What the fixtures cover — each one encodes problems found on real projects:

    Fixture Covers
    basic plain Jest 29 in a path with spaces; verbose: true; names with ^ | &; skip / todo; .each (%s and $var tables); duplicate test names; jest.mock('fs'); a setupTests.js with hooks; --resetMocks in the test script; nested ?.; files Jest's config excludes (e2e/, .mjs)
    ts-config jest.config.ts + ts-jest + a path alias only that config defines
    esm-fn-config jest.config.mjs exporting an async function
    cra Create React App: react-scripts' own Jest 27, jsdom, setupTests.js with hooks, react-scripts test --resetMocks

    Every fixture's full run is compared file by file with plain Jest (checkMatchesPlainJest). When a real project shows a new problem, reproduce it in a fixture (or a new one) so CI keeps catching it.

  • Fixtures (e2e/fixtures/<name>) are copied to %TEMP%/ltr e2e/<name> project — a path with spaces on purpose — and npm installed once (again when package.json changes).

  • Scenarios (e2e/scenarios/*.js) export { workspace, timeoutMs, settings?, prepare?, run({ api, t, vscode, workspace, workspaces }) }. prepare(folders) adjusts the fresh fixture copy before the window opens (a variant of a fixture without a second install: angular-coverage-include adds coverageInclude to angular.json). workspace is fixture:<name>, env:<VAR> or a path — or an array of them for a multi-root window (e2e/run.js writes an e2e.code-workspace in the run folder; workspaces lists every folder, workspace is the first). Every folder of a fixture with a requirements-e2e.txt gets its own .venv (kept between runs, like node_modules, at any depth). With LTR_E2E=1 the extension's activate() returns its internals (store, session, traceStore, coverageStore, observers, rawOutput, …) — never in normal use. Helpers are in e2e/lib/harness.js (wait for discovery, record observer events, Jest summaries from raw output, Jest / Vitest processes still alive — Vitest renames its processes to node (vitest), so vitestProcesses() matches those titles —, edit + save through VS Code, plain Jest / Vitest reference runs and per-file comparisons).

  • Monorepo scenarios: fixture:monorepo-jest (npm workspaces: two Jest packages — one with its own config, one with only a jest test script — and a package without tests) runs monorepo-select (detection, switching, the maxRunningProjects refusal, projectRoot pinning) and monorepo-stop (Stop on one project leaves the other running; each project's Jest CLI is found by its session folder in --config); fixture:monorepo-vitest (a Vitest package with two test.projects and one configured only by its test script) runs monorepo-run (two projects at once, switching while both run, results per project vs plain Vitest groups, a background on-save rerun). api.projects is the ProjectRegistry; api.store / api.session / … are the selected project's.

  • Mixed-framework scenarios: fixture:mixed-same-package (Jest *.test.js + *.jest.js, Vitest *.test.js + *.vitest.js, Jest 29.7 + Vitest 3.2.4, a source file both load) runs mixed-full-run (each file's framework — its results only pass under the right one —, Explorer groups, the warning for a file both configs match, status-bar split, merged coverage, ▶ Run), mixed-on-save (test and source saves, a file moving to Vitest, config restart) and mixed-stop; fixture:mixed-monorepo (a Jest, a Vitest and a mixed package) runs mixed-monorepo.

  • pytest scenarios run on fixture:pytest-basic (a src/ package, tests/ with classes, parametrize, unittest, a collection error, fixtures that fail; its own .venv from requirements-e2e.txt, built by e2e/run.js with a Python ≥ 3.12 — LTR_E2E_PYTHON or the newest python3.x on PATH): pytest-full-run (vs a plain pytest JUnit run, checkMatchesPlainPytest), pytest-scoped-run, pytest-on-save, pytest-stop, pytest-hang, pytest-coverage (totals vs coverage.py's own report), pytest-debug, pytest-related; fixture:pytest-no-pytest runs pytest-no-pytest; fixture:monorepo-pytest (a uv workspace, one .venv at its root) runs pytest-monorepo; fixture:monorepo-pytest-venvs (two services under services/, each with its own .venv, nothing shared — their tests assert sys.prefix) runs pytest-venv-per-service; [fixture:vitest-basic, fixture:pytest-basic] as two workspace folders runs multi-root-js-python (switcher, Python chip only for pytest, saves wake only their project); fixture:mixed-js-python (Jest + pytest at one root) runs mixed-js-python, fixture:mixed-js-python-monorepo (a Jest root + a backend/ pytest project) runs mixed-js-python-monorepo. repo-pytest runs on real Python repos (kind pytest in the local config, e.g. click, httpx, erdantic on pytest 7, pytest itself — heavy) through real-repos.js, which points each clone's editable installs at the clone and drops copied __pycache__; baseline in the local e2e/baselines/pytest.json. The plugin's own tests: python -m pytest packages/runner/python-tests (CI job pytest plugin, pytest 7.4 / 8.4 / 9.1).

  • Vitest scenarios run on fixture:vitest-basic (Vitest 3.2.4): vitest-full-run, vitest-scoped-run, vitest-session (guard, test / source-file saves, ▶ Run, after Stop), vitest-stop, vitest-hang, vitest-debug; repo-vitest runs on real Vitest repos through real-repos.js.

  • Real projects: LTR_E2E_TSJEST_REPO (+ LTR_E2E_TSJEST_BASELINE, a jest --json result to compare every file with) for repo-tsjest; LTR_E2E_CRA_REPO for repo-cra (quick by default; LTR_E2E_CRA_FULL=1 + LTR_E2E_CRA_BASELINE for the whole project). repo-tsjest edits one source file and restores it byte-for-byte; repo-cra never writes to the project.

  • Real-repository matrix: node e2e/real-repos.js (light repos) / jest (the heavy monorepo) / --all / --fresh runs those scenarios on a copy of each configured repo (e.g. unplugin, slidev, vueuse — repo-vitest), computes the plain Jest / plain vitest run baseline itself, and fails if the original repository changed. Which repositories, and where they are, comes from a local config: copy e2e/real-repos.example.json (public open-source projects) to e2e/real-repos.local.json and point each entry's path at your clone (kind: jest, cra, vitest, components, pytest; heavy = only with --all or by name; env = extra scenario variables). The local config and the baselines each run records (e2e/baselines/, per-file plain-runner counts) are gitignored — test against private projects without them ever reaching the repository.

Screenshots and demo GIFs (README, website, guide) are recorded from the real UI, not drawn by hand. diag-* scenarios are never part of --all; VS Code gets a DevTools port and the scenario captures itself through it (e2e/lib/devtools.js):

  • diag-screenshots, diag-screenshots-monorepo — the mixed-project and monorepo-switcher screenshots.
  • diag-demo-jest / -vitest / -pytest (e2e/lib/demo.js) — the same story on the clean fixture:demo-* shop projects: Start (live tree, Running card, gutter icons), a source edit + save rerunning only its tests (red, then green), the coverage hover, ▶ Run on one test and its output. Each step is a clip of screenshots taken in a loop (recorder: Page.startScreencast leaves webviews blank) plus stills (<fw>-coverage-hover.png, <fw>-results.png).
  • diag-perf — performance numbers on a large project of any framework (discovery cold / warm, first result of the open file, full run, trace and coverage parse time, memory, extension-host CPU, one save rerun). Run it through node scripts/perf-measure.js <project> [--label name] [--open file] [--no-plain] [--no-save] [--in-place], which also times the plain framework run (Jest, Vitest, Angular ng test or pytest) at the same parallelism the extension uses and adds both to e2e/baselines/perf.json (local); the project is copied to the temp folder first. LTR_E2E_PERF_PROFILE=<file>.cpuprofile records a CPU profile of the extension host during the full run, LTR_E2E_PERF_LOG=<file> keeps its whole log. node scripts/perf-project.js <dir> [--framework jest|vitest|pytest|angular] --install writes the same synthetic 2.5k-file project for each framework (pytest: Python 3.12 through uv when installed; Angular: the e2e Angular fixture's app project, TypeScript).
  • diag-screenshots-ai — the AI-assistant features (Fix with AI, Problems and its quick fix, the Connect page, an agent's answers). diag-demo-ai — the clip ai-fix plus stills: a terminal agent (a scripted MCP client: fixed steps, real answers from the relay) printed in a terminal tab reads a failure, fixes the source and verifies while the Explorer turns green.
  • diag-screenshots-console — console output in the Results panel at every level (log, info, warn, error) for a passing and a failing test and for the whole file.
  • diag-demo-failure — failure-on-line.png: a failed test on fixture:demo-jest with its message after the line and the hover open. It captures the whole window (a clipped capture closes the hover first); crop it with the sips command in the scenario's header.
  • Scenes the GIF zooms into (the hover, the Results panel) are recorded at full size (record(name, true)); SCENES in scripts/demo-gifs.js gives them a zoom ({ at, dur, z, cx, cy }: eased into z× around a point, then held). The README / site coverage image is <fw>-coverage-hover.png cropped to the editor.
  • scripts/demo-gifs.js turns the clips into resources/gifs/demo.gif (README hero: five captioned scenes, ~40 s, ~1 MB) and scene-*.gif (the website slider, uncaptioned). It needs an ffmpeg with drawtext, which is not a dependency of the repo — e.g. npm i ffmpeg-static in a temp folder.
LTR_E2E_CDP_PORT=9333 LTR_E2E_SHOTS_DIR=/tmp/shots node e2e/run.js diag-demo-jest diag-demo-vitest diag-demo-pytest
FFMPEG=/tmp/ff/node_modules/ffmpeg-static/ffmpeg node scripts/demo-gifs.js /tmp/shots

Copy the stills you need into resources/images/ (coverage-hover.png = jest-coverage-hover.png, results-panel.png = pytest-results.png; explorer-running.png is a 300×620 crop of the Explorer from jest-run mid-run). Keep the README to the hero GIF plus a couple of images.


Core patterns (Timeline Debugger additions)

Webview router pattern

Both ResultsView and ExplorerView implement an internal single-page router (router.js). The router listens for { type: 'route', view: '...' } messages and swaps view modules in and out of <div id="app">.

Each view module exports { mount(container, vscode, payload), unmount(), onMessage(msg) }. Adding a new view = one new JS file + one entry in the views map passed to Router.init() in the HTML shell.

PlaybackEngine pattern

PlaybackEngine is a plain JS class that lives in the webview (src/webview/timeline/PlaybackEngine.js). It owns all playback state (currentStepId, play/pause timer). Callers wire callbacks — the engine emits nothing itself. To use it:

const engine = new PlaybackEngine(store)  // store has .steps array
engine.play(step => { /* update UI, call vscode.postMessage step-changed */ })
engine.pause()
engine.jumpTo(stepId)

Shared component pattern

logPanel.js and errorPanel.js in src/webview/components/ are standalone JS modules loaded as <script> tags in both HTML shells. They expose window.LogPanel and window.ErrorPanel with { mount, update, unmount }. Views call these directly — no import/export, no bundler required.


Known limitations

Limitation Detail
--testNamePattern may over-match Rerunning a single test matches by name regex — overlapping names will run together
describe fallback If no LineMap entry exists for the line, ▶ Run on a describe block reruns the whole file
Debug config hardcoded path getDebugConfig in JestAdapter uses ${workspaceFolder}/node_modules/.bin/jest; non-standard layouts may need the liveTestRunner.jestCommand override
CRA config cache is in-memory Lost when the session ends; recomputed (~2–3s) on next Start Testing
Projects inside a project A folder with its own test config is one project even when its packages have their own configs; nested workspaces (a package that is itself a monorepo root) are not split further
Gutter icon animation animateTransform in the running SVG is rendered statically by VS Code — the spinner does not spin in the gutter
location not always present Some Jest setups (CRA) and Vitest 1–2 do not emit location in JSON; gutter icons won't appear for those files (Vitest ≥ 3 gets it via --includeTaskLocation)
Timeline transform: regex-based injection traceTransform.js injects trace calls using Babel AST. It handles assignments, function calls, and common statement patterns, but may miss complex patterns such as multi-line destructuring or chained optional calls inside expressions.
Timeline: no import tracing The transform only instruments the target test file. Imported modules are not traced; their execution does not appear as steps in the timeline.
Timeline: console.log in tests traceRuntime.js patches console.* to emit LOG events. If the test patches console before the runtime loads, log capture may be incomplete.

Roadmap

Planned work and ideas are tracked as GitHub Issues. What has shipped, by release, is in the CHANGELOG:

Next, in order (details and status in the GitHub Issues):

  1. More frameworks, each with results and coverage: Mocha, Playwright, node:test, Cypress
  2. Coverage: file detail page, function-level stale marking, sole-coverage warnings
  3. Mirroring results into VS Code's Testing view (optional, gives Copilot its native "Fix test failure" too); the Timeline debugger rewrite comes last

Measured and not planned: tracing only some test files on large projects, and a lighter discovery parser (reasons in Test runs: design).

Shipped:

  • 3.5.0 — AI assistants: Copilot, Cursor and terminal agents (Claude Code, Codex, Gemini CLI) read live results and run tests through LTR_ tools (VS Code language-model tools and a local stdio MCP relay, no network port); failing tests in the Problems list; Fix with AI
  • 3.4.1 — large projects much faster for every framework, a speed setting with a budget that adapts to free CPU and memory, coverage equal to the project's own coverage command and correct after any test change
  • 3.4.0 — Angular (ng test), failures on the failing line with a diff, Update snapshot, Copy for AI, no network / privacy policy, minimum VS Code 1.82
  • 3.3.0 — Python monorepos (uv workspaces, one .venv per service), JS + Python in one folder, a framework router for any number of frameworks, open test files first, coverage-off notes
  • 3.2.x — pytest support; coverage bars that stay out of the way while editing; files changed outside the editor rerun
  • 3.1.0 — monorepos and multi-root workspaces, mixed Jest + Vitest projects, the Vitest execution trace, any UI framework
  • 3.0.0 — Vitest support

Source: docs/development/developer-guide.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