|
| 1 | +# Rstest setup — agent execution prompt |
| 2 | + |
| 3 | +Follow these steps **in order** to add Rstest to the current project. |
| 4 | +Read the repository first. Make the smallest correct change. |
| 5 | + |
| 6 | +Fetch a linked doc page **only after** choosing that branch. Do **not** fetch docs for branches you did not select. |
| 7 | + |
| 8 | +## Guardrails |
| 9 | + |
| 10 | +- Always install `@rstest/core`. Config file is always `rstest.config.ts` (even in JS projects). |
| 11 | +- Only add framework plugins, DOM environments, or browser support when the code under test actually needs the transform — not just because `react` or `vue` appears in `dependencies`. |
| 12 | +- Do **not** replace existing Jest/Vitest `test` scripts unless migration is clearly intended — add `"test:unit": "rstest"` or similar instead. |
| 13 | +- If the package already has Jest/Vitest tests and migration is **not** intended, use `include` (https://rstest.rs/config/test/include.md) to target only Rstest's own tests so it does not discover tests written for another runner. |
| 14 | +- If migration **is** intended, follow the migration guide instead of this prompt: Jest → https://rstest.rs/guide/migration/jest.md / Vitest → https://rstest.rs/guide/migration/vitest.md |
| 15 | +- Do **not** reuse Jest/Vitest setup files blindly — only add a setup file (https://rstest.rs/config/test/setup-files.md) if the selected Rstest docs require it and the contents are compatible. |
| 16 | +- If `@rstest/core` or `rstest.config.ts` already exists, extend the existing setup minimally instead of recreating it. |
| 17 | +- Do **not** generate placeholder tests (e.g., `test('placeholder', () => {})`). A real verification test is fine when no tests exist — see Step 8. |
| 18 | +- When signals conflict, the project's existing test/build setup takes precedence. |
| 19 | + |
| 20 | +## Step 0 — Repo-wide inventory (no changes yet) |
| 21 | + |
| 22 | +Before editing anything, determine: |
| 23 | + |
| 24 | +- Package manager (from lockfile, or `packageManager` field in root `package.json`) |
| 25 | +- Whether this is a monorepo (`pnpm-workspace.yaml`, `workspaces` in `package.json`, `turbo.json`, `nx.json`) |
| 26 | +- Whether Rstest is already present anywhere (`@rstest/core`, `rstest.config.ts`, scripts) |
| 27 | +- Whether an existing test runner (Jest/Vitest) is in use — if migration is intended, stop here and follow the migration guide (see Guardrails) |
| 28 | + |
| 29 | +## Step 1 — find the owning package |
| 30 | + |
| 31 | +Choose in this order: |
| 32 | + |
| 33 | +1. Package containing the source files being tested |
| 34 | +2. Package containing existing tests for that source |
| 35 | +3. Package containing the relevant build config |
| 36 | +4. If single-package repo, the root |
| 37 | + |
| 38 | +Note: deps, config, and scripts may live in different places. Determine separately: |
| 39 | + |
| 40 | +- **Config and test files** → always in the owning package. |
| 41 | +- **devDependencies and scripts** → in the owning package, unless the repo centralizes them at the workspace root — follow that convention. |
| 42 | +- **Validate from** → wherever the test script lives. |
| 43 | + |
| 44 | +## Step 2 — Package-scoped inventory |
| 45 | + |
| 46 | +Now inspect the owning package: |
| 47 | + |
| 48 | +- Source/test file extensions (`.ts`/`.tsx`/`.mts` vs `.js`/`.jsx`/`.mjs`) |
| 49 | +- Build tool in scope (`rsbuild.config.*`, `rslib.config.*`, or neither) |
| 50 | +- Existing test file naming and location |
| 51 | +- Whether tests need Node only, simulated DOM, or real browser APIs |
| 52 | + |
| 53 | +## Step 3 — detect language |
| 54 | + |
| 55 | +Determine from the owning package's **actual source/test file extensions** first. Use `tsconfig.json` or `typescript` dep only as a tiebreaker. |
| 56 | + |
| 57 | +- TypeScript → `.ts` / `.tsx` test files. |
| 58 | +- JavaScript → `.js` / `.jsx` test files. |
| 59 | + |
| 60 | +## Step 4 — detect build tooling → pick adapter |
| 61 | + |
| 62 | +An adapter auto-inherits plugins, aliases, and build config. If using an adapter, follow that guide first — only fetch a framework guide if the adapter guide does not already cover the required setup. |
| 63 | + |
| 64 | +- **Rsbuild project** (has `rsbuild.config.*` or `@rsbuild/core` dep) → follow https://rstest.rs/guide/integration/rsbuild.md |
| 65 | +- **Rslib project** (has `rslib.config.*` or `@rslib/core` dep) → follow https://rstest.rs/guide/integration/rslib.md |
| 66 | +- **Neither** → no adapter; configure Rstest standalone (continue below). |
| 67 | + |
| 68 | +When using an adapter you may still need to set `testEnvironment` or `browser` — the adapter does not decide those. |
| 69 | + |
| 70 | +## Step 5 — choose test environment |
| 71 | + |
| 72 | +Decide based on what the tests actually need, not solely from framework deps in `package.json`. See https://rstest.rs/config/test/test-environment.md for all options. |
| 73 | + |
| 74 | +### A. No DOM APIs needed → node (default) |
| 75 | + |
| 76 | +Omit `testEnvironment`. No extra deps. If not using an adapter and no other options are needed: |
| 77 | + |
| 78 | +```ts |
| 79 | +import { defineConfig } from '@rstest/core'; |
| 80 | +export default defineConfig({}); |
| 81 | +``` |
| 82 | + |
| 83 | +### B. DOM APIs needed, simulated DOM is sufficient → `happy-dom` / `jsdom` |
| 84 | + |
| 85 | +Use for tests that render components or rely on DOM APIs. |
| 86 | + |
| 87 | +- If the project already depends on `jsdom` or `happy-dom`, follow that choice. |
| 88 | +- Otherwise default to `happy-dom` (lighter). |
| 89 | +- **React** → follow https://rstest.rs/guide/framework/react.md |
| 90 | +- **Vue** → follow https://rstest.rs/guide/framework/vue.md |
| 91 | + |
| 92 | +### C. Real browser behavior needed → browser mode (experimental) |
| 93 | + |
| 94 | +Choose **only** when tests explicitly require Canvas, WebGL, CSS computed styles, Web Workers, or cross-browser testing. This is opt-in, not a default escalation. Vue Browser Mode is **not yet supported**. See https://rstest.rs/config/test/browser.md for all options. |
| 95 | + |
| 96 | +→ Follow https://rstest.rs/guide/browser-testing/getting-started.md |
| 97 | +→ For React component testing in browser, also follow https://rstest.rs/guide/browser-testing/framework-guides.md |
| 98 | + |
| 99 | +## Step 6 — install dependencies |
| 100 | + |
| 101 | +Use the repo's existing package manager (`pnpm add -D`, `npm i -D`, `yarn add -D`, `bun add -d`) based on the lockfile. Fall back to the `packageManager` field in root `package.json` if no lockfile exists. Install only packages justified in previous steps. |
| 102 | + |
| 103 | +## Step 7 — create config |
| 104 | + |
| 105 | +Keep it minimal — include **only** options justified by detection. |
| 106 | +→ See https://rstest.rs/guide/basic/configure-rstest.md only if the selected guide above does not fully specify the config. |
| 107 | + |
| 108 | +Config examples are in the guide pages linked in Steps 4–5. Do not copy examples blindly. |
| 109 | + |
| 110 | +## Step 8 — update scripts |
| 111 | + |
| 112 | +If migration is intended, you should already be following the migration guide — skip this step. |
| 113 | + |
| 114 | +- Do not overwrite any existing test-related script. Add a new non-conflicting name. |
| 115 | +- **No test script** → add `"test": "rstest"`. |
| 116 | +- **`test` exists (Jest/Vitest)** → add `"test:unit": "rstest"` or similar. |
| 117 | +- **Browser Mode** → consider a dedicated `"test:browser"` script. |
| 118 | +- Preserve the repo's naming conventions. |
| 119 | + |
| 120 | +## Step 9 — verification test (only if needed) |
| 121 | + |
| 122 | +Only if no tests exist and verification is needed: |
| 123 | + |
| 124 | +- Add **one** small test for a real exported function or module. Prefer a function/module over a UI component to avoid introducing extra test utilities. |
| 125 | +- Match existing naming (`*.test.*` vs `*.spec.*`), placement, and language. |
| 126 | +- If no convention, colocate next to the source file. |
| 127 | +- If there is no small, deterministic real export to test, skip this step. |
| 128 | + |
| 129 | +## Step 10 — validate |
| 130 | + |
| 131 | +Run the test command from wherever the test script lives. If it fails, read the error and fix — do not leave a broken setup. If no tests exist and you skipped Step 9, confirm the setup is valid (config loads, `rstest --passWithNoTests` or equivalent succeeds). |
0 commit comments