|
| 1 | +# Rstest setup instructions |
| 2 | + |
| 3 | +You are setting up Rstest in an existing project. Detect all project-specific choices from |
| 4 | +the repository context. Do not hard-code any assumption about package manager, framework, |
| 5 | +directory layout, or file naming. Only these are invariant: |
| 6 | + |
| 7 | +- Always install `@rstest/core` |
| 8 | +- Config file is always `rstest.config.ts` (uses `defineConfig` from `@rstest/core`) |
| 9 | +- Add framework plugins and test helpers only when detected |
| 10 | +- Add `@rstest/browser` only when browser mode is needed |
| 11 | + |
| 12 | +Follow each step in order. |
| 13 | + |
| 14 | +## Step 1: detect workspace scope |
| 15 | + |
| 16 | +Determine whether you are in: |
| 17 | + |
| 18 | +- A single-package repo |
| 19 | +- A monorepo root (look for `pnpm-workspace.yaml`, `workspaces` in `package.json`, `turbo.json`, `nx.json`) |
| 20 | +- A workspace package inside a monorepo |
| 21 | + |
| 22 | +Choose the **owning package** — the `package.json` closest to the source code being tested. |
| 23 | +Install deps, create config, and update scripts in that package. |
| 24 | + |
| 25 | +## Step 2: detect language |
| 26 | + |
| 27 | +- If `tsconfig.json` exists or `typescript` is in dependencies → TypeScript project, |
| 28 | + use `.ts` / `.tsx` for generated files. |
| 29 | +- Otherwise → JavaScript project, use `.js` / `.jsx`. |
| 30 | + |
| 31 | +Keep `rstest.config.ts` regardless (Rstest always resolves it). |
| 32 | + |
| 33 | +## Step 3: detect framework |
| 34 | + |
| 35 | +Inspect `package.json` dependencies: |
| 36 | + |
| 37 | +- `react` or `react-dom` → React project. |
| 38 | + Additional deps: `@rsbuild/plugin-react`. |
| 39 | + For component testing, also add `@testing-library/react` and `@testing-library/jest-dom`. |
| 40 | +- `vue` → Vue project. |
| 41 | + Additional deps: `@rsbuild/plugin-vue`. |
| 42 | + For component testing, also add `@vue/test-utils`. |
| 43 | +- Neither → plain Node project. No framework plugin needed. |
| 44 | + |
| 45 | +## Step 4: detect test environment |
| 46 | + |
| 47 | +Choose the `testEnvironment` based on these signals (in priority order): |
| 48 | + |
| 49 | +1. **Existing config**: if a prior `jest.config.*` or `vitest.config.*` specifies an |
| 50 | + environment, prefer that choice. |
| 51 | +2. **Existing deps**: if `jsdom` is already installed → use `'jsdom'`. |
| 52 | + If `happy-dom` is already installed → use `'happy-dom'`. |
| 53 | +3. **Browser mode signals**: if the project has Playwright, Cypress, or WebdriverIO deps, |
| 54 | + or existing browser/e2e test scripts → consider `@rstest/browser` (browser mode) |
| 55 | + instead of a simulated DOM. |
| 56 | +4. **Framework heuristic**: React or Vue project with component tests → use `'happy-dom'` |
| 57 | + (install `happy-dom` as devDependency). |
| 58 | +5. **Default**: plain Node project with no DOM usage → omit `testEnvironment` (defaults to `'node'`). |
| 59 | + |
| 60 | +Important: React/Vue does NOT automatically mean browser mode. Prefer `happy-dom`/`jsdom` |
| 61 | +for unit/component tests. Only use `@rstest/browser` when real browser behavior is needed. |
| 62 | + |
| 63 | +## Step 5: install dependencies |
| 64 | + |
| 65 | +Use [`ni`](https://github.com/antfu-collective/ni) to install — it auto-detects |
| 66 | +the project's package manager from lockfiles: |
| 67 | + |
| 68 | +```bash |
| 69 | +npx @antfu/ni -D @rstest/core |
| 70 | +``` |
| 71 | + |
| 72 | +Add additional packages to the same command based on detection results from Steps 3–4: |
| 73 | + |
| 74 | +- Framework plugin if detected (Step 3) |
| 75 | +- Test helpers if component testing is needed (Step 3) |
| 76 | +- `happy-dom` or `jsdom` if needed (Step 4) |
| 77 | +- `@rstest/browser` if browser mode is needed (Step 4) |
| 78 | + |
| 79 | +For example, a React project with component tests: |
| 80 | + |
| 81 | +```bash |
| 82 | +npx @antfu/ni -D @rstest/core @rsbuild/plugin-react @testing-library/react @testing-library/jest-dom happy-dom |
| 83 | +``` |
| 84 | + |
| 85 | +## Step 6: create `rstest.config.ts` |
| 86 | + |
| 87 | +Generate the minimal config. Only add options that are justified by detection results. |
| 88 | + |
| 89 | +### Plain node (no framework, no DOM) |
| 90 | + |
| 91 | +```ts |
| 92 | +import { defineConfig } from '@rstest/core'; |
| 93 | + |
| 94 | +export default defineConfig({}); |
| 95 | +``` |
| 96 | + |
| 97 | +### With framework plugin (e.g., React) |
| 98 | + |
| 99 | +```ts |
| 100 | +import { pluginReact } from '@rsbuild/plugin-react'; |
| 101 | +import { defineConfig } from '@rstest/core'; |
| 102 | + |
| 103 | +export default defineConfig({ |
| 104 | + plugins: [pluginReact()], |
| 105 | + testEnvironment: 'happy-dom', |
| 106 | +}); |
| 107 | +``` |
| 108 | + |
| 109 | +### With framework plugin (e.g., Vue) |
| 110 | + |
| 111 | +```ts |
| 112 | +import { pluginVue } from '@rsbuild/plugin-vue'; |
| 113 | +import { defineConfig } from '@rstest/core'; |
| 114 | + |
| 115 | +export default defineConfig({ |
| 116 | + plugins: [pluginVue()], |
| 117 | + testEnvironment: 'happy-dom', |
| 118 | +}); |
| 119 | +``` |
| 120 | + |
| 121 | +Adapt as needed — these are examples, not templates to copy verbatim. |
| 122 | + |
| 123 | +## Step 7: update `package.json` scripts |
| 124 | + |
| 125 | +Check the owning `package.json` scripts: |
| 126 | + |
| 127 | +- If a `test` script already exists, consider using a different name like `test:unit` |
| 128 | + or updating the existing script, depending on what it currently runs. |
| 129 | +- If no `test` script exists, add `"test": "rstest"`. |
| 130 | +- Preserve existing script naming conventions in the project. |
| 131 | + |
| 132 | +## Step 8: write tests |
| 133 | + |
| 134 | +### If tests already exist |
| 135 | + |
| 136 | +Follow their conventions: |
| 137 | + |
| 138 | +- Same file naming pattern (`*.test.*` vs `*.spec.*`) |
| 139 | +- Same placement (colocated vs `test/` vs `__tests__/`) |
| 140 | +- Same assertion style and helper libraries |
| 141 | + |
| 142 | +### If no tests exist |
| 143 | + |
| 144 | +1. Detect the project's source directory (look for `src/`, `app/`, `lib/`, or the |
| 145 | + `main`/`exports` entry in `package.json` — do not assume `src/`). |
| 146 | +2. Identify key exported modules (utility functions, core logic, components). |
| 147 | +3. Write meaningful tests for real modules, not placeholder tests. |
| 148 | +4. Place test files following the project's existing file organization patterns. |
| 149 | + If no convention exists, colocate tests next to source files. |
| 150 | +5. Use the detected language extension (`.test.ts`, `.test.tsx`, `.test.js`, etc.). |
| 151 | + |
| 152 | +## Step 9: validate |
| 153 | + |
| 154 | +Run the test script using the detected package manager and confirm Rstest executes |
| 155 | +successfully. If it fails, read the error output and fix the configuration. |
0 commit comments