Handle edge cases in E2E

.github/workflows/e2e.yml

@@ -1,3 +1,9 @@
+# We use github cache to save snapshots between runs.
+# For PRs and MergeQueues, the target commit is used, and for push events, github.event.previous is used.
+# If a snapshot for a given Hash is not found, we checkout that commit, run the tests and cache the snapshots.
+# These are then downloaded before running the E2E, providing the reference snapshots.
+# If there are any errors, the diff image is uploaded to artifacts, and the user is notified.
+
 name: E2E
 
 on:
@@ -9,7 +15,8 @@ permissions:
   contents: read
 
 env:
-  targetHash: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event_name == 'merge_group' && github.event.merge_group.base.sha || github.event.before }}
+  # For PRs and MergeQueues, the target commit is used, and for push events, github.event.previous is used.
+  targetHash: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
 
 jobs:
   cache:
@@ -30,6 +37,7 @@ jobs:
           path: ./cypress/snapshots
           key: ${{ runner.os }}-snapshots-${{ env.targetHash }}
 
+      # If a snapshot for a given Hash is not found, we checkout that commit, run the tests and cache the snapshots.
       - name: Switch to base branch
         if: ${{ steps.cache-snapshot.outputs.cache-hit != 'true' }}
         uses: actions/checkout@v4
@@ -44,6 +52,8 @@ jobs:
           start: pnpm run dev
           wait-on: 'http://localhost:9000'
           browser: chrome
+          spec:
+            cypress/integration/rendering/sequencediagram.spec.js
 
   e2e:
     runs-on: ubuntu-latest
@@ -64,6 +74,7 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
+      # These cached snapshots are downloaded, providing the reference snapshots.
       - name: Cache snapshots
         id: cache-snapshot
         uses: actions/cache/restore@v3
@@ -87,6 +98,8 @@ jobs:
           # e.g. if this action was run from a fork
           record: ${{ secrets.CYPRESS_RECORD_KEY != '' }}
           parallel: ${{ secrets.CYPRESS_RECORD_KEY != '' }}
+          spec:
+            cypress/integration/rendering/sequencediagram.spec.js
         env:
           CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
           VITEST_COVERAGE: true
@@ -104,9 +117,10 @@ jobs:
           verbose: true
           token: 6845cc80-77ee-4e17-85a1-026cd95e0766
 
+      # We upload the artifacts into numbered archives to prevent overwriting
       - name: Upload Artifacts
         uses: actions/upload-artifact@v4
-        if: ${{ failure() && steps.cypress.conclusion == 'failure' }}
+        if: ${{ always() }}
         with:
           name: snapshots-${{ matrix.containers }}
           retention-days: 1
@@ -117,38 +131,40 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ always() }}
     steps:
+      # Download all snapshot artifacts and merge them into a single folder
       - name: Download All Artifacts
         uses: actions/download-artifact@v4
         with:
           path: snapshots
           pattern: snapshots-*
           merge-multiple: true
-      
+
+      # For successful push events, we save the snapshots cache
       - name: Save snapshots cache
         id: cache-upload
-        if: ${{ github.event_name == 'push' }}
+        if: ${{ github.event_name == 'push' && needs.e2e.result != 'failure' }}
         uses: actions/cache/save@v3
         with:
-          path: |
-            ./cypress/snapshots
-            !./**/__diff_output__/*
+          path: ./snapshots
           key: ${{ runner.os }}-snapshots-${{ github.event.after }}
 
-      - if: ${{ failure() }}
+      - name: Flatten images to a folder
+        if: ${{ needs.e2e.result == 'failure'  }}
         run: |
           mkdir errors
           cd snapshots
           find . -mindepth 2 -type d -name "*__diff_output__*" -exec sh -c 'mv "$0"/*.png ../errors/' {} \;
+
       - name: Upload Error snapshots
-        if: ${{ failure() }}
+        if: ${{ needs.e2e.result == 'failure' }}
         uses: actions/upload-artifact@v4
         id: upload-artifacts
         with:
           name: error-snapshots
           retention-days: 10
           path: errors/
+
       - name: Notify Users
-        if: ${{ failure() }}
+        if: ${{ needs.e2e.result == 'failure' }}
         run: |
           echo "::error title=Visual tests failed::You can view images that failed by downloading the error-snapshots artifact: ${{ steps.upload-artifacts.outputs.artifact-url }}"
-