Rstest Debugging
Diagnose the measured lifecycle stage before changing configuration. Keep behavior and the test manifest fixed, change one variable at a time, and remove experiments that do not produce a repeatable benefit.
Workflow
- Establish comparable single-file and full-scope baselines with
references/performance-measurement.md.
- Run
rstest --trace when supported and classify the cost as host build/startup, runtime load/setup/collect, test bodies/hooks, or CLI/report/teardown overhead.
- Use
DEBUG=rstest for resolved config and build output. For Rstest 0.11.7+ experimental per-test bundle coverage, follow references/performance-measurement.md. Use Rsdoctor only after evidence points to the compiler. Use verbose reporting or a profiler only after narrowing to runtime files/cases.
- If dependency loading or compilation is implicated, read
references/dependency-bundling.md. Compare the environment default, bundleDependencies: false, and bundleDependencies: true; neither bundling nor externalization is universally faster.
- If a fully mocked heavy module still reaches the build graph, read
references/mocked-module-build-graph.md before testing an exact external.
- If assets, console output, pools, isolation, or memory dominate, read
references/runtime-output-memory.md.
- Rerun the representative file and full scope. Keep a change only when behavior, discovery, snapshots, and coverage remain valid and the benefit survives repeated measurement. Remove traces, profiles, and
.rstest debug artifacts created by the diagnosis before handing off.
Guardrails
- Use the project's installed Rstest for final claims. Label local checkout or unreleased diagnostic results separately.
- Keep Node version, test files, coverage, cache state, environment, workers, and command shape fixed while comparing.
- Do not add worker durations that overlap or subtract runner/build/tests values without verifying their lifecycle boundaries.
- Do not treat aggregate process-tree RSS as physical memory; it can double-count shared pages.
- Do not disable isolation, reduce coverage, silence failures, or change production/test semantics for a benchmark win.
- Do not stack speculative aliases, externals, compiler hooks, pool settings, or caches. Preserve only the measured minimum.
Handoff from migration
When invoked from migrate-to-rstest, first confirm that the Jest/Vitest and Rstest manifests match. If the migration intentionally adds tests, report same-scope performance separately from final expanded-scope performance.
1---2name: rstest-debugging3description: Diagnose Rstest startup, build, runtime, logging, memory, or performance problems using traces and comparable measurements.4---5
6# Rstest Debugging
7
8Diagnose the measured lifecycle stage before changing configuration. Keep behavior and the test manifest fixed, change one variable at a time, and remove experiments that do not produce a repeatable benefit.
9
10## Workflow
11
121. Establish comparable single-file and full-scope baselines with `references/performance-measurement.md`.
132. Run `rstest --trace` when supported and classify the cost as host build/startup, runtime load/setup/collect, test bodies/hooks, or CLI/report/teardown overhead.
143. Use `DEBUG=rstest` for resolved config and build output. For Rstest 0.11.7+ experimental per-test bundle coverage, follow `references/performance-measurement.md`. Use Rsdoctor only after evidence points to the compiler. Use verbose reporting or a profiler only after narrowing to runtime files/cases.
154. If dependency loading or compilation is implicated, read `references/dependency-bundling.md`. Compare the environment default, `bundleDependencies: false`, and `bundleDependencies: true`; neither bundling nor externalization is universally faster.
165. If a fully mocked heavy module still reaches the build graph, read `references/mocked-module-build-graph.md` before testing an exact external.
176. If assets, console output, pools, isolation, or memory dominate, read `references/runtime-output-memory.md`.
187. Rerun the representative file and full scope. Keep a change only when behavior, discovery, snapshots, and coverage remain valid and the benefit survives repeated measurement. Remove traces, profiles, and `.rstest` debug artifacts created by the diagnosis before handing off.
19
20## Guardrails
21
22- Use the project's installed Rstest for final claims. Label local checkout or unreleased diagnostic results separately.
23- Keep Node version, test files, coverage, cache state, environment, workers, and command shape fixed while comparing.
24- Do not add worker durations that overlap or subtract runner/build/tests values without verifying their lifecycle boundaries.
25- Do not treat aggregate process-tree RSS as physical memory; it can double-count shared pages.
26- Do not disable isolation, reduce coverage, silence failures, or change production/test semantics for a benchmark win.
27- Do not stack speculative aliases, externals, compiler hooks, pool settings, or caches. Preserve only the measured minimum.
28
29## Handoff from migration
30
31When invoked from `migrate-to-rstest`, first confirm that the Jest/Vitest and Rstest manifests match. If the migration intentionally adds tests, report same-scope performance separately from final expanded-scope performance.
rstackjs