Store snapshots using git lfs

.gitattributes

@@ -0,0 +1,3 @@
+# LFS settings
+# If changing, also change in .github/workflows/ci.yml
+parley/tests/snapshots/*.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -152,14 +152,51 @@ jobs:
       - name: cargo clippy (auxiliary)
         run: cargo hack clippy --workspace --locked --target ${{ matrix.target }} --optional-deps --each-feature --ignore-unknown-features --features std --tests --benches --examples -- -D warnings
 
+  prime-lfs-cache:
+    name: Prime LFS Cache
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Cache git lfs
+      id: lfs-cache
+      uses: actions/cache@v4
+      with:
+        path: .git/lfs
+        # The files targeted with git lfs
+        key: parley-lfs-${{ hashFiles('parley/tests/snapshots/*.png') }}
+        restore-keys: parley-lfs-
+        enableCrossOsArchive: true
+
+    - name: Fetch lfs data
+      if: ${{ steps.lfs-cache.outputs.cache-hit != 'true' }}
+      run: git lfs fetch
+
   test-stable:
     name: cargo test
+    needs: prime-lfs-cache
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [windows-latest, macos-latest, ubuntu-latest]
     steps:
       - uses: actions/checkout@v4
+        # We intentionally do not use lfs: true here, instead using the caching method to save LFS bandwidth.
+
+      - name: Restore lfs cache
+        id: lfs-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: .git/lfs
+          # The files targeted with git lfs
+          key: parley-lfs-${{ hashFiles('parley/tests/snapshots/*.png') }}
+          enableCrossOsArchive: true
+
+      - name: Checkout LFS files
+        run: git lfs checkout
+        continue-on-error: true
 
       - name: install stable toolchain
         uses: dtolnay/rust-toolchain@master
@@ -178,6 +215,11 @@ jobs:
 
       - name: cargo nextest
         run: cargo nextest run --workspace --locked --all-features --no-fail-fast
+        # env:
+          # Although GitHub's LFS limits are very low, we don't expect to run out of bandwidth.
+          # However, if we do, the tests are designed to be robust against that, if this environment variable is set.
+          # If we do run out of bandwidth, uncomment both `# env:` above and the following line, and inform @DJMcNab.
+          # PARLEY_IGNORE_DECODING_ERRORS: 1
 
       - name: cargo test --doc
         run: cargo test --doc --workspace --locked --all-features --no-fail-fast

parley/src/tests/utils/env.rs

@@ -190,8 +190,20 @@ impl TestEnv {
         if !snapshot_path.is_file() {
             return Err(format!("Cannot find snapshot {}", snapshot_path.display()));
         }
-        let snapshot_img = Pixmap::load_png(snapshot_path)
-            .map_err(|_| format!("Loading snapshot {} failed", snapshot_path.display()))?;
+        let snapshot_img = match Pixmap::load_png(snapshot_path) {
+            Ok(snapshot_img) => snapshot_img,
+            Err(d) => {
+                if std::env::var("PARLEY_IGNORE_DECODING_ERRORS").is_ok() {
+                    return Ok(());
+                }
+                return Err(format!(
+                    "Loading snapshot {} failed due to decoding error {d}.\n\
+                    If this file is an LFS file, install git lfs (https://git-lfs.com/) and run `git lfs pull`.\n\
+                    If that fails (due to e.g. a lack of bandwidth), rerun tests with `PARLEY_IGNORE_DECODING_ERRORS=1` to skip this test.",
+                    snapshot_path.display()
+                ))?;
+            }
+        };
         if snapshot_img.width() != current_img.width()
             || snapshot_img.height() != current_img.height()
         {