refactor: ADR-006 T3+T4 — hoist setup, consolidate assertion helpers

.github/actions/upload-screenshots/action.yml

@@ -1,6 +1,6 @@
 ---
 name: 'Upload SnapDiff screenshots'
-description: 'Upload screenshot diffs and HTML report as CI artifacts'
+description: 'Upload screenshot diffs, HTML report, and optionally comment on PR'
 inputs:
   name:
     description: 'Artifact name prefix'
@@ -11,6 +11,9 @@ inputs:
   retention-days:
     description: 'Number of days to retain artifacts'
     default: '2'
+  pr-comment:
+    description: 'Post PR comment with report link (requires pull-requests: write)'
+    default: 'false'
 outputs:
   report-url:
     description: 'Direct URL to the inline HTML report artifact'
@@ -70,3 +73,41 @@ runs:
         name: ${{ inputs.name }}-report-full
         retention-days: ${{ inputs.retention-days }}
         path: ${{ inputs.report-path }}/
+
+    - name: Job summary
+      if: steps.check-report.outputs.exists == 'true'
+      shell: bash
+      run: |
+        cat >> "$GITHUB_STEP_SUMMARY" <<EOF
+        ### SnapDiff Report
+
+        | Artifact | Link |
+        |----------|------|
+        | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
+        | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
+        EOF
+
+    - name: Find existing PR comment
+      if: inputs.pr-comment == 'true' && github.event_name == 'pull_request'
+      uses: peter-evans/find-comment@v3
+      id: find-comment
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-author: 'github-actions[bot]'
+        body-includes: 'Screenshot diffs'
+
+    - name: Comment PR with report link
+      if: inputs.pr-comment == 'true' && github.event_name == 'pull_request'
+      uses: peter-evans/create-or-update-comment@v5
+      with:
+        comment-id: ${{ steps.find-comment.outputs.comment-id }}
+        issue-number: ${{ github.event.pull_request.number }}
+        edit-mode: replace
+        body: |
+          ### Screenshot diffs detected
+
+          | Artifact | Link |
+          |----------|------|
+          | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
+          | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
+          | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |

.github/workflows/test.yml

@@ -82,58 +82,9 @@ jobs:
 
       - uses: ./.github/actions/upload-screenshots
         if: failure()
-        id: upload-screenshots
         with:
           name: base-screenshots
-
-      - name: Find existing report comment
-        if: always() && github.event_name == 'pull_request'
-        uses: peter-evans/find-comment@v3
-        id: find-comment
-        with:
-          issue-number: ${{ github.event.pull_request.number }}
-          comment-author: 'github-actions[bot]'
-          body-includes: 'Screenshot diffs'
-
-      - name: Comment PR with report link
-        if: failure() && github.event_name == 'pull_request'
-        uses: peter-evans/create-or-update-comment@v5
-        with:
-          comment-id: ${{ steps.find-comment.outputs.comment-id }}
-          issue-number: ${{ github.event.pull_request.number }}
-          edit-mode: replace
-          body: |
-            ### Screenshot diffs detected
-
-            | Artifact | Link |
-            |----------|------|
-            | HTML report (inline preview) | ${{ steps.upload-screenshots.outputs.report-url || 'N/A' }} |
-            | Full report with images | ${{ steps.upload-screenshots.outputs.report-full-url || 'N/A' }} |
-            | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |
-
-      - name: Job summary with report links
-        if: failure()
-        run: |
-          cat >> "$GITHUB_STEP_SUMMARY" <<EOF
-          ### Screenshot diffs detected
-
-          | Artifact | Link |
-          |----------|------|
-          | HTML report (inline) | ${{ steps.upload-screenshots.outputs.report-url || 'N/A' }} |
-          | Full report with images | ${{ steps.upload-screenshots.outputs.report-full-url || 'N/A' }} |
-          | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |
-          EOF
-
-      - name: Update comment on success
-        if: success() && github.event_name == 'pull_request' && steps.find-comment.outputs.comment-id != ''
-        uses: peter-evans/create-or-update-comment@v5
-        with:
-          comment-id: ${{ steps.find-comment.outputs.comment-id }}
-          edit-mode: replace
-          body: |
-            ### Screenshot diffs resolved
-
-            All screenshots match their baselines. Previous diffs have been fixed.
+          pr-comment: 'true'
 
       - name: Uploading Coverage Report
         uses: actions/upload-artifact@v7
@@ -253,17 +204,5 @@ jobs:
         run: bin/rake 'report:sample[embed]'
 
       - uses: ./.github/actions/upload-screenshots
-        id: upload-screenshots
         with:
           name: test-report
-
-      - name: Job summary with report links
-        run: |
-          cat >> "$GITHUB_STEP_SUMMARY" <<'EOF'
-          ### SnapDiff Report
-
-          | Artifact | Link |
-          |----------|------|
-          | HTML report (inline) | ${{ steps.upload-screenshots.outputs.report-url || 'N/A' }} |
-          | Full report with images | ${{ steps.upload-screenshots.outputs.report-full-url || 'N/A' }} |
-          EOF

README.md

@@ -118,17 +118,18 @@ After tests run, open `doc/screenshots/snap_diff_report.html`:
 
 Review all visual changes in one place — no need to hunt through `.diff.png` files. 4 view modes (both/base/new/heatmap), per-image zoom, annotation toggle, keyboard navigation, and search.
 
-**In GitHub Actions**, the report renders inline as a CI artifact — no download needed. Add a PR comment with a link to the report automatically:
+**In GitHub Actions**, one step uploads the report, posts a PR comment with the link, and adds a job summary:
 
 ```yaml
 - name: Upload screenshot report
   if: failure()
   uses: snap-diff/snap_diff-capybara/.github/actions/upload-screenshots@master
   with:
     name: screenshots
+    pr-comment: 'true'
 ```
 
-See [CI Integration](docs/ci-integration.md) for the full GitHub Actions setup with PR commenting.
+See [CI Integration](docs/ci-integration.md) for full setup including Ruby + libvips action and baseline update workflow.
 
 ## Compare Any Two Images