Adds screenshots to issues

Author: lindseywild

.github/actions/file/src/generateIssueBody.ts

@@ -11,17 +11,29 @@ export function generateIssueBody(finding: Finding, repoWithOwner: string): stri
           : line
       )
       .join("\n");
-    const acceptanceCriteria = `## Acceptance Criteria
+
+  let screenshotSection;
+  if (finding.screenshotId) {
+    const screenshotUrl = `https://raw.githubusercontent.com/${repoWithOwner}/gh-cache/.screenshots/${finding.screenshotId}.png`;
+    screenshotSection = `\n\n
+
+    ![Screenshot of the issue on ${finding.url}](${screenshotUrl})
+    `;
+  }
+
+  const acceptanceCriteria = `## Acceptance Criteria
   - [ ] The specific axe violation reported in this issue is no longer reproducible.
   - [ ] The fix MUST meet WCAG 2.1 guidelines OR the accessibility standards specified by the repository or organization.
   - [ ] A test SHOULD be added to ensure this specific axe violation does not regress.
   - [ ] This PR MUST NOT introduce any new accessibility issues or regressions.
   `;
-    const body = `## What
+
+  const body = `## What
   An accessibility scan flagged the element \`${finding.html}\` on ${finding.url} because ${finding.problemShort}. Learn more about why this was flagged by visiting ${finding.problemUrl}.
 
+  ${screenshotSection ?? ""}
   To fix this, ${finding.solutionShort}.
-  ${solutionLong ? `\nSpecifically:\n\n${solutionLong}` : ''}
+  ${solutionLong ? `\nSpecifically:\n\n${solutionLong}` : ""}
 
   ${acceptanceCriteria}
   `;

.github/actions/file/src/types.d.ts

@@ -7,6 +7,7 @@ export type Finding = {
   problemUrl: string;
   solutionShort: string;
   solutionLong?: string;
+  screenshotId?: string;
 };
 
 export type Issue = {

.github/actions/find/action.yml

@@ -9,6 +9,10 @@ inputs:
   auth_context:
     description: "Stringified JSON object containing 'username', 'password', 'cookies', and/or 'localStorage' from an authenticated session"
     required: false
+  include_screenshots:
+    description: "Whether to capture screenshots of scanned pages"
+    required: false
+    default: "true"
 
 outputs:
   findings:

.github/actions/find/src/findForUrl.ts

@@ -2,9 +2,25 @@ import type { Finding } from './types.d.js';
 import AxeBuilder from '@axe-core/playwright'
 import playwright from 'playwright';
 import { AuthContext } from './AuthContext.js';
+import fs from "node:fs";
+import path from "node:path";
 
-export async function findForUrl(url: string, authContext?: AuthContext): Promise<Finding[]> {
-  const browser = await playwright.chromium.launch({ headless: true, executablePath: process.env.CI ? '/usr/bin/google-chrome' : undefined });
+// Use GITHUB_WORKSPACE to ensure screenshots are saved in the workflow workspace root
+// where the artifact upload step can find them
+const SCREENSHOT_DIR = path.join(
+  process.env.GITHUB_WORKSPACE || process.cwd(),
+  ".screenshots",
+);
+
+export async function findForUrl(
+  url: string,
+  authContext?: AuthContext,
+  includeScreenshots: boolean = true,
+): Promise<Finding[]> {
+  const browser = await playwright.chromium.launch({
+    headless: true,
+    executablePath: process.env.CI ? "/usr/bin/google-chrome" : undefined,
+  });
   const contextOptions = authContext?.toPlaywrightBrowserContextOptions() ?? {};
   const context = await browser.newContext(contextOptions);
   const page = await context.newPage();
@@ -14,15 +30,46 @@ export async function findForUrl(url: string, authContext?: AuthContext): Promis
   let findings: Finding[] = [];
   try {
     const rawFindings = await new AxeBuilder({ page }).analyze();
-    findings = rawFindings.violations.map(violation => ({
-      scannerType: 'axe',
+
+    let screenshotId: string | undefined;
+
+    if (includeScreenshots) {
+      // Ensure screenshot directory exists
+      if (!fs.existsSync(SCREENSHOT_DIR)) {
+        fs.mkdirSync(SCREENSHOT_DIR, { recursive: true });
+        console.log(`Created screenshot directory: ${SCREENSHOT_DIR}`);
+      }
+
+      try {
+        const screenshotBuffer = await page.screenshot({
+          fullPage: true,
+          type: "png",
+        });
+
+        screenshotId = crypto.randomUUID();
+        const filename = `${screenshotId}.png`;
+        const filepath = path.join(SCREENSHOT_DIR, filename);
+
+        fs.writeFileSync(filepath, screenshotBuffer);
+        console.log(`Screenshot saved: ${filename}`);
+      } catch (error) {
+        console.error("Failed to capture/save screenshot:", error);
+        screenshotId = undefined;
+      }
+    }
+
+    findings = rawFindings.violations.map((violation) => ({
+      scannerType: "axe",
       url,
       html: violation.nodes[0].html.replace(/'/g, "&apos;"),
       problemShort: violation.help.toLowerCase().replace(/'/g, "&apos;"),
       problemUrl: violation.helpUrl.replace(/'/g, "&apos;"),
       ruleId: violation.id,
-      solutionShort: violation.description.toLowerCase().replace(/'/g, "&apos;"),
-      solutionLong: violation.nodes[0].failureSummary?.replace(/'/g, "&apos;")
+      solutionShort: violation.description
+        .toLowerCase()
+        .replace(/'/g, "&apos;"),
+      solutionLong: violation.nodes[0].failureSummary?.replace(/'/g, "&apos;"),
+      screenshotId,
     }));
   } catch (e) {
     // do something with the error

.github/actions/find/src/index.ts

@@ -12,10 +12,17 @@ export default async function () {
   );
   const authContext = new AuthContext(authContextInput);
 
+  const includeScreenshots =
+    core.getInput("include_screenshots", { required: false }) !== "false";
+
   let findings = [];
   for (const url of urls) {
     core.info(`Preparing to scan ${url}`);
-    const findingsForUrl = await findForUrl(url, authContext);
+    const findingsForUrl = await findForUrl(
+      url,
+      authContext,
+      includeScreenshots,
+    );
     if (findingsForUrl.length === 0) {
       core.info(`No accessibility gaps were found on ${url}`);
       continue;

.github/actions/find/src/types.d.ts

@@ -5,6 +5,7 @@ export type Finding = {
   problemUrl: string;
   solutionShort: string;
   solutionLong?: string;
+  screenshotId?: string;
 };
 
 export type Cookie = {

.github/actions/gh-cache/delete/action.yml

@@ -60,20 +60,22 @@ runs:
           echo "Created new orphaned 'gh-cache' branch"
         fi
 
-    - name: Copy file to repo
+    - name: Delete file from repo
       shell: bash
       run: |
-        if [ -f "${{ inputs.path }}" ]; then
+        if [ -e "${{ inputs.path }}" ]; then
           rm -Rf "${{ inputs.path }}"
-          rm -Rf ".gh-cache-${{ github.run_id }}/${{ inputs.path }}"
           echo "Deleted '${{ inputs.path }}' from 'gh-cache' branch"
+        else
+          echo "'${{ inputs.path }}' does not exist in 'gh-cache' branch"
+          echo "Skipping delete"
         fi
 
     - name: Commit and push
       shell: bash
       working-directory: .gh-cache-${{ github.run_id }}
       run: |
-        git add "${{ inputs.path }}" || true
+        git add --all -- "${{ inputs.path }}" || true
         git config user.name "github-actions[bot]"
         git config user.email "github-actions[bot]@users.noreply.github.com"
         git commit -m "$(printf 'Delete artifact: %s' "${{ inputs.path }}")" \

.github/actions/gh-cache/restore/action.yml

@@ -72,6 +72,9 @@ runs:
         src=".gh-cache-${{ github.run_id }}/${{ inputs.path }}"
         dest="${{ inputs.path }}"
         if [ -e "$src" ]; then
+          if [ -d "$src" ]; then
+            rm -rf "$dest"
+          fi
           mkdir -p "$(dirname "$dest")"
           cp -Rf "$src" "$dest"
           echo "Restored '${{ inputs.path }}' from cache"

.github/actions/gh-cache/save/action.yml

@@ -60,21 +60,24 @@ runs:
           echo "Created new orphaned 'gh-cache' branch"
         fi
 
-    - name: Copy file to repo
+    - name: Copy file or directory to repo
       shell: bash
       run: |
-        if [ -f "${{ inputs.path }}" ]; then
+        if [ -e "${{ inputs.path }}" ]; then
           mkdir -p ".gh-cache-${{ github.run_id }}/$(dirname "${{ inputs.path }}")"
           cp -Rf "${{ inputs.path }}" ".gh-cache-${{ github.run_id }}/${{ inputs.path }}"
           echo "Copied '${{ inputs.path }}' to 'gh-cache' branch"
+        else
+          echo "'${{ inputs.path }}' does not exist"
+          echo "Skipping copy"
         fi
 
     - name: Commit and push
       shell: bash
       working-directory: .gh-cache-${{ github.run_id }}
       run: |
-        if [ -f "${{ inputs.path }}" ]; then
-          git add "${{ inputs.path }}"
+        if [ -e "${{ inputs.path }}" ]; then
+          git add -- "${{ inputs.path }}"
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git commit -m "$(printf 'Save artifact: %s' "${{ inputs.path }}")" \

action.yml

@@ -31,6 +31,10 @@ inputs:
     description: "Whether to skip assigning filed issues to Copilot"
     required: false
     default: "false"
+  include_screenshots:
+    description: "Whether to include screenshots of issues in the issue bodies"
+    required: false
+    default: "true"
 
 outputs:
   results:
@@ -80,6 +84,7 @@ runs:
       with:
         urls: ${{ inputs.urls }}
         auth_context: ${{ inputs.auth_context || steps.auth.outputs.auth_context }}
+        include_screenshots: ${{ inputs.include_screenshots }}
     - name: File
       id: file
       uses: ./../../_actions/github/accessibility-scanner/current/.github/actions/file
@@ -125,6 +130,12 @@ runs:
           }
           core.setOutput('results', JSON.stringify(results));
           core.debug(`Results: ${JSON.stringify(results)}`);
+    - if: ${{ inputs.include_screenshots == 'true' }}
+      name: Save screenshots
+      uses: ./../../_actions/github/accessibility-scanner/current/.github/actions/gh-cache/save
+      with:
+        path: .screenshots
+        token: ${{ inputs.token }}
     - name: Save cached results
       uses: ./../../_actions/github/accessibility-scanner/current/.github/actions/gh-cache/cache
       with: