rstest-best-practices

Rstest Best Practices

Apply these rules when setting up, writing, or reviewing Rstest projects.

Workflow

• Inspect the existing package manager, dependency policy, module mode, build configuration, test layout, and framework conventions before editing.
• Add @rstest/core, a package-local test script, and a config file whose extension matches the package's module mode.
• Reuse existing build configuration only when doing so lowers maintenance cost and remains compatible. An adapter is optional; use an independent Rstest config when adapter integration is incompatible or disproportionately costly, and explicitly reproduce required aliases, plugins, defines, environments, and externals.
• Configure test discovery, environment, and setup files intentionally. Do not enable passWithNoTests unless an empty test set is an expected and documented state.
• Verify test discovery with rstest list, then run focused tests, the full suite, and the project's existing build or type-check command.

Configuration and environments

• Use defineConfig from @rstest/core and a config file extension compatible with the package's module mode.
• Prefer explicit imports from @rstest/core over globals: true.
• Use setupFiles for shared matchers and cleanup; use plugins, resolve, or source for ordinary build integration and low-level tools only when necessary.
• Set include explicitly when the package's test layout is non-standard; do not assume the default discovery pattern.
• Use node for server/SSR tests, happy-dom or jsdom for simulated DOM tests, and Browser Mode for real-browser behavior; install the selected environment package explicitly.
• For React or Vue component tests, register the matching build plugin, use the corresponding Testing Library, and centralize matcher extension and cleanup in a setup file.
• Use multiple test projects only when environments or configurations genuinely differ; keep global options such as reporters, coverage, pool, isolation, and bail at the root.