migrate-to-rstest — Claude Code skill for moving tests to Rstest
Migrates Jest, Vitest, or Playwright Test suites to Rstest while keeping test discovery, assertions, mocks, snapshots, and coverage intact. For moving a runner without rewriting scenarios.
npx skills add rstackjs/agent-skills --skill migrate-to-rstest -a claude-codeWhat migrate-to-rstest does
The skill follows a strict order: detect the runner and smallest runnable scope first, check installed dependencies, then edit scripts, config, and setup before touching test bodies. A dependency gate stops it from picking an Rstest API that does not match the installed version.
It ships reference files per source runner: Jest, Vitest, Playwright Test, global APIs, and the [MODULE_TYPELESS_PACKAGE_JSON] config warning. The Playwright path only loads when the detected runner is actually Playwright Test, not for any browser-related request.
Some Rstest behavior is easy to get wrong. rstest run is single-run; watch mode is a separate rstest --watch. globals defaults to false, so global APIs need globals: true plus @rstest/core/globals types. rs.mock() is runtime replacement and does not prune the real module graph from the build. The skill keeps the previous runner in place until Rstest is green.
After migration it compares pre- and post-migration test manifests and classifies every added, removed, skipped, or excluded test. A green run is not proof of equivalence. Jest snapshots get a separate cleanup and unchecked validation pass.
What it helps with
- move tests from Jest to Rstest without losing discovery
- keep mocks, snapshots, and coverage working after the switch
- spot config fields Rstest does not support
- verify test counts match before and after migration
- track down a performance regression after the move
Example prompts for the agent
- migrate this project's tests from Vitest to Rstest
- migrate only this test file from Jest, leave the rest alone
- compare the post-migration test manifest with the baseline and show differences
How to install migrate-to-rstest
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill migrate-to-rstest -a claude-code2Manually: put the files in place
~/.claude/skills/migrate-to-rstest/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/migrate-to-rstest/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill migrate-to-rstest -a codex2Manually: put the files in place
.agents/skills/migrate-to-rstest/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill migrate-to-rstest -a cursor2Manually: put the files in place
.cursor/skills/migrate-to-rstest/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rstackjs/agent-skills migrate-to-rstest2Manually: put the files in place
.github/skills/migrate-to-rstest/SKILL.md1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill migrate-to-rstest -a gemini-cli2Platform CLI
gemini skills install https://github.com/rstackjs/agent-skills --path skills/migrate-to-rstestManually: put the files in place
.devin/skills/migrate-to-rstest/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill migrate-to-rstest -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about migrate-to-rstest
How do I install migrate-to-rstest in Claude Code?
Run npx skills add rstackjs/agent-skills --skill migrate-to-rstest -a claude-code. The skill lands at ~/.claude/skills/migrate-to-rstest/SKILL.md.
What does migrate-to-rstest do?
It moves the smallest runnable scope of Jest, Vitest, or Playwright Test tests to Rstest while preserving discovery, assertions, mocks, snapshots, and coverage. It then compares test manifests to catch drift.
Why does rs.mock() still load the real module?
Rstest builds before tests run, and rs.mock() only replaces modules at runtime. The real module remains in the build graph unless the config externalizes or prunes it explicitly.
Source text
SKILL.md · MIT
--- name: migrate-to-rstest description: Migrate Jest, Vitest, or Playwright Test to Rstest while preserving test discovery, assertions, mocks, snapshots, and coverage. --- <!-- cspell:words TYPELESS --> # Migrate to Rstest ## Goal Migrate the smallest runnable Jest, Vitest, or Playwright Test scope with minimal behavior change. Use documentation and types that match the installed Rstest version; use latest online docs only after the capability gate confirms they apply. ## Workflow 1. Detect the runner, environment, Rstack integration, and smallest runnable scope with `references/detect-test-framework.md`. 2. Run `references/dependency-install-gate.md` before choosing Rstest, coverage, adapter, or plugin APIs. 3. Before editing, record the exact command, Node and runner versions, environment, files/tests/skips/snapshots, and failures. Capture the pre-migration test manifest and follow `references/discovery-parity.md` throughout the migration. 4. For Jest read `references/jest-migration-deltas.md`; for Vitest read `references/vitest-migration-deltas.md`; for global APIs also read `references/global-api-migration.md`; for a detected Playwright Test runner read `references/playwright-migration-deltas.md`. Do not load the Playwright path for a browser-only request whose runner is not Playwright Test. Migrate scripts, config, and setup before editing test bodies; prefer adapter or Rsbuild/Rspack fixes over broad test rewrites. 5. If config loading emits `[MODULE_TYPELESS_PACKAGE_JSON]`, use `references/config-module-type.md`. Do not suppress the warning or change the whole package module type without an audit. 6. Get the migrated scope semantically green. Fix failures in this order: dependency skew, config/resolver, discovery, setup/environment/coverage, mocks/timers/snapshots, then test bodies. 7. Compare the post-migration manifest and execution counts with the baseline. Classify every added, removed, skipped, or excluded test explicitly; do not call a run equivalent merely because it is green. For Jest snapshot migrations, also complete the snapshot cleanup and `unchecked` validation in `references/jest-migration-deltas.md`. 8. Remove temporary aliases, diagnostic hooks, and copied legacy workarounds that are no longer required. Keep only configuration proven necessary by behavior or measurement. 9. If wall time, build, test runtime, logs, or memory materially regress, load and follow the `rstest-debugging` skill when available. Otherwise use the migration fallback in `references/performance-diagnosis.md`, then read `references/dependency-bundling-performance.md` and/or `references/mocked-module-build-graph.md` according to the measured bottleneck. Change one variable at a time. 10. After correctness and performance validation, remove only legacy files and dependencies owned by the migrated scope. Summarize behavior parity, discovery differences, unsupported fields, retained compatibility config, performance tradeoffs, and TODOs. ## Guardrails - Keep the smallest viable scope. Do not broaden a monorepo migration because scopes share a lockfile. - Do not change production behavior, assertions, test names, scenarios, coverage thresholds, or ignore directives to make migration pass. - Do not introduce `jest`/`vi` shims or aliases; rewrite call sites with `references/global-api-migration.md`. - Do not silently drop unknown config fields or historical excludes. Verify, replace, or report each one. - Do not compare performance across different test manifests, Node versions, coverage modes, cache states, or worker settings. - Keep the previous runner until Rstest is green. Use a local Rstest checkout only for labeled diagnostics, then validate the final result with the project's installed dependency. - Escalate before many test edits or any production-source change: report why smaller config/setup fixes failed, options, risks, and the recommended path. ## High-risk Rstest deltas - `rstest` / `rstest run` is single-run; watch mode is `rstest --watch` or `rstest watch`. - `globals` defaults to `false`; preserving global APIs requires `globals: true` and `@rstest/core/globals` types. - Rstest builds before tests run. `rs.mock()` is runtime replacement and does not by itself prune the real module graph. - Dependency bundling trades compiler work for runtime Node loading. Neither “bundle all” nor “externalize all” is universally faster; measure a representative file and the full scope. - An externalized runtime mock must match the exact request and module format. A config-wide external is unsafe when any test needs the real module.
© rstackjs · MIT · rstackjs/agent-skills
