test: standardize snapshot terminology

Author: zharinov

.github/workflows/release.yml

@@ -73,7 +73,7 @@ jobs:
           cache-all-crates: "true"
           prefix-key: v0-rust-codegen-release
 
-      - name: Generate Rust fixtures
+      - name: Generate Rust snapshot tests
         run: make codegen-rust
 
       - name: Lint generated Rust

.github/workflows/stable.yml

@@ -91,7 +91,7 @@ jobs:
           prefix-key: v0-rust-codegen
           save-if: ${{ github.ref == 'refs/heads/master' }}
 
-      - name: Generate Rust fixtures
+      - name: Generate Rust snapshot tests
         run: make codegen-rust
 
       - name: Lint generated Rust

AGENTS.md

@@ -37,7 +37,7 @@ Two zones, one rule each:
 
 ## Backward compatibility
 
-As Plotnik is pre-release, backward compatibility is irrelevant and must not affect design or implementation. Make breaking changes directly and update all in-tree callers, tests, fixtures, and docs. Keep existing compatibility machinery, but use it only to validate the current format and keep all internal format-version integers at `0`.
+As Plotnik is pre-release, backward compatibility is irrelevant and must not affect design or implementation. Make breaking changes directly and update all in-tree callers, tests, test data, snapshots, and docs. Keep existing compatibility machinery, but use it only to validate the current format and keep all internal format-version integers at `0`.
 
 Do not add:
 
@@ -49,14 +49,14 @@ Do not add:
 
 # Commands
 
-| Command                  | What it does                                          |
-| ------------------------ | ----------------------------------------------------- |
-| `make check`             | `cargo check --workspace --all-targets`               |
-| `make clippy`            | clippy with `-D warnings`                             |
-| `make test [FILTER=...]` | full test suite via native Rust test harnesses        |
-| `make shot [FILTER=...]` | accept golden fixtures + insta snapshots, then re-run |
-| `make fmt`               | `cargo fmt` + prettier                                |
-| `make coverage-lines`    | per-file missing lines for `plotnik-lib`              |
+| Command                  | What it does                                   |
+| ------------------------ | ---------------------------------------------- |
+| `make check`             | `cargo check --workspace --all-targets`        |
+| `make clippy`            | clippy with `-D warnings`                      |
+| `make test [FILTER=...]` | full test suite via native Rust test harnesses |
+| `make shot [FILTER=...]` | update custom + Insta snapshots, then re-run   |
+| `make fmt`               | `cargo fmt` + prettier                         |
+| `make coverage-lines`    | per-file missing lines for `plotnik-lib`       |
 
 Check your changes: `make test`
 Before commit: `make fmt`
@@ -87,7 +87,7 @@ crates/
     src/vm/                    # runtime engine, backtracking, materialization
   plotnik-rt/                  # shared runtime engine (VM + generated matchers)
   plotnik-tests/
-    tests/                     # golden fixtures
+    tests/                     # snapshot tests
       mod.rs                   # test harness + docs
       01-lexer/
       02-parser/
@@ -209,15 +209,15 @@ cargo run -p plotnik-cli -- lang list                       # languages + aliase
 
 # Testing
 
-The golden fixtures have priority over Rust-based tests.
+The snapshot tests have priority over Rust-based tests.
 
 - Run `make shot` to (re)write generated sections
-- Use `FILTER=<name>` with `make test` or `make shot` to run the same filtered fixture subset
-- Name new fixture folders after existing ones in sibling stages
+- Use `FILTER=<name>` with `make test` or `make shot` to run the same filtered snapshot subset
+- Name new snapshot folders after existing ones in sibling stages
 - Rust `*_tests.rs` are unit-logic only
   - `foo.rs` gets a sibling `foo_tests.rs`, declared as `#[cfg(test)] mod foo_tests;`
   - AAA sections separated by blank lines (unless all 3 are one-liners)
   - single-line input literal, multi-line uses `indoc!`
-- Don't generate data for `insta` snapshots and golden fixtures by hand:
+- Don't generate snapshot data by hand:
   - use `@""` for `insta` placeholders, then `make shot`
-  - fill inputs only for golden snapshots
+  - author snapshot inputs only; let `make shot` write generated sections

Makefile

@@ -131,8 +131,8 @@ test-codegen-rust:
 
 shot:
 	@# See AGENTS.md for diagnostic guidelines
-	@# SHOT=1 accepts the golden-fixture suite (tests/0N-*); TRYBUILD=overwrite
-	@# refreshes the macro_diagnostics .stderr goldens; cargo insta accept does the rest.
+	@# SHOT=1 updates custom inline snapshots; TRYBUILD=overwrite updates .stderr snapshots.
+	@# The first run also records pending Insta snapshots, which cargo insta then accepts.
 	@SHOT=1 TRYBUILD=overwrite cargo test \
 		--workspace \
 		--lib \

crates/plotnik-lib/src/compiler/analyze/grammar/satisfiability/engine.rs

@@ -313,7 +313,7 @@ enum Edge {
 /// Default ceiling on satisfiability work before the query is declared too complex.
 /// Charged for automaton state allocation and in the two quadratic solve loops
 /// (`closure` and a `Visible` `thread_step`) for state visits and pattern-edge scans,
-/// so it caps the dominant costs. The widest real fixture settles in a few thousand
+/// so it caps the dominant costs. The widest real snapshot settles in a few thousand
 /// work units, leaving roughly three orders of magnitude of headroom, while a child list
 /// past about a thousand wide trips it in a fraction of a second rather than running
 /// for tens. Tunable per query via

crates/plotnik-lib/src/compiler/emit/targets/rust/config.rs

@@ -8,7 +8,7 @@ use plotnik_rt::{Limit, RuntimeLimitSpec};
 pub struct Config {
     /// Rust output-type configuration shared with the type renderer.
     pub(crate) rust_types: RustTypesConfig,
-    /// Whether to emit the JSON surface used by generated-code golden tests.
+    /// Whether to emit the JSON surface used by generated-code snapshot tests.
     pub(crate) debug: bool,
     /// The limit policy compiled into the module's safe entry points.
     /// Chosen at generation time, never at the call site: the query is

crates/plotnik-lib/src/compiler/emit/targets/rust/module.rs

@@ -8,7 +8,7 @@
 //!
 //! Emission is deterministic — instructions render in label order, names and
 //! tables come from `BTreeMap`s — so the same query always produces the same
-//! code (golden-snapshot-able, cache-friendly).
+//! code (snapshot-friendly, cache-friendly).
 //!
 //! Control skeletons (`run`, `backtrack`, `match_retry`) transcribe the VM's
 //! `execute_with_stats` / `backtrack` handler-for-handler over the shared

crates/plotnik-lib/src/compiler/parse/lexer_tests.rs

@@ -5,22 +5,22 @@ use similar::TextDiff;
 
 use super::lexer::dump_tokens;
 
-const FIXTURE_EXT: &str = "txt";
+const SNAPSHOT_EXT: &str = "txt";
 
 #[test]
-fn lexer_fixtures() {
+fn lexer_snapshots() {
     let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("test_data/01-lexer");
-    let mut fixtures = Vec::new();
-    discover(&root, &mut fixtures);
-    fixtures.sort();
+    let mut snapshots = Vec::new();
+    discover(&root, &mut snapshots);
+    snapshots.sort();
     assert!(
-        !fixtures.is_empty(),
-        "01-lexer fixtures should be present under {}",
+        !snapshots.is_empty(),
+        "01-lexer snapshots should be present under {}",
         root.display()
     );
 
     let mut failures = Vec::new();
-    for path in fixtures {
+    for path in snapshots {
         let raw =
             fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
         let normalized = raw.replace("\r\n", "\n");
@@ -47,21 +47,21 @@ fn lexer_fixtures() {
 
     assert!(
         failures.is_empty(),
-        "lexer fixtures out of date - run `make shot`:\n\n{}",
+        "lexer snapshots out of date - run `make shot`:\n\n{}",
         failures.join("\n\n")
     );
 }
 
 fn discover(dir: &Path, out: &mut Vec<PathBuf>) {
     let entries =
-        fs::read_dir(dir).unwrap_or_else(|e| panic!("read fixture dir {}: {e}", dir.display()));
+        fs::read_dir(dir).unwrap_or_else(|e| panic!("read snapshot dir {}: {e}", dir.display()));
     for entry in entries {
         let entry =
-            entry.unwrap_or_else(|e| panic!("read fixture entry in {}: {e}", dir.display()));
+            entry.unwrap_or_else(|e| panic!("read snapshot entry in {}: {e}", dir.display()));
         let path = entry.path();
         if path.is_dir() {
             discover(&path, out);
-        } else if path.extension().and_then(|e| e.to_str()) == Some(FIXTURE_EXT) {
+        } else if path.extension().and_then(|e| e.to_str()) == Some(SNAPSHOT_EXT) {
             out.push(path);
         }
     }
@@ -78,7 +78,7 @@ fn parse_query<'a>(raw: &'a str, path: &Path) -> &'a str {
         offset += line.len();
     }
     panic!(
-        "fixture {} must contain a `TOKENS` section rule",
+        "snapshot {} must contain a `TOKENS` section rule",
         path.display()
     )
 }

crates/plotnik-lib/src/vm/engine/value.rs

@@ -190,7 +190,7 @@ enum WorkItem<'a> {
 /// Output depth tracks source depth for captured-recursive queries, and a high or
 /// `Unbounded` depth limit lets it exceed any native-stack budget — so the walk
 /// uses an explicit work stack. Emission is byte-identical to the equivalent
-/// recursive printer; the `06-vm` golden fixtures pin that.
+/// recursive printer; the `06-vm` snapshots pin that.
 fn format_value<'a>(ctx: &mut FormatCtx<'_>, value: &'a Value<'a>, indent: usize) {
     let mut stack = vec![WorkItem::Value(value, indent)];
     while let Some(item) = stack.pop() {

crates/plotnik-tests/build.rs

@@ -56,7 +56,7 @@ fn main() {
         println!("cargo::rerun-if-changed={grammar_path}");
     }
 
-    generate_golden_tests(&manifest_dir);
+    generate_snapshot_tests(&manifest_dir);
 
     println!("cargo::rerun-if-changed=build.rs");
     println!("cargo::rerun-if-changed=Cargo.toml");
@@ -66,47 +66,47 @@ fn main() {
     );
 }
 
-fn generate_golden_tests(manifest_dir: &Path) {
+fn generate_snapshot_tests(manifest_dir: &Path) {
     let tests_dir = manifest_dir.join("tests");
-    let mut fixtures = Vec::new();
-    discover_fixtures(&tests_dir, &tests_dir, &mut fixtures);
-    fixtures.sort();
+    let mut snapshots = Vec::new();
+    discover_snapshots(&tests_dir, &tests_dir, &mut snapshots);
+    snapshots.sort();
 
     let mut tests = TestModule::default();
-    for relative in fixtures {
+    for relative in snapshots {
         tests.insert(&relative);
     }
     let mut generated = String::from("// @generated by crates/plotnik-tests/build.rs\n\n");
     tests.render(&mut generated, 0);
 
     let out_dir = PathBuf::from(std::env::var("OUT_DIR").expect("OUT_DIR must be set"));
-    let destination = out_dir.join("golden_tests.rs");
+    let destination = out_dir.join("snapshot_tests.rs");
     let unchanged = fs::read_to_string(&destination).is_ok_and(|current| current == generated);
     if !unchanged {
-        fs::write(destination, generated).expect("generated golden tests must be writable");
+        fs::write(destination, generated).expect("generated snapshot tests must be writable");
     }
     println!("cargo::rerun-if-changed={}", tests_dir.display());
 }
 
-fn discover_fixtures(dir: &Path, root: &Path, out: &mut Vec<String>) {
+fn discover_snapshots(dir: &Path, root: &Path, out: &mut Vec<String>) {
     let entries = fs::read_dir(dir)
-        .unwrap_or_else(|error| panic!("read fixture dir {}: {error}", dir.display()));
+        .unwrap_or_else(|error| panic!("read snapshot dir {}: {error}", dir.display()));
     for entry in entries {
         let entry = entry
-            .unwrap_or_else(|error| panic!("read fixture entry in {}: {error}", dir.display()));
+            .unwrap_or_else(|error| panic!("read snapshot entry in {}: {error}", dir.display()));
         let path = entry.path();
         if path.is_dir() {
-            discover_fixtures(&path, root, out);
+            discover_snapshots(&path, root, out);
             continue;
         }
         if path.extension().and_then(|extension| extension.to_str()) != Some("txt") {
             continue;
         }
         let relative = path
             .strip_prefix(root)
-            .expect("fixture path must be under tests/")
+            .expect("snapshot path must be under tests/")
             .to_str()
-            .unwrap_or_else(|| panic!("fixture path is not UTF-8: {}", path.display()))
+            .unwrap_or_else(|| panic!("snapshot path is not UTF-8: {}", path.display()))
             .replace(std::path::MAIN_SEPARATOR, "/");
         let stage = relative.split('/').next().unwrap_or("");
         if is_stage_dir(stage) {
@@ -127,18 +127,18 @@ fn is_stage_dir(name: &str) -> bool {
 #[derive(Default)]
 struct TestModule {
     modules: BTreeMap<String, TestModule>,
-    fixtures: BTreeMap<String, String>,
+    snapshots: BTreeMap<String, String>,
 }
 
 impl TestModule {
     fn insert(&mut self, relative: &str) {
         let mut components = relative.split('/').collect::<Vec<_>>();
         let file = components
             .pop()
-            .expect("fixture path must have a file name");
+            .expect("snapshot path must have a file name");
         let stem = file
             .strip_suffix(".txt")
-            .expect("fixture path must end in .txt");
+            .expect("snapshot path must end in .txt");
         require_snake_case(stem, relative);
 
         let mut module = self;
@@ -154,27 +154,27 @@ impl TestModule {
             module = module.modules.entry(identifier).or_default();
         }
 
-        let identifier = format!("fixture_{stem}");
+        let identifier = format!("snapshot_{stem}");
         if let Some(previous) = module
-            .fixtures
+            .snapshots
             .insert(identifier.clone(), relative.to_string())
         {
             panic!(
-                "fixture paths `{previous}` and `{relative}` both register Rust test `{identifier}`"
+                "snapshot paths `{previous}` and `{relative}` both register Rust test `{identifier}`"
             );
         }
     }
 
     fn render(&self, generated: &mut String, depth: usize) {
-        for (identifier, relative) in &self.fixtures {
+        for (identifier, relative) in &self.snapshots {
             let indent = "    ".repeat(depth);
             writeln!(generated, "{indent}#[test]").expect("write generated test attribute");
             writeln!(
                 generated,
                 "{indent}fn {identifier}() -> Result<(), String> {{"
             )
             .expect("write generated test declaration");
-            writeln!(generated, "{indent}    crate::run_fixture({relative:?})")
+            writeln!(generated, "{indent}    crate::run_snapshot({relative:?})")
                 .expect("write generated test body");
             writeln!(generated, "{indent}}}\n").expect("write generated test close");
         }
@@ -196,6 +196,6 @@ fn require_snake_case(component: &str, relative: &str) {
     let valid_rest =
         bytes.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_');
     if !valid_start || !valid_rest {
-        panic!("fixture path component `{component}` is not snake_case: {relative}");
+        panic!("snapshot path component `{component}` is not snake_case: {relative}");
     }
 }