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

When `--trace` is passed (or `performance.trace: true` is set in config),
each test file's lifecycle is recorded as Perfetto-compatible events and
written at run end to `<rootPath>/.rstest/trace-<timestamp>.json`.

The trace contains:
- per-phase `ph: 'X'` spans (prepare, envSetup, load, setupFiles, collect,
  tests, coverage, teardown)
- per-suite / per-case `ph: 'X'` spans via the runner's existing lifecycle
  hooks (zero intrusion into runner.ts)
- heap-usage counter samples (`ph: 'C'`) at each phase boundary so memory
  pressure shows up as a track in Perfetto UI

Each `PhaseTracker` (one per test file) gets a unique per-process `tid`,
so workers with `isolate: false` render multiple files as distinct thread
tracks instead of collapsing onto the first file's label. A tiny
localhost HTTP server on port 9001 (the only port allowed by Perfetto
UI's CSP) starts in TTY runs so the printed `ui.perfetto.dev` deep-link
loads the trace directly; in non-TTY (CI) runs the file is written
without spawning the server so `rstest run` exits cleanly.

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/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;

packages/core/src/core/runTests.ts

@@ -1,11 +1,17 @@
 import { constants as osConstants } from 'node:os';
 import { cleanCoverageReports, createCoverageProvider } from '../coverage';
 import { createPool } from '../pool';
-import type { EntryInfo, ProjectEntries, SourceMapInput } from '../types';
+import type {
+  Duration,
+  EntryInfo,
+  ProjectEntries,
+  SourceMapInput,
+} from '../types';
 import type { CoverageMap } from '../types/coverage';
 import {
   clearScreen,
   color,
+  createTraceController,
   getTestEntries,
   logger,
   resolveShardedEntries,
@@ -110,11 +116,7 @@ const notifyReportersOnTestRunEnd = async ({
 }: {
   context: Rstest;
   coverage?: CoverageMap;
-  duration: {
-    totalTime: number;
-    buildTime: number;
-    testTime: number;
-  };
+  duration: Duration;
   getSourcemap: (sourcePath: string) => Promise<SourceMapInput | null>;
   unhandledErrors?: Error[];
   filterRerunTestPaths?: string[];
@@ -434,6 +436,11 @@ export async function runTests(context: Rstest): Promise<void> {
 
   type Mode = 'all' | 'on-demand';
 
+  const traceController = createTraceController({
+    enabled: context.trace,
+    rootPath,
+  });
+
   const run = async ({
     fileFilters,
     mode = 'all',
@@ -460,6 +467,8 @@ export async function runTests(context: Rstest): Promise<void> {
       ? coverageProvider.createCoverageMap()
       : undefined;
 
+    const traceRun = traceController.beginRun();
+
     const returns = await Promise.all(
       projects.map(async (p) => {
         const {
@@ -548,6 +557,7 @@ export async function runTests(context: Rstest): Promise<void> {
           project: p,
           updateSnapshot: context.snapshotManager.options.updateSnapshot,
           onCoverageResult: (coverage) => mergedCoverageMap?.merge(coverage),
+          onTraceEvents: traceRun.onEvents,
         });
 
         return {
@@ -599,7 +609,7 @@ export async function runTests(context: Rstest): Promise<void> {
       };
 
       // When unifying reporter output, combine browser and node durations
-      const duration =
+      const duration: Duration =
         shouldUnifyReporter && browserResult
           ? {
               totalTime:
@@ -680,6 +690,8 @@ export async function runTests(context: Rstest): Promise<void> {
         await generateCoverage(context, mergedCoverageMap!, coverageProvider);
       }
 
+      await traceRun.finalize();
+
       if (isFailure) {
         const bail = context.normalizedConfig.bail;
 
@@ -711,6 +723,7 @@ export async function runTests(context: Rstest): Promise<void> {
         await runGlobalTeardown();
         await pool.close();
         await closeServer();
+        await traceController.close();
       } catch (error) {
         logger.log(color.red(`Error during cleanup: ${error}`));
       }
@@ -750,6 +763,7 @@ export async function runTests(context: Rstest): Promise<void> {
       await runGlobalTeardown();
       await pool.close();
       await closeServer();
+      await traceController.close();
     });
 
     let buildStart: number | undefined;
@@ -771,6 +785,7 @@ export async function runTests(context: Rstest): Promise<void> {
           closeServer: async () => {
             await pool.close();
             await closeServer();
+            await traceController.close();
           },
           runAll: async () => {
             clearScreen();
@@ -898,6 +913,7 @@ export async function runTests(context: Rstest): Promise<void> {
         await runGlobalTeardown();
         await pool.close();
         await closeServer();
+        await traceController.close();
       } catch (error) {
         logger.log(color.red(`Error during cleanup: ${error}`));
       }
@@ -952,5 +968,7 @@ export async function runTests(context: Rstest): Promise<void> {
       process.off('SIGTERM', handleSignal);
       process.off('SIGTSTP', handleSignal);
     }
+
+    await traceController.waitForExit();
   }
 }

packages/core/src/pool/index.ts

@@ -25,6 +25,7 @@ import {
   isDeno,
   needFlagExperimentalDetectModule,
 } from '../utils';
+import type { TraceEvent } from '../utils/trace';
 import { isMemorySufficient } from '../utils/memory';
 import { Pool } from './pool';
 
@@ -192,6 +193,7 @@ const buildTask = async ({
         rootPath: context.rootPath,
         projectRoot: project.rootPath,
         runtimeConfig,
+        trace: context.trace,
       },
       type,
       setupEntries,
@@ -267,6 +269,8 @@ export const createPool = async ({
     project: ProjectContext;
     /** When provided, coverage data is passed to this callback immediately for caller-owned merging. */
     onCoverageResult?: (coverage: CoverageMapData) => void;
+    /** Perfetto trace events forwarded for caller-owned dumping. */
+    onTraceEvents?: (events: TraceEvent[]) => void;
   }) => Promise<{
     results: TestFileResult[];
     testResults: TestResult[];
@@ -449,6 +453,7 @@ export const createPool = async ({
       project,
       updateSnapshot,
       onCoverageResult,
+      onTraceEvents,
     }) => {
       const projectName = project.name;
       const runtimeConfig = getRuntimeConfig(project);
@@ -488,6 +493,10 @@ export const createPool = async ({
             onCoverageResult?.(result.coverage);
             delete result.coverage;
           }
+          if (result.traceEvents) {
+            onTraceEvents?.(result.traceEvents);
+            delete result.traceEvents;
+          }
           context.stateManager.onTestFileResult(result);
           reporters.map((reporter) => reporter.onTestFileResult?.(result));
           return result;

packages/core/src/runtime/util.ts

@@ -28,6 +28,14 @@ export const getRealTimers = (): typeof REAL_TIMERS => {
   return REAL_TIMERS;
 };
 
+/**
+ * Stable reference to `Date.now`, captured before `@sinonjs/fake-timers`
+ * can hijack the global. Phase boundaries straddling `tests` rely on this.
+ */
+const realNow = Date.now.bind(Date);
+
+export const getRealNow = (): number => realNow();
+
 export const formatTestError = async (
   err: any,
   test?: Test,