# Rstest

> Rstest is a JavaScript testing framework powered by Rspack

## 指南

- [介绍](/zh/guide/start/index.md): Rstest 是一个基于 Rspack 的 JavaScript 测试框架，它为 Rspack 生态提供了全面、一流的支持，能够轻松集成到现有的 Rspack 项目中。
- [快速上手](/zh/guide/start/quick-start.md): 本章节介绍如何快速上手 Rstest。
- [功能导航](/zh/guide/start/features.md): Rstest 为 JavaScript 和 TypeScript 项目提供快速、与构建集成的测试体验，覆盖本地开发和 CI。
- [AI](/zh/guide/start/ai.md): 本章节介绍如何帮助 AI 更全面地了解 Rstest 的功能、配置与最佳实践，从而在日常开发和问题排查过程中提供更准确的帮助。
- [命令行工具](/zh/guide/basic/cli.md): Rstest 提供了一个轻量级的命令行工具，包含 rstest watch 和 rstest run 等命令。
- [配置 Rstest](/zh/guide/basic/configure-rstest.md): 本章节介绍如何配置 Rstest 以及其底层使用的 Rsbuild 和 Rspack。
- [CSS](/zh/guide/basic/css.md): 介绍如何在 Rstest 中处理 CSS、CSS Modules、Less 和 Sass，以及如何在逻辑测试中替换样式导入。
- [过滤测试](/zh/guide/basic/test-filter.md): Rstest 提供了多种灵活的方式来过滤和选择要运行的测试文件和测试用例。你可以通过配置文件、命令行参数、测试 API 等方式精准控制测试范围。
- [Mocking](/zh/guide/basic/mock.md): 使用 Rstest mock 函数、对象方法、ESM 模块、CommonJS 模块，并区分 mock 状态和模块状态。
- [快照测试](/zh/guide/basic/snapshot.md): 快照测试（Snapshot Testing）是一种强大的测试方法，用于捕获和比较组件输出的序列化表示。当你的 UI 或数据结构发生变化时，快照测试能够帮助你及时发现这些变更。
- [E2E 测试](/zh/guide/basic/e2e-testing.md): 本 E2E 测试指南介绍如何使用 @rstest/playwright，在运行于 Node.js worker 的 Rstest 测试中测试完整页面和应用。
- [多项目测试](/zh/guide/basic/projects.md): Rstest 支持在单个 Rstest 进程中同时运行多个测试项目，这些项目可以有不同的测试配置和环境。
- [Reporters](/zh/guide/basic/reporters.md): Rstest 中的报告器控制测试结果的显示和处理方式。
- [VS Code 扩展](/zh/guide/basic/vscode-extension.md): Rstack VS Code 扩展能够在编辑器内同步项目测试，让你在 VS Code 中浏览、运行和调试测试。
- [升级 Rstest](/zh/guide/basic/upgrade-rstest.md): 本章节介绍如何将项目中的 Rstest 依赖升级到最新版本。
- [CI](/zh/guide/advanced/ci.md): 在 CI 中配置 Rstest，包括基础工作流、覆盖率、浏览器测试、分片和报告产物。
- [Metadata](/zh/guide/advanced/metadata.md): 为测试、套件和文件附加结构化 metadata，供自定义 Reporter 和 programmatic result 处理。
- [作用域清理](/zh/guide/advanced/scoped-cleanup.md): 使用 `using` 和 `await using` 在代码块退出时自动清理测试中的临时资源。
- [适配器](/zh/guide/advanced/adapters.md): 适配器是一个强大的功能，它允许你将来自其他工具（如构建工具或 CLI）的配置转换为 Rstest 支持的配置格式。通过创建一个自定义适配器，你可以复用现有配置，避免在多个工具之间重复定义，并确保项目的一致性。
- [模块联邦](/zh/guide/advanced/module-federation.md): 使用 Rstest 在 Node、JSDOM 和 Browser Mode 中加载并测试真实的模块联邦生产者。
- [浏览器模式](/zh/guide/browser-testing/index.md): Rstest 提供了浏览器模式（Browser Mode），允许你在真实浏览器中运行测试，而不是使用 jsdom 或 happy-dom 等模拟环境。
- [快速开始](/zh/guide/browser-testing/getting-started.md): 本指南将帮助你在项目中配置并运行浏览器模式测试。
- [框架集成](/zh/guide/browser-testing/framework-guides.md): 本指南提供各前端框架在浏览器模式下的测试配置示例。
- [浏览器交互](/zh/guide/browser-testing/user-interactions.md): 本指南介绍在 Browser Mode 测试中如何模拟用户交互，并帮助你在稳定性、可维护性和控制粒度之间做选择。
- [React](/zh/guide/framework/react.md): 本指南介绍如何使用 Rstest 测试 React 应用和组件。Rstest 支持在 Node.js、SSR 和浏览器模式下测试 React。
- [Vue](/zh/guide/framework/vue.md): 本指南介绍如何使用 Rstest 测试 Vue 应用和组件。
- [更多框架](/zh/guide/framework/more.md): 你可以通过注册 Rsbuild 插件，为更多框架启用编译与测试支持。
- [从 Jest 迁移](/zh/guide/migration/jest.md): 本章节介绍如何将你的 Jest 项目迁移到 Rstest。
- [从 Vitest 迁移](/zh/guide/migration/vitest.md): 迁移指南，介绍如何从 Vitest 迁移到 Rstest。
- [调试](/zh/guide/debug/debugging.md): 为了便于排查问题，Rstest 提供了调试模式，你可以在执行测试时添加 DEBUG=rstest 环境变量来开启 Rstest 的调试模式，也可以通过在 VS Code 中设置断点的方式进行调试。
- [性能分析](/zh/guide/debug/profiling.md): Rstest 提供了多种工具和方法来分析测试运行的性能，帮助你识别和解决性能瓶颈。
- [问题排查](/zh/guide/debug/troubleshooting.md): Rstest 常见问题排查，包括迁移和运行时差异。
- [Rstest setup — agent execution prompt](/zh/guide/start/agent-install.md): Set up Rstest in a project that doesn't have a test runner configured yet. Pick the target, detect what it needs, install, verify. Rstest here means @rstest/core, the JavaScript testing framework powered by Rsbuild, not the Rust crate of the same name.
- [Migrate to Rstest](/zh/guide/start/agent-migrate.md)

## 配置

- [配置总览](/zh/config/index.md): 当前页面列出了 Rstest 所有的配置项，请查看 「配置 Rstest」 了解使用方式。
- [root](/zh/config/test/root.md): 指定项目根目录。可以是绝对路径，也可以是相对于 process.cwd() 的路径。root 将决定配置文件加载的起点，测试文件被搜索的起点等。
- [name](/zh/config/test/name.md): 测试项目的名称。通过 projects 定义的所有项目名称必须唯一。
- [include](/zh/config/test/include.md): 匹配 glob 规则的文件将被视为测试文件。这些规则会相对于 root 解析（默认是 process.cwd()）。
- [exclude](/zh/config/test/exclude.md): 匹配 glob 规则的文件将不会被视为测试文件。
- [setupFiles](/zh/config/test/setup-files.md): 一组 setup 文件列表，通常用于配置或设置测试环境，它们将在每个测试文件执行前运行。
- [globalSetup](/zh/config/test/global-setup.md): Rstest 中的 globalSetup 选项允许你运行 setup 和 teardown 代码，这些代码会在所有测试之前和完成后执行。
- [projects](/zh/config/test/projects.md): 定义多个测试项目，可以是一个目录、配置文件或 glob 模式，也可以是一个对象。Rstest 将会按照各个项目定义的配置运行对应的测试，所有项目的测试结果将会合并展示。
- [update](/zh/config/test/update.md): 当开启更新时，Rstest 将在测试过程中自动更新所有变更的快照并删除过时的快照。
- [globals](/zh/config/test/globals.md): 为测试文件提供全局的 Rstest API，如 expect、test、describe 等。
- [passWithNoTests](/zh/config/test/pass-with-no-tests.md): 默认情况下，当未找到测试用例时，Rstest 会将测试标记为失败。你可以将 passWithNoTests 设置为 true 来允许测试在未找到测试用例时通过。
- [onlyFailures](/zh/config/test/only-failures.md): 仅重新运行上一次运行中失败的测试文件。
- [includeSource](/zh/config/test/include-source.md): 源码内联测试（In-source testing）指的是测试代码与源代码写在同一个文件中，类似于 Rust 的模块测试。
- [forceRerunTriggers](/zh/config/test/force-rerun-triggers.md): 配置哪些变更文件会强制 Rstest 运行完整测试套件。
- [testNamePattern](/zh/config/test/test-name-pattern.md): 仅运行测试名称中匹配正则表达式或字符串的测试。
- [extends](/zh/config/test/extends.md): extends 选项允许你从外部来源扩展 Rstest 配置，例如使用适配器将其他构建工具的配置转换为 Rstest 兼容格式。
- [env](/zh/config/test/env.md): 自定义环境变量，在测试过程中可以通过 process.env 访问。
- [bail](/zh/config/test/bail.md): 在指定个数的测试失败后中止测试运行。这对于在发生失败时提前停止测试运行非常有用。
- [retry](/zh/config/test/retry.md): 如果测试执行失败，则重试特定次数。这对于一些会产生不稳定结果的测试用例很有帮助。
- [testTimeout](/zh/config/test/test-timeout.md): 测试的默认超时时间（以毫秒为单位）。设置为 0 禁用超时。
- [hookTimeout](/zh/config/test/hook-timeout.md): 单个测试 hook 的超时时间（毫秒）。设置为 0 禁用超时。
- [maxConcurrency](/zh/config/test/max-concurrency.md): 使用 test.concurrent 或 describe.concurrent 时允许同时运行的最大测试用例数量。
- [expect](/zh/config/test/expect.md): 配置 expect.poll 的重试间隔，以及轮询断言和浏览器元素断言的默认超时时间。
- [pool](/zh/config/test/pool.md): 配置运行测试所用的 worker pool。
- [isolate](/zh/config/test/isolate.md): 默认情况下，Rstest 会运行每个测试在一个独立的环境，这会使其避免受到一些模块副作用的影响，从而有助于提升测试的稳定性。
- [testEnvironment](/zh/config/test/test-environment.md): Rstest 默认使用 Node.js 作为测试环境。如果你在开发 Web 应用，可以使用类浏览器环境，如 jsdom 或 happy-dom。
- [federation](/zh/config/test/federation.md): 启用模块联邦支持。
- [browser（实验性）](/zh/config/test/browser.md): 浏览器模式配置。启用后，测试将在真实浏览器中运行，而非 Node.js 环境。
- [clearMocks](/zh/config/test/clear-mocks.md): 清除所有 mock 的 mock.calls、mock.instances、mock.contexts 和 mock.results 属性。
- [resetMocks](/zh/config/test/reset-mocks.md): 清除所有 mock 属性，并将每个 mock 的实现重置为其原始实现。
- [restoreMocks](/zh/config/test/restore-mocks.md): 重置所有 mock，并恢复被 mock 的对象的原始描述符。
- [unstubEnvs](/zh/config/test/unstub-envs.md): 每次测试时恢复之前使用 rs.stubEnv 更改的所有 process.env 值。
- [unstubGlobals](/zh/config/test/unstub-globals.md): 每次测试时恢复之前使用 rs.stubGlobal 更改的所有全局变量。
- [coverage](/zh/config/test/coverage.md): 选择覆盖率收集方式，支持 istanbul 和 v8。
- [reporters](/zh/config/test/reporters.md): 配置用于测试结果输出的报告器。
- [includeTaskLocation](/zh/config/test/include-task-location.md): 在收集测试信息时，是否包含测试的位置信息。
- [logHeapUsage](/zh/config/test/log-heap-usage.md): 打印每个测试的堆内存使用情况，有助于发现内存泄漏问题。
- [detectAsyncLeaks](/zh/config/test/detect-async-leaks.md): 检测测试文件结束后仍然存活的异步资源。
- [hideSkippedTests](/zh/config/test/hide-skipped-tests.md): 隐藏已跳过的测试用例的日志，以减少测试输出中的噪声。当跳过大量测试用例时（例如启用过滤器运行测试时），此功能尤其有用。
- [hideSkippedTestFiles](/zh/config/test/hide-skipped-test-files.md): 隐藏已跳过的测试文件的日志，以减少测试输出中的噪声。当跳过大量测试文件时（例如启用过滤器运行测试时），此功能尤其有用。
- [slowTestThreshold](/zh/config/test/slow-test-threshold.md): 测试运行时间超过指定毫秒数时，被认为是缓慢的并在报告结果中显示。
- [snapshotFormat](/zh/config/test/snapshot-format.md): 使用 pretty-format 提供的选项自定义快照格式。
- [chaiConfig](/zh/config/test/chai-config.md): 配置 Chai 断言库的选项，例如是否显示差异和截断阈值。
- [resolveSnapshotPath](/zh/config/test/resolve-snapshot-path.md): 默认情况下，Rstest 会将快照文件保存在与测试文件相同的目录下的 snapshots 文件夹中。你可以使用 resolveSnapshotPath 来自定义快照文件的存放位置。
- [printConsoleTrace](/zh/config/test/print-console-trace.md): console 方法调用时始终打印调用栈，这将有助于调试。
- [silent](/zh/config/test/silent.md): 控制是否输出测试中的 console 日志，或只保留失败任务的日志。
- [onConsoleLog](/zh/config/test/on-console-log.md): 自定义 console 日志的处理函数，这有助于过滤来自第三方库的日志。
- [disableConsoleIntercept](/zh/config/test/disable-console-intercept.md): 禁用 console 日志的拦截。默认情况下，Rstest 会对 console 日志做拦截，这样将有助于追踪日志来源。
- [plugins](/zh/config/build/plugins.md): plugins 选项用于注册 Rsbuild 插件。
- [source](/zh/config/build/source.md): 与输入的源代码相关的选项，如配置装饰器语法等。
- [output](/zh/config/build/output.md): 配置 Rstest 输出的选项，例如是否以 ES 模块格式输出 JavaScript 文件。
- [resolve](/zh/config/build/resolve.md): 与模块解析相关的选项，如配置别名策略、解析扩展名等。
- [tools](/zh/config/build/tools.md): 与底层工具相关的选项。如修改 Rspack 配置等。
- [dev](/zh/config/build/dev.md): 与本地开发调试有关的选项。
- [performance](/zh/config/build/performance.md): 配置 Rstest 在测试构建中使用的 Rsbuild performance 选项。

## API

- [API 总览](/zh/api/runtime-api/index.md): 当前页面列出了 Rstest 所有的测试 API。
- [Expect](/zh/api/runtime-api/test-api/expect.md): expect 用于在测试中创建断言。Rstest 提供了丰富的 API 及匹配器，支持轮询、快照断言等。
- [Test](/zh/api/runtime-api/test-api/test.md): test 用于定义一个测试用例，支持链式调用和 fixture 扩展。
- [Describe](/zh/api/runtime-api/test-api/describe.md): describe 用于定义测试套件（test suite），支持链式修饰符和参数化方法，便于灵活有序地组织测试。
- [Hooks](/zh/api/runtime-api/test-api/hooks.md): Hooks 允许你在测试或测试套件执行之前或之后运行初始化和清理逻辑。
- [Browser mode](/zh/api/runtime-api/browser-mode/index.md): Browser Mode API 由 @rstest/browser 提供，目标是让你在浏览器测试中使用 Playwright 风格的 Locator 工作流。
- [Locator](/zh/api/runtime-api/browser-mode/locator.md): Locator 是 Browser Mode 的元素查询与交互核心 API。你可以通过 page.getBy* 或 page.locator() 构建查询链，再执行交互操作。具体执行语义由 browser provider 决定。
- [Assertion](/zh/api/runtime-api/browser-mode/assertion.md): expect.element 是 Browser Mode 中用于 Locator 断言的 API。它接收 Locator，返回可链式调用的断言对象。
- [Rstest Utility](/zh/api/runtime-api/rstest/index.md): Rstest 提供了一些实用函数，通过 rs 工具方法可以帮助你更方便地进行测试。
- [Mock modules](/zh/api/runtime-api/rstest/mock-modules.md): Rstest 支持对模块进行 mock，这使得你可以在测试中替换模块的实现。
- [Mock functions](/zh/api/runtime-api/rstest/mock-functions.md): Rstest 基于 tinyspy 提供了一些工具方法帮助你进行函数的模拟（mock）。
- [Mock instance](/zh/api/runtime-api/rstest/mock-instance.md): MockInstance 是所有 mock 和 spy 实例的类型。
- [Fake timers](/zh/api/runtime-api/rstest/fake-timers.md): 当你的代码中设置了很长的定时器（timeout），而你又不想在测试中等待它们时，fake timers 会非常有用。
- [Utilities](/zh/api/runtime-api/rstest/utilities.md): 提供一些实用的工具函数，如模拟环境变量、全局变量等。
- [环境变量](/zh/api/runtime-api/environment-variables.md): Rstest 注入到测试进程和 worker 进程中的环境变量。

## 集成

- [Rslint](/zh/integration/rslint.md): 本页面介绍 Rslint 内置的 Rstest rules。
- [Rslib](/zh/integration/rslib/index.md): 本指南介绍如何在 Rslib 项目中集成 Rstest，并复用已有的 Rslib 构建配置。
- [Rslib adapter 配置参考](/zh/integration/rslib/reference.md): Rstest Rslib adapter 的 API 和配置映射参考。
- [Rsbuild](/zh/integration/rsbuild/index.md): 本指南介绍如何在 Rsbuild 项目中集成 Rstest，并复用已有的 Rsbuild 构建配置。
- [Rsbuild adapter 配置参考](/zh/integration/rsbuild/reference.md): Rstest Rsbuild adapter 的 API 和配置映射参考。
- [Rspack](/zh/integration/rspack/index.md): 本指南介绍如何在 Rspack 项目中集成 Rstest，并复用已有的 Rspack 构建配置。
- [Rspack adapter 配置参考](/zh/integration/rspack/reference.md): Rstest Rspack adapter 的 API 和配置映射参考。

## 博客

- [Rstest 博客](/zh/blog/index.md): Rstest 博客归档，涵盖版本发布、生态更新和团队技术文章。
- [Rstest 0.12 发布](/zh/blog/announcing-0-12.md): Rstest 0.12 新增 E2E 与 Module Federation 测试支持，通过 VM pool 和 test environment prebundle 提升大型测试套件性能，并正式推出新的 JavaScript API。
- [Rstest 0.11 发布](/zh/blog/announcing-0-11.md): Rstest 0.11 是迈向 1.0 的过渡版本：通过一批不兼容变更收敛 test options、mock、pool、shard 等 API，同时带来更快的 V8 coverage 与升级后的 fake timers。
- [Rstest 0.10 发布](/zh/blog/announcing-0-10.md): Rstest 0.10 让测试运行更快、更可靠：新增 threads pool、--changed / --related 测试过滤、持久化构建缓存、基于内存状态的 worker 启动控制、--trace profiling，以及更清晰的 worker 输出归属。

## Others

- [Rstest 实例](/zh/api/javascript-api/instance.md): Rstest 实例 API 参考：createRstest、rstest.context、rstest.run、rstest.watch、rstest.listTests、rstest.mergeReports 和 runCLI。
- [Reporter](/zh/api/javascript-api/reporter.md): Reporter API 允许你创建自定义测试结果处理器和输出格式器。此接口是实验性的，在未来的版本中可能会发生变化。
- [Rstest core](/zh/api/javascript-api/rstest-core.md): 本章节介绍了 Rstest 提供的一些核心方法。
- [Rstest types](/zh/api/javascript-api/types.md): 从 @rstest/core 导入公开的 TypeScript 类型，用于配置、运行时 API、Reporter 和 mock 工具。