Snapshot testing

[dannymcgee]

This PR adds some utilities for snapshot testing (inspired by Jest), and migrates most of the parser tests over to snapshots.

Creating snapshot tests

To use snapshot testing, first import snapshot!, snapshot_test, and begin_snapshots! from the new snapshot crate. Call begin_snapshots! at the top of the test file, before creating any snapshot tests.

use snapshot::{begin_snapshots, snapshot, snapshot_test};

begin_snapshots!();

Annotate snapshot test functions with the #[snapshot_test] attribute — this is a drop-in replacement for #[test]:

// ...
#[snapshot_test]
fn my_snapshot_test() {
    // ...
}

In the body of the test function, create snapshot tests by calling the snapshot! macro. The macro can be invoked with one of two signatures:

• Check the result of parsing a particular syntax node (or an entire syntax tree)

  // ...
  #[snapshot_test]
  fn my_snapshot_test() {
    snapshot!(SyntaxTree "// Here's some WGSL code");
    //        ^^^^^^^^^^ The node whose `Parse` implementation should be invoked
  }

• Check the result of any arbitrary format string (using the familiar std::fmt syntax)

  // ...
  #[snapshot_test]
  fn my_snapshot_test() {
    // ...
    snapshot!("{some_debug_value:#?}");
    snapshot!("{:#?}", make_some_debug_value());
    snapshot!("{some_display_value}");
  }

How it works

Each snapshot! invocation is associated with a file path in this format:

<crate>/snapshots/<path/to/test/module>/<function_name>-<test_number>.wgsl-ast

Where:

• <crate> is the manifest directory of the crate being tested
• <path/to/test/module> is the module path of the file where the test functions are written
• <function_name> is the name of the #[snapshot_test] function
• <test_number> is n for the nth invocation of the snapshot! macro within that function

When the crate is tested, for each snapshot! invocation:

• If the associated snapshot file does not exist, a new one is written
• If the associated snapshot file does exist, the snapshot result is compared against the contents of that file
  • If they're identical, the test passes
  • If they're different, and nx test <project> was called with the --update flag, the snapshot file is overwritten with the new result
  • If they're different and the --update flag was not passed, the test fails, with the diff printed to stderr

[!IMPORTANT] If you intend to update the snapshots, you must invoke the tests with Nx:

npx nx test <project> --update

Attempting to call cargo test ... --update will fail due to the unrecognized --update flag.