feat(core): add --trace flag to dump Perfetto-compatible profile

Add a `--trace` CLI flag that records per-phase, per-suite, and per-case
timing spans plus heap counters for each test file and writes them to a
Perfetto-compatible JSON file. On interactive TTYs the dump is served
over a localhost HTTP server so users can click a one-shot link that
auto-loads the trace in https://ui.perfetto.dev.

Implementation:

* `runtime/worker/phaseTracker.ts` records phase spans, suite/case
  slices, and `process.memoryUsage()` counter samples per file. Each
  tracker gets its own `tid` so files share one `pid` cleanly under
  `isolate: false`.
* `utils/trace.ts` exposes `createTraceController`, which buffers events
  per run (`beginRun`), writes the trace JSON on `finalize`, manages the
  optional Perfetto helper HTTP server, and provides `shutdown` /
  `waitForExit` / `close` lifecycle hooks.
* `core/runTests.ts` wires the controller across node and browser
  modes. Pre-allocates the per-run buffer so events emitted before the
  first `run()` call — or in mixed runs where `run()` is never invoked
  because all node tests are filtered out — are not dropped through the
  `activeTraceRun?.` optional chain. Watch cleanup paths
  (`SIGINT`/restart/CLI close) flush the active buffer before closing
  the controller so events accumulated between reruns make it to disk.
* Browser mode: `@rstest/browser` host instantiates one `PhaseTracker`
  per test file and forwards events through
  `BrowserTestRunOptions.onTraceEvents`. Each file is assigned a
  synthetic per-file `pid` (base `1_000_000_000`) so Perfetto labels
  every track with the file path instead of collapsing every file under
  the shared host process.

User impact: opt-in profiling via `rstest run --trace`. Without the
flag, behavior is unchanged; `beginRun()` returns a no-op handle so the
hot path is free of branching overhead.

Author: fi3ework

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 *.log*
 *.cpuprofile
+*.dump
 node_modules/
 
 .cache/
@@ -48,6 +49,7 @@ packages/vscode/*.vsix
 packages/vscode/icon.png
 
 .rstest-temp/
+.rstest/
 lefthook-local.yml
 
 # Generated memory benchmark fixture

packages/browser/src/hostController.ts

@@ -18,6 +18,7 @@ import {
   type ListCommandResult,
   loadCoverageProvider,
   logger,
+  PhaseTracker,
   type ProjectContext,
   type Reporter,
   type Rstest,
@@ -95,6 +96,18 @@ type RsbuildInstance = rsbuild.RsbuildInstance;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const OPTIONS_PLACEHOLDER = '__RSTEST_OPTIONS_PLACEHOLDER__';
 
+/**
+ * Monotonic counter for synthetic per-file Perfetto `pid` values in `--trace`
+ * mode. Browser host runs every test file inside the same Node process, so
+ * without an override every file would emit events under the same `pid` and
+ * share a single track labelled `worker <hostPid>`. Giving each file its own
+ * synthetic `pid` makes the track title surface the file path instead,
+ * matching node mode's default `isolate: true` behavior. The 1_000_000_000
+ * base keeps each synthetic `pid` well clear of real OS `pid` values in
+ * mixed-mode traces.
+ */
+let nextBrowserFilePid = 1_000_000_000;
+
 /**
  * Serialize JSON for inline <script> injection.
  * Escapes '<' to prevent accidental </script> break-out.
@@ -1693,10 +1706,22 @@ export const runBrowserController = async (
   context: Rstest,
   options?: BrowserTestRunOptions,
 ): Promise<BrowserTestRunResult | void> => {
-  const { skipOnTestRunEnd = false, allowEmptyWatchRun = false } =
-    options ?? {};
+  const {
+    skipOnTestRunEnd = false,
+    allowEmptyWatchRun = false,
+    onTraceEvents,
+  } = options ?? {};
   const buildStart = Date.now();
   const isWatchMode = context.command === 'watch';
+
+  // Per-file PhaseTrackers, populated only when `--trace` is on (caller
+  // passes `onTraceEvents`). The browser host shares one Node process across
+  // every test file, so each tracker is assigned a synthetic per-file pid
+  // (`nextBrowserFilePid`) that lets Perfetto render each file as its own
+  // process track with the file path as the title.
+  const phaseTrackers = onTraceEvents
+    ? new Map<string, PhaseTracker>()
+    : undefined;
   const browserProjects = getBrowserProjects(context);
   const useHeadlessDirect = browserProjects.every(
     (project) => project.normalizedConfig.browser.headless,
@@ -2180,6 +2205,17 @@ export const runBrowserController = async (
   const handleTestFileStart = async (
     payload: TestFileStartPayload,
   ): Promise<void> => {
+    if (phaseTrackers) {
+      const tracker = new PhaseTracker({
+        trace: {
+          testPath: payload.testPath,
+          project: payload.projectName,
+        },
+        pid: nextBrowserFilePid++,
+      });
+      tracker.transition('prepare');
+      phaseTrackers.set(payload.testPath, tracker);
+    }
     await Promise.all(
       context.reporters.map((reporter) =>
         (reporter as Reporter).onTestFileStart?.({
@@ -2194,6 +2230,7 @@ export const runBrowserController = async (
   const handleTestFileReady = async (
     payload: TestFileReadyPayload,
   ): Promise<void> => {
+    phaseTrackers?.get(payload.testPath)?.transition('tests');
     await Promise.all(
       context.reporters.map((reporter) =>
         (reporter as Reporter).onTestFileReady?.(payload),
@@ -2204,6 +2241,7 @@ export const runBrowserController = async (
   const handleTestSuiteStart = async (
     payload: TestSuiteStartPayload,
   ): Promise<void> => {
+    phaseTrackers?.get(payload.testPath)?.recordSuiteStart(payload);
     await Promise.all(
       context.reporters.map((reporter) =>
         (reporter as Reporter).onTestSuiteStart?.(payload),
@@ -2214,6 +2252,7 @@ export const runBrowserController = async (
   const handleTestSuiteResult = async (
     payload: TestSuiteResultPayload,
   ): Promise<void> => {
+    phaseTrackers?.get(payload.testPath)?.recordSuiteResult(payload);
     await Promise.all(
       context.reporters.map((reporter) =>
         (reporter as Reporter).onTestSuiteResult?.(payload),
@@ -2234,6 +2273,7 @@ export const runBrowserController = async (
   const handleTestCaseStart = async (
     payload: TestCaseStartPayload,
   ): Promise<void> => {
+    phaseTrackers?.get(payload.testPath)?.recordCaseStart(payload);
     await Promise.all(
       context.reporters.map((reporter) =>
         (reporter as Reporter).onTestCaseStart?.(payload),
@@ -2243,6 +2283,7 @@ export const runBrowserController = async (
 
   const handleTestCaseResult = async (payload: TestResult): Promise<void> => {
     caseResults.push(payload);
+    phaseTrackers?.get(payload.testPath)?.recordCaseResult(payload);
     await Promise.all(
       context.reporters.map((reporter) =>
         (reporter as Reporter).onTestCaseResult?.(payload),
@@ -2269,6 +2310,16 @@ export const runBrowserController = async (
       context.snapshotManager.add(payload.snapshotResult);
     }
 
+    if (phaseTrackers) {
+      const tracker = phaseTrackers.get(payload.testPath);
+      if (tracker) {
+        tracker.end();
+        const events = tracker.getTraceEvents();
+        if (events) onTraceEvents?.(events);
+        phaseTrackers.delete(payload.testPath);
+      }
+    }
+
     if (context.normalizedConfig.silent === 'passed-only') {
       await flushBufferedLogsForTask({
         taskId: payload.testId,

packages/core/src/browser.ts

@@ -17,6 +17,10 @@ export { createRstestRuntime } from './runtime/api';
 // These are the test APIs that run in the browser (describe, it, expect, etc.)
 export * from './runtime/api/public';
 export { setRealTimers } from './runtime/util';
+// Trace primitives — the browser host instantiates PhaseTracker per test file
+// and forwards its events via `BrowserTestRunOptions.onTraceEvents`.
+export { PhaseTracker } from './runtime/worker/phaseTracker';
+export type { TraceEvent } from './utils/trace';
 // Types
 export type {
   BrowserTestRunOptions,

packages/core/src/cli/commands.ts

@@ -67,6 +67,7 @@ const runtimeOptionDefinitions: OptionDefinition[] = [
   ],
   ['--disableConsoleIntercept', 'Disable console intercept'],
   ['--logHeapUsage', 'Log heap usage after each test'],
+  ['--trace', 'Dump a Perfetto-compatible performance trace JSON file'],
   [
     '--slowTestThreshold <value>',
     'The number of milliseconds after which a test or suite is considered slow',
@@ -321,7 +322,7 @@ export const runRest = async ({
     });
 
     rstest = createRstest(
-      { config, configFilePath, projects },
+      { config, configFilePath, projects, trace: options.trace },
       command,
       effectiveFilters,
       fileFilterMode,

packages/core/src/cli/init.ts

@@ -67,6 +67,7 @@ export type CommonOptions = {
   silent?: boolean | 'passed-only';
   printConsoleTrace?: boolean;
   logHeapUsage?: boolean;
+  trace?: boolean;
   disableConsoleIntercept?: boolean;
   update?: boolean;
   testNamePattern?: RegExp | string;

packages/core/src/core/index.ts

@@ -13,10 +13,13 @@ export function createRstest(
     config,
     projects,
     configFilePath,
+    trace,
   }: {
     config: RstestConfig;
     configFilePath?: string;
     projects: Project[];
+    /** CLI-only `--trace` switch; not exposed via user config. */
+    trace?: boolean;
   },
   command: RstestCommand,
   fileFilters: string[],
@@ -30,6 +33,7 @@ export function createRstest(
       fileFilterMode,
       configFilePath,
       projects,
+      trace,
     },
     config,
   );

packages/core/src/core/rstest.ts

@@ -49,6 +49,7 @@ type Options = {
   fileFilterMode?: FileFilterMode;
   configFilePath?: string;
   projects: Project[];
+  trace?: boolean;
 };
 
 export class Rstest implements RstestContext {
@@ -61,6 +62,7 @@ export class Rstest implements RstestContext {
   public configFilePath?: string;
   public reporters: Reporter[];
   public snapshotManager: SnapshotManager;
+  public trace: boolean;
   public version: string;
   public rootPath: string;
   public originalConfig: RstestConfig;
@@ -96,11 +98,13 @@ export class Rstest implements RstestContext {
       fileFilterMode,
       configFilePath,
       projects,
+      trace = false,
     }: Options,
     userConfig: RstestConfig,
   ) {
     this.cwd = cwd;
     this.command = command;
+    this.trace = trace;
     this.fileFilters = fileFilters;
     this.fileFilterMode = fileFilterMode;
     this.configFilePath = configFilePath;