mirror of
https://github.com/oxc-project/oxc.git
synced 2026-11-04 10:29:58 +00:00
docs(skills): simplify insta snapshot guidance for newer models (#26581)
GPT-6 Astra needs less step-by-step scaffolding, while explicit completion criteria help it carry work through verification. Following OpenAI's [guidance on rethinking skills and prompts for GPT-6 Astra](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra), this trims the Insta snapshot skill from 136 lines to 21 and removes repeated workflows and blanket accept/reject examples. The shorter skill keeps the important constraints: review expected output before accepting, use the non-interactive CLI, accept only snapshots from the current task, and rerun the affected test. It also makes completion explicit without requiring a commit for every snapshot update.
This commit is contained in:
Cameron authored and 
GitHub committed
1 parent
6c8a862f80
commit
171d8af71a
1 file changed
+7
-122
@@ -1,136 +1,21 @@
|
||||
---
|
||||
name: insta-snapshots
|
||||
description: Guide for working with and updating insta snapshot tests in Oxc without terminal interaction.
|
||||
description: Review and update Oxc Insta snapshots non-interactively after expected output changes or snapshot test failures.
|
||||
---
|
||||
|
||||
This skill guides you through working with [insta](https://insta.rs) snapshot tests in the Oxc codebase without requiring terminal interaction.
|
||||
# Insta snapshots
|
||||
|
||||
## What are Insta Snapshots?
|
||||
Run the affected test to generate pending snapshots. Use `cargo insta pending-snapshots` and read the old `.snap` and new `.snap.new` outputs to decide whether each change matches the intended behavior.
|
||||
|
||||
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.
|
||||
|
||||
## Running Tests and Generating Snapshots
|
||||
|
||||
### Run tests for a specific crate:
|
||||
|
||||
```bash
|
||||
cargo test -p <crate_name>
|
||||
```
|
||||
|
||||
This generates `.snap.new` files if test outputs have changed.
|
||||
|
||||
## Reviewing Snapshots Non-Interactively
|
||||
|
||||
**IMPORTANT**: Avoid using `cargo insta review` (the interactive terminal UI). Instead, follow these steps:
|
||||
|
||||
### 1. List all pending snapshots
|
||||
Use the CLI instead of the interactive `cargo insta review` UI or manually editing expected output:
|
||||
|
||||
```bash
|
||||
cargo insta pending-snapshots
|
||||
# Or for workspace-wide:
|
||||
cargo insta pending-snapshots --workspace
|
||||
```
|
||||
|
||||
This shows all `.snap.new` files waiting for review.
|
||||
|
||||
### 2. Read the snapshot files directly
|
||||
|
||||
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.
|
||||
|
||||
### 3. Accept or reject changes
|
||||
|
||||
**Accept all pending snapshots:**
|
||||
|
||||
```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:**
|
||||
Scope acceptance to the reviewed snapshots from this task; check `cargo insta accept --help` if a name or package filter is ambiguous. Avoid workspace-wide acceptance or rejection when unrelated pending snapshots exist. Fix unexpected output in the implementation before accepting it.
|
||||
|
||||
```bash
|
||||
cargo insta reject
|
||||
# Or workspace-wide:
|
||||
cargo insta reject --workspace
|
||||
```
|
||||
After accepting, inspect the snapshot diff and rerun the affected test. Finish with the intended `.snap` updates and no task-generated `.snap.new` files left pending. Updating snapshots does not itself call for a commit.
|
||||
|
||||
This deletes all `.snap.new` files.
|
||||
|
||||
### 4. Verify the changes
|
||||
|
||||
After accepting, the `.snap.new` files become `.snap` files. Check with git:
|
||||
|
||||
```bash
|
||||
git diff <path/to/snapshots/>
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### After fixing a bug or adding new snapshot tests:
|
||||
|
||||
1. Run tests: `cargo test -p oxc_linter` (or relevant crate)
|
||||
2. Check pending: `cargo insta pending-snapshots`
|
||||
3. Read new snapshots to verify they match expected behavior
|
||||
4. Accept if correct: `cargo insta accept`
|
||||
5. Commit the updated `.snap` files
|
||||
|
||||
### Working with specific test files:
|
||||
|
||||
1. Run: `cargo test -p oxc_linter specific_test_name`
|
||||
2. Read: `cargo insta pending-snapshots` - look for `specific_test_name.snap.new`
|
||||
3. Accept: `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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Example: Complete Workflow
|
||||
|
||||
```bash
|
||||
# 1. Make a code change to a linter rule
|
||||
# 2. Run tests
|
||||
cargo test -p oxc_linter
|
||||
|
||||
# 3. See what changed
|
||||
cargo insta pending-snapshots
|
||||
|
||||
# 4. Review specific snapshot (using Read tool)
|
||||
# Read: crates/oxc_linter/src/snapshots/some_test.snap.new
|
||||
|
||||
# 5. Accept if correct
|
||||
cargo insta accept -p oxc_linter
|
||||
|
||||
# 6. Verify with git
|
||||
git diff crates/oxc_linter/src/snapshots/
|
||||
|
||||
# 7. Run tests again to ensure everything passes
|
||||
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.
|
||||
Snapshots record expected output, including successful output in some crates. Linter diagnostic snapshots are under `crates/oxc_linter/src/snapshots/`; other crates have their own locations. Conformance `.snap.md` reports use a separate update mechanism; inspect the producing test harness rather than treating them as Insta pending snapshots.
|
||||
Reference in new issue
Block a user