migrate-to-rstest
Migrate to Rstest
Goal
Migrate Jest- or Vitest-based tests and configuration to Rstest with minimal behavior changes.
Migration principles (must follow)
- Smallest-change-first: prefer the smallest viable change that restores test pass.
- Config before code: prefer fixing in config/tooling/mocks before touching test logic.
- Do not change user source behavior: avoid modifying production/business source files unless user explicitly requests it.
- Avoid bulk test rewrites: do not refactor entire test suites when a local compatibility patch can solve it.
- Preserve test intent: keep assertions and scenario coverage unchanged unless clearly broken by framework differences.
- Two-phase legacy-runner lifecycle (per migrated scope): (a) While the scope being migrated is not green on Rstest, keep every Jest/Vitest dep + config/setup/workspace file untouched — they are your rollback path. (b) Once that scope is green, delete its scope-local legacy config/setup files in the same commit. Drop the shared legacy devDeps (
jest,vitest, adapters, environments) only when no other scope still relies on them — in a partial / mixed-mode monorepo migration that means the final scope, not the first. Leaving files behind "for reference" creates two source-of-truth configs. Framework-specific file enumeration: see the deltas reference. - Literal API substitution, no shims: rewrite every
vi./jest./vitest.call site — no global aliasing, no local rebinding, no aliased imports. Full forbidden-form list and reasoning inreferences/global-api-migration.md. - Replace on call sites, not strings: match only identifiers preceding
(; after every batch edit, grepdescribe\(|it\(|test\(to confirm no test name string was mutated. Regex template and rationale inreferences/global-api-migration.md. - Coverage thresholds are not negotiable: never lower
coverage.thresholds(lines/functions/branches/statements) to make a migrated suite pass. If thresholds fail under Rstest, investigatecoverage.include/exclude/ provider wiring before touching the numbers.
Workflow
More from rstackjs/agent-skills
rsbuild-best-practices
Rsbuild best practices for config, CLI workflow, type checking, bundle optimization, assets, and debugging. Use when writing, reviewing, or troubleshooting Rsbuild projects.
562rslib-best-practices
Rslib best practices for config, CLI workflow, output, declaration files, dependency handling, build optimization and toolchain integration. Use when writing, reviewing, or troubleshooting Rslib projects.
406rspack-v2-upgrade
Use when upgrading a Rspack 1.x project to v2, including dependency and configuration updates.
237rstest-best-practices
Rstest best practices for config, CLI workflow, test writing, mocking, snapshot testing, DOM testing, coverage, multi-project setup, CI integration, performance and debugging. Use when writing, reviewing, or troubleshooting Rstest test projects.
229rspack-best-practices
Rspack best practices for config, CLI workflow, type checking, CSS, bundle optimization, assets and profiling. Use when writing, reviewing, or troubleshooting Rspack projects.
223rsbuild-v2-upgrade
Use when upgrading a Rsbuild 1.x project to v2, including dependency and configuration updates.
207