> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# onlyFailures


[Added in v0.11.2](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.2)

- **类型：** `boolean`
- **默认值：** `false`
- **CLI：** `-f, --onlyFailures`

仅重新运行上一次运行中失败的测试文件。

当一次改动挂掉多个测试文件时，每修复一处通常都要付出一轮全量运行的代价来验证。启用 `onlyFailures` 后，Rstest 会记住上次失败的文件，只重跑这些文件，让每一轮「修复 → 验证」都保持快速。


**CLI**

```bash
npx rstest --onlyFailures
# 或使用简写
npx rstest -f
```


**rstest.config.ts**

```ts
import { defineConfig } from '@rstest/core';

export default defineConfig({
  onlyFailures: true,
});
```


## 示例

一次改动挂掉了 14 个测试文件中的 2 个：

```bash
npx rstest

 Test Files 2 failed | 12 passed
```

修复代码后，用 `-f` 验证——只有之前失败的 2 个文件会运行：

```bash
npx rstest -f

onlyFailures: running 2 of 14 test files (12 deselected).
```

重复这个过程直到全部通过。当不再有失败记录时，下一次 `-f` 运行会自动回退到全量运行：

```bash
npx rstest -f

No failed tests found from the previous run. Running all tests.
```

## 哪些文件会被重跑

`onlyFailures` 以整个测试文件为选择单位：

- 只要文件中有任意一个测试失败，整个文件都会重跑——包括其中已通过的测试。不支持只重跑单个失败的测试用例。
- 从未运行过的文件（例如你刚新增的文件）没有失败记录，不会被选中。先不带 `onlyFailures` 运行一次即可将其纳入。

:::info Browser Mode
[Browser Mode](/zh/config/test/browser.md) 项目的结果目前尚未被记录，因此 `onlyFailures` 不会排除它们的文件——browser 项目始终运行其全部测试文件。
:::

## 失败记录

Rstest 将每个测试文件最近一次的通过/失败状态保存在 workspace 根目录的 `node_modules/.cache/.rstest-results/` 中，并在每次运行后刷新。多 project 场景下，所有 project 共用这一份记录文件，条目按 project 区分。删除该目录即可重置记录。

部分运行不会覆盖记录，因此 `onlyFailures` 始终基于最近一次完整运行的结果工作：

- 使用 [testNamePattern](/zh/config/test/test-name-pattern.md)（`-t`）过滤的运行，只执行了每个文件中的部分测试。
- 被 [bail](/zh/config/test/bail.md) 中止的运行，未能执行到剩余的文件。

## 与其他筛选方式的关系

`onlyFailures` 只在完整运行时生效。通过以下方式指定运行范围时，以指定的范围为准，`onlyFailures` 会被忽略并打印一条警告（配置文件中开启的 `onlyFailures` 同样如此）：

- **文件过滤**——`npx rstest some.test.ts -f` 会精确运行你指定的文件，无论它们上次是否失败。
- **`--changed` / `--related`**——基于变更的选择已经定义了运行范围。若只想重跑该次运行中的失败，请在之后执行朴素的 `npx rstest -f`。
- **[testNamePattern](/zh/config/test/test-name-pattern.md)（`-t`）**——名称匹配需要在每个文件中搜索匹配的测试；若收窄到上次失败的文件，会静默漏掉通过文件中的匹配测试。
- **Watch 模式**——watch 本身就会重跑你编辑的文件，并提供重跑失败测试的快捷键。