|
| 1 | +# Snapshot Testing |
| 2 | + |
| 3 | +> [!NOTE] |
| 4 | +> Also see the compile-fail tests, described [here](../tests/README.md). |
| 5 | +
|
| 6 | +This folder contains fixtures for snapshot testing the `#[versioned()]` macro. Snapshot testing is |
| 7 | +done using the [insta] crate. It provides a [CLI tool][insta-cli] called `cargo-insta` and a |
| 8 | +[VS Code extension][insta-ext]. |
| 9 | + |
| 10 | +Test inputs and snapshots of the expected output are located in the `fixtures` folder. There are two |
| 11 | +inputs to the `#[versioned()]` macro because it is an attribute macro: |
| 12 | + |
| 13 | +> The first TokenStream is the delimited token tree following the attribute’s name, not including |
| 14 | +> the outer delimiters. If the attribute is written as a bare attribute name, the attribute |
| 15 | +> TokenStream is empty. The second TokenStream is the rest of the item including other attributes on |
| 16 | +> the item. |
| 17 | +> |
| 18 | +> _(Taken from the [Rust reference][rust-ref])_ |
| 19 | +
|
| 20 | +Because of that, a special delimiter is used in the input files which separates the two inputs while |
| 21 | +still enabling developers to write valid Rust code. The delimiter is `// ---\n`. Most of the inner |
| 22 | +workings are located in [this file](../src/test_utils.rs). |
| 23 | + |
| 24 | +```rust |
| 25 | +#[versioned( |
| 26 | + version(name = "v1alpha1"), |
| 27 | + version(name = "v1beta1"), |
| 28 | + version(name = "v1") |
| 29 | +)] |
| 30 | +// --- <- See here! |
| 31 | +pub(crate) struct Foo { |
| 32 | + #[versioned( |
| 33 | + changed(since = "v1beta1", from_name = "jjj", from_type = "u8"), |
| 34 | + changed(since = "v1", from_type = "u16"), |
| 35 | + )] |
| 36 | + bar: usize, |
| 37 | + baz: bool, |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +## Recommended Workflow |
| 42 | + |
| 43 | +First, add new input files (which automatically get picked up by `insta`) to the `fixtures/inputs` |
| 44 | +folder. Make sure the delimiter is placed correctly between the attribute and the container |
| 45 | +definition. Doc comments on the container have to be placed after the delimiter. Next, generate the |
| 46 | +snapshot files (initially not accepted) by running |
| 47 | + |
| 48 | +```shell |
| 49 | +cargo insta test -p stackable-versioned-macros |
| 50 | +``` |
| 51 | + |
| 52 | +This command will place the new snapshot files (with a `.new` extension) in the `fixtures/snapshots` |
| 53 | +folder. These new snapshot files must not appear on `main`, but can be shared on branches for |
| 54 | +collaboration. To review them, run the `cargo insta review` command, then accept or fix the |
| 55 | +snapshots. Once all are accepted (ie: no `.new` files remaining), check in the files. |
| 56 | + |
| 57 | +[rust-ref]: https://doc.rust-lang.org/reference/procedural-macros.html#attribute-macros |
| 58 | +[insta-ext]: https://insta.rs/docs/vscode/ |
| 59 | +[insta-cli]: https://insta.rs/docs/cli/ |
| 60 | +[insta]: https://insta.rs/ |
0 commit comments