API to read snapshots

[max-sixty]

Edit: to avoid reading this wall of text, see this comment for a summary

Below is the original comment

---

We have a process in PRQL to extract, compile, and test the examples in our book / docs. Currently we're extracting each PRQL example, making our own snapshot of the PRQL, and then running insta snapshots on the result of compiling that PRQL to SQL.

I wonder whether this is a common case, and we could replace "making our own snapshots of it" with "make an insta snapshot and then read it". For that, we'd need some sort of API where we could do something like read_snapshots!(prefix) -> [(id, snapshot_text)] or similar

---

Full details:

• In the book source, we just store the PRQL query, for example: https://github.com/PRQL/prql/blob/c186b135ce607fe851e026c037a7ef12cdd228f4/book/src/transforms/from_text.md?plain=1#L16-L26
• In the book HTML, we want to show the PRQL & SQL together, for example: https://prql-lang.org/book/transforms/from_text.html
• It's helpful to have the PRQL in files that we can read, independently of the markdown
• We want to check that those files are consistent with the markdown, which looks like a snapshot process
• So I wrote a function that does this — grab the PRQL from the markdown, write it if it doesn't match the current file & then raise — but is strictly worse than insta, except for the files being plain prql files: https://github.com/PRQL/prql/blob/2ecdfaac4796e12772afd0394268fdd9f366ab02/book/tests/snapshot.rs#L123-L159
• It generates files such as https://github.com/PRQL/prql/blob/2ecdfaac4796e12772afd0394268fdd9f366ab02/book/tests/prql/transforms/from_text-0.prql, which are then read and used as an input to the insta snapshot of the compiled SQL at https://github.com/PRQL/prql/blob/c186b135ce607fe851e026c037a7ef12cdd228f4/book/tests/snapshot.rs#L161-L178

Another use case for something like this would be testing a pipeline without having to start from the beginning. For example, to test our compilation, we could have a snapshot of each stage of the compiler, and be able to test the final step by reading a snapshot of the result in the middle, running the final stage, and asserting it matches a snapshotted final result. Currently with insta we can snapshot each stage, but it requires starting from the beginning.

---

This is an idea I've been brewing on today when writing some of this code, so possibly it's not complete / there is a simpler way to achieve the goal / it's actually fairly rare to need to start with an intermediate result.

[max-sixty]

Another approach here would be an API for writing & managing files that weren't .snap files.

So in the case above, we could write files like https://github.com/PRQL/prql/blob/2ecdfaac4796e12772afd0394268fdd9f366ab02/book/tests/prql/transforms/from_text-0.prql, and use insta rather than code like this: https://github.com/PRQL/prql/blob/2ecdfaac4796e12772afd0394268fdd9f366ab02/book/tests/snapshot.rs#L123-L159.

[max-sixty]

I realize there's a wall of text above, and my thinking has coalesced, so to summarize on the APi I'm thinking of:

• read_snapshot, which returns the text of the body of the snapshot
  • Would have to think about whether it deserializes a yaml snapshot, and how to best specify the snapshot name / path
• settings.use_plain, which would write a snapshot without any heading; just the text, so other processes can read it without needing to parse it

[NfNitLoop]

+1 for something like this.

Use case: We're using async-graphql, which is a code-first graphql library. But we need to generate the SDL schema for our GraphQL API so other languages/libraries can interact with our API.

I reached for Insta thinking I could just make an insta test and pass it my schema.sdl() string and a file path, which would let me use that file as both:

• The canonical graphql.schema declaration for the API.
• An Insta test to make sure no one has forgotten to re-run the command to snapshot (and code review) the new API changes.

[mitsuhiko]

I mean you can load snapshots even today with the Snapshot::from_file method. But actually determining the name will be tricky. I would love to see a mocked up idea of how you would try to use this.

[xamgore]

In another thread I show an example of testing library implementation with support for snapshots.

[mitsuhiko]

I dumped some ideas over there for how this could work if the snapshot macro were to be changed: #456 (comment)

[max-sixty]

One simple incremental approach would be to have an assert_snapshot_raw!(path, value) which:

• Writes value to path
• ...no metadata, no header, no .snap extension
• Uses all the insta snapshot machinery when the file doesn't match / is missing

It's a bit less orthogonal than other approaches — generally the macro type concerns the format of the snapshot rather than its type. But it would be useful.

---

Another approach would be .with_settings({raw=True, path="./foo/bar.html"}). This is a bit more orthogonal, a bit more work to implement.

[max-sixty]

For future travelers — #610 does some of this, since it can write an arbitrary value to an arbitrary file. (it doesn't allow literally reading snapshots though, still need some mapping to the file path)