Binary snapshots (in-memory)

[lasernoises]

The biggest difference to the previous attempt in #489 is that the snapshot contents are now kept in-memory instead of being written into a temporary file directly.

For SnapshotContents I decided to make it an enum with two variants like in the previous attempt. I first attempted to change it to three variants so it would also replace the SnapshotKind enum but I realized that a lot of logic is still shared between inline and file text snapshots. That approach would definitely also work though and it's perhaps also a question of how much the logic between the two is expected to diverge in the future.

In runtime::assert_snapshot I replaced the combination of the refval and new_snapshot_value with an enum. In that case it is a three variant enum and some From impls for two value tuples for the macros. Maybe it would be better to make it a two variant enum there too for consistency and keep the ReferenceValue enum for the text case. That might be a bit weird because both binary and non-inline text snapshot have a name and that would then be in two different enums.

I should probably also add some tests in cargo-insta. I'll do that as soon as possible, but I need to figure out how the testing there works.

[max-sixty]

It's in impressive effort! And thank you for redoing on top of the new master.

It does add lots more data structures & some complications to the code. I'm going to think about how much we could simplify (I've already simplified the existing code somewhat..). If you have ideas, that would be great too.

[max-sixty]

For SnapshotContents I decided to make it an enum with two variants like in the previous attempt. I first attempted to change it to three variants so it would also replace the SnapshotKind enum but I realized that a lot of logic is still shared between inline and file text snapshots. That approach would definitely also work though and it's perhaps also a question of how much the logic between the two is expected to diverge in the future.

FWIW I think the ontology is quite an interesting case — FileText & FileBinary share some properties, but FileText & InlineText also share some completely different properties. So there's no perfect hierarchy.

The proposed structure seems reasonable (as above I'd like to see if we can reduce the number of data structures a bit, but I don't think there are any easy large clean-ups)

[max-sixty]

To sketch out what I think we need to do to merge:

• Tests — we already have a couple good integration tests. Would be great to extend those to any corner cases — for example, what if someone uses the same extension for a text snapshot? What does it look like if someone has an older version of cargo-insta? (maybe those are too specific, but anything in that direction)
• @mitsuhiko needs to review, I think focused on the external API
  • Obv great if we can make the internal code nice, but also we can do that later, and would be a loss if this withered based on refinements.
• We should decide whether we mark as experimental. If we don't mark it as experimental, we're stuck with the API, and in some ways insta has more stringent backward-compatibility constraints than other libraries, since it needs to work with older versions of itself in the form of cargo-insta)
• Docs — we should add a short section on this in https://github.com/mitsuhiko/insta-website

[max-sixty]

Let's add a couple of examples to the docs and then hit the big button. Thank you very much for all your persistence here, I know it was a long road. It's a great feature for insta!

[lasernoises]

The deleting of unreferenced snapshots does not work for binary snapshots yet. I'm working on fixing that now.

[lasernoises]

Now it works, but I'm not quite sure what the best error handling strategy there is. It needs to load the snapshot now to know whether it's binary and to get the extension. It still ignores errors when deleting the files like before. So I think it should probably also ignore errors when loading the snapshot and just skip it and maybe print a log message.

[lasernoises]

What I'm a bit more worried about is the internals module. I am changing some things that are exposed in there. The docstring does imply that it's primarily for documentation. So that might imply that it's not part of the stable API?

Yes, this is hidden and so not part of the public API (somewhat by convention). We only have it public so cargo-insta can access it.

I meant to reply to this earlier but forgot:
I think you meant the _cargo_insta_support module. Because the internals module is actually not hidden. I think given that it's called internals we can probably justify changing things exposed in it. Maybe it would make sense to add a comment there that explicitly states that this is not guaranteed to be stable.

[lasernoises]

I've started adding a section for the website: https://github.com/mitsuhiko/insta-website/compare/main...lasernoises:insta-website:binary-snapshots?expand=1. I think I'll wait with opening a PR until this is merged.

[max-sixty]

I think you meant the _cargo_insta_support module. Because the internals module is actually not hidden. I think given that it's called internals we can probably justify changing things exposed in it. Maybe it would make sense to add a comment there that explicitly states that this is not guaranteed to be stable.

Yes v good point. Would be great to add the comment (but no need to slow down this PR ofc)

[max-sixty]

@lasernoises anything else? Or we merge? :)

[lasernoises]

I think from my point of view we can merge.

[lasernoises]

🎉🎉🎉

Thank you so much for your patience and the many reviews/comments!

[max-sixty]

Thank you!!