insta-snapshots

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This skill guides you through working with insta snapshot tests in the Oxc codebase without requiring terminal interaction.

本技能将指导你在Oxc代码库中使用insta快照测试，无需终端交互。

What are Insta Snapshots?

什么是Insta快照？

Insta is a snapshot testing library for Rust. Oxc uses it extensively for:

Linter rule tests (
```
crates/oxc_linter/src/snapshots/
```
)

Semantic analysis tests (

crates/oxc_semantic/tests/integration/snapshots/

)

Other crate-specific snapshot tests

Snapshots track expected test outputs (often failures or errors). When code changes, new snapshots are generated as

.snap.new

files for review.

Insta是一款适用于Rust的快照测试库。Oxc广泛将其用于：

规则检查器测试（
```
crates/oxc_linter/src/snapshots/
```
）

语义分析测试（

crates/oxc_semantic/tests/integration/snapshots/

）

其他 crate 专属的快照测试

快照用于追踪预期测试输出（通常是失败或错误结果）。当代码变更时，新的快照会以

.snap.new

文件的形式生成，等待审核。

Running Tests and Generating Snapshots

运行测试并生成快照

Run tests for a specific crate:

为特定 crate 运行测试：

bash

cargo test -p <crate_name>

This generates

.snap.new

files if test outputs have changed.

bash

cargo test -p <crate_name>

如果测试输出发生变化，这会生成

.snap.new

文件。

Reviewing Snapshots Non-Interactively

非交互式审核快照

IMPORTANT: Avoid using

cargo insta review

(the interactive terminal UI). Instead, follow these steps:

重要提示：避免使用

cargo insta review

（交互式终端界面）。请遵循以下步骤：

1. List all pending snapshots

1. 列出所有待处理的快照

bash

cargo insta pending-snapshots

bash

cargo insta pending-snapshots

Or for workspace-wide:

或者针对整个工作区：

cargo insta pending-snapshots --workspace


This shows all `.snap.new` files waiting for review.

cargo insta pending-snapshots --workspace


这会显示所有等待审核的`.snap.new`文件。

2. Read the snapshot files directly

2. 直接读取快照文件

New snapshots are stored as

.snap.new

files next to their corresponding

.snap

files. You can use

cargo insta pending-snapshots

to view the changes to the snapshot files.

新快照以

.snap.new

文件的形式存储在对应

.snap

文件的旁边。你可以使用

cargo insta pending-snapshots

查看快照文件的变更内容。

3. Accept or reject changes

3. 接受或拒绝变更

Accept all pending snapshots:

bash

cargo insta accept

接受所有待处理快照：

bash

cargo insta accept

Or workspace-wide:

或者针对整个工作区：

cargo insta accept --workspace


**Accept specific snapshot(s):**

```bash
cargo insta accept --snapshot <snapshot_name>

Reject all pending snapshots:

bash

cargo insta reject

cargo insta accept --workspace


**接受特定快照：**

```bash
cargo insta accept --snapshot <snapshot_name>

拒绝所有待处理快照：

bash

cargo insta reject

Or workspace-wide:

或者针对整个工作区：

cargo insta reject --workspace


This deletes all `.snap.new` files.

cargo insta reject --workspace


这会删除所有`.snap.new`文件。

4. Verify the changes

4. 验证变更

After accepting, the

.snap.new

files become

.snap

files. Check with git:

bash

git diff <path/to/snapshots/>

接受后，

.snap.new

文件会变为

.snap

文件。使用git检查：

bash

git diff <path/to/snapshots/>

Common Workflows

常见工作流程

After fixing a bug or adding new snapshot tests:

修复 bug 或添加新快照测试后：

Run tests:
```
cargo test -p oxc_linter
```
(or relevant crate)
Check pending:
```
cargo insta pending-snapshots
```
Read new snapshots to verify they match expected behavior
Accept if correct:
```
cargo insta accept
```
Commit the updated
```
.snap
```
files

运行测试：
```
cargo test -p oxc_linter
```
（或相关 crate）
检查待处理快照：
```
cargo insta pending-snapshots
```
读取新快照，验证其是否符合预期行为
如果正确则接受：
```
cargo insta accept
```
提交更新后的
```
.snap
```
文件

Working with specific test files:

处理特定测试文件：

Run:

cargo test -p oxc_linter specific_test_name

Read:

cargo insta pending-snapshots

- look for

specific_test_name.snap.new

Accept:
```
cargo insta accept -p oxc_linter
```

运行：

cargo test -p oxc_linter specific_test_name

读取：

cargo insta pending-snapshots

- 查找

specific_test_name.snap.new

文件

接受：
```
cargo insta accept -p oxc_linter
```

Snapshot File Formats

快照文件格式

```
.snap
```
- Current expected output
```
.snap.new
```
- New output from recent test run (pending review), do not commit if these files are present

Note that

.snap.md

files are from Vitest, and not Insta. They are used in conformance tests, and are not handled by the instructions in this skill.

```
.snap
```
- 当前的预期输出
```
.snap.new
```
- 最近测试运行产生的新输出（待审核），请勿提交此类文件

注意：

.snap.md

文件来自Vitest，不属于Insta。它们用于一致性测试，本技能中的说明不适用于此类文件。

Tips

提示

Always review snapshots manually before accepting - don't blindly accept all changes
Snapshot files are checked into git - they're part of the test suite
Large snapshot changes may indicate breaking changes or bugs
Use
```
git diff
```
after accepting to see what actually changed
Use the CLI commands. DO NOT just copy-paste or manually edit
```
.snap
```
files.

接受前务必手动审核快照 - 不要盲目接受所有变更
快照文件会提交至git - 它们是测试套件的一部分
快照的大幅变更可能意味着存在破坏性变更或bug
接受后使用
```
git diff
```
查看实际变更内容
使用CLI命令操作。请勿直接复制粘贴或手动编辑
```
.snap
```
文件。

Example: Complete Workflow

示例：完整工作流程

bash

undefined

bash

undefined

1. Make a code change to a linter rule

1. 修改某个规则检查器的代码

2. Run tests

2. 运行测试

cargo test -p oxc_linter

3. See what changed

3. 查看变更内容

cargo insta pending-snapshots

4. Review specific snapshot (using Read tool)

4. 审核特定快照（使用读取工具）

Read: crates/oxc_linter/src/snapshots/some_test.snap.new

读取：crates/oxc_linter/src/snapshots/some_test.snap.new

5. Accept if correct

5. 如果正确则接受

cargo insta accept -p oxc_linter

6. Verify with git

6. 使用git验证

git diff crates/oxc_linter/src/snapshots/

7. Run tests again to ensure everything passes

7. 再次运行测试确保全部通过

cargo test -p oxc_linter


---

**When to use this skill**: When tests fail due to snapshot mismatches or after changing code that affects test outputs.

cargo test -p oxc_linter


---

**何时使用本技能**：当测试因快照不匹配而失败，或者在修改影响测试输出的代码之后。