Add snapshot testing setup (#1506)

Author: senekor

.gitignore

@@ -6,3 +6,4 @@ static/styles/vendor.css
 static/styles/app.css
 static/styles/fonts.css
 static/styles/noscript.css
+src/snapshots

Cargo.lock

@@ -21,3 +21,6 @@ tera = "=1.20.0"
 
 [workspace]
 members = ["serve"]
+
+[dev-dependencies]
+insta = { version = "1.42.0", features = ["filters", "glob"] }

Cargo.toml

@@ -54,3 +54,28 @@ author: Blog post author (or on behalf of which team)
 release: true (to be only used for official posts about Rust releases announcements)
 ---
 ```
+
+### Snapshot testing
+
+If you're making changes to how the site is generated, you may want to check the impact your changes have on the output.
+For this purpose, there is a setup to do snapshot testing over the entire output directory.
+It's not run in CI, because the number of snapshots is too large.
+But you can run these tests locally as needed.
+
+- Make sure you have [cargo-insta](https://insta.rs/docs/quickstart/) installed.
+
+- Generate the good snapshots to compare against, usually based off the master branch:
+  ```sh
+  cargo insta test --accept --include-ignored
+  ```
+  Consider making a commit with these snapshots, so you can always check the diff of your changes with git:
+  ```sh
+  git add --force src/snapshots # snapshots are ignored by default
+  git commit --message "WIP add good snapshots"
+  ```
+  Since we can't merge the snapshots to main, don't forget to drop this commit when opening a pull request.
+
+- Compare the output of the branch you're working on with the good snapshots:
+  ```sh
+  cargo insta test --review --include-ignored
+  ```

README.md

@@ -302,3 +302,40 @@ pub fn main() -> eyre::Result<()> {
 
     Ok(())
 }
+
+#[test]
+fn snapshot() {
+    main().unwrap();
+    let timestamped_files = ["releases.json", "feed.xml"];
+    let inexplicably_non_deterministic_files = ["images/2023-08-rust-survey-2022/experiences.png"];
+    insta::glob!("..", "site/**/*", |path| {
+        if path.is_dir() {
+            return;
+        }
+        let path = path.display().to_string();
+        if timestamped_files
+            .into_iter()
+            .chain(inexplicably_non_deterministic_files)
+            .any(|f| path.ends_with(f))
+        {
+            // Skip troublesome files, e.g. they might contain timestamps.
+            // If possible, they are tested separately below.
+            return;
+        }
+        let content = fs::read(path).unwrap();
+        // insta can't deal with non-utf8 strings?
+        let content = String::from_utf8_lossy(&content).into_owned();
+        insta::assert_snapshot!(content);
+    });
+
+    // test files with timestamps filtered
+    insta::with_settings!({filters => vec![
+        (r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+\d{2}:\d{2}", "(filtered timestamp)"),
+    ]}, {
+        for file in timestamped_files {
+            let content = fs::read(format!("site/{file}")).unwrap();
+            let content = String::from_utf8_lossy(&content).into_owned();
+            insta::assert_snapshot!(content);
+        }
+    });
+}