Adds reflow scan plugin

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

@@ -19,21 +19,20 @@ export function generateIssueBody(finding: Finding, screenshotRepo: string): str
   }
 
   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.
-  `
+- [ ] The specific 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 violation does not regress.
+- [ ] This PR MUST NOT introduce any new accessibility issues or regressions.`
 
   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}.
+An accessibility scan ${finding.html ? `flagged the element \`${finding.html}\`` : `found an issue 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}` : ''}
+${screenshotSection ?? ''}
+To fix this, ${finding.solutionShort}.
+${solutionLong ? `\nSpecifically:\n\n${solutionLong}` : ''}
 
-  ${acceptanceCriteria}
-  `
+${acceptanceCriteria}
+`
 
   return body
 }

.github/actions/file/src/openIssue.ts

@@ -21,7 +21,11 @@ export async function openIssue(octokit: Octokit, repoWithOwner: string, finding
   const owner = repoWithOwner.split('/')[0]
   const repo = repoWithOwner.split('/')[1]
 
-  const labels = [`${finding.scannerType} rule: ${finding.ruleId}`, `${finding.scannerType}-scanning-issue`]
+  // Only include a ruleId label when it's defined
+  const labels = [
+    `${finding.scannerType}-scanning-issue`,
+    ...(finding.ruleId ? [`${finding.scannerType} rule: ${finding.ruleId}`] : []),
+  ]
   const title = truncateWithEllipsis(
     `Accessibility issue: ${finding.problemShort[0].toUpperCase() + finding.problemShort.slice(1)} on ${new URL(finding.url).pathname}`,
     GITHUB_ISSUE_TITLE_MAX_LENGTH,

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

@@ -1,8 +1,8 @@
 export type Finding = {
   scannerType: string
-  ruleId: string
+  ruleId?: string
   url: string
-  html: string
+  html?: string
   problemShort: string
   problemUrl: string
   solutionShort: string

.github/actions/file/src/updateFilingsWithNewFindings.ts

@@ -5,7 +5,7 @@ function getFilingKey(filing: ResolvedFiling | RepeatedFiling): string {
 }
 
 function getFindingKey(finding: Finding): string {
-  return `${finding.url};${finding.ruleId};${finding.html}`
+  return `${finding.url};${finding.scannerType};${finding.problemUrl}`
 }
 
 export function updateFilingsWithNewFindings(

.github/actions/file/tests/generateIssueBody.test.ts

@@ -11,13 +11,21 @@ const baseFinding = {
   solutionShort: 'ensure the contrast between foreground and background colors meets WCAG thresholds',
 }
 
+const findingWithEmptyOptionalFields = {
+  scannerType: 'reflow',
+  url: 'https://example.com/page',
+  problemShort: 'elements must meet minimum color contrast ratio thresholds',
+  problemUrl: 'https://dequeuniversity.com/rules/axe/4.10/color-contrast?application=playwright',
+  solutionShort: 'ensure the contrast between foreground and background colors meets WCAG thresholds',
+}
+
 describe('generateIssueBody', () => {
   it('includes acceptance criteria and omits the Specifically section when solutionLong is missing', () => {
     const body = generateIssueBody(baseFinding, 'github/accessibility-scanner')
 
     expect(body).toContain('## What')
     expect(body).toContain('## Acceptance Criteria')
-    expect(body).toContain('The specific axe violation reported in this issue is no longer reproducible.')
+    expect(body).toContain('The specific violation reported in this issue is no longer reproducible.')
     expect(body).not.toContain('Specifically:')
   })
 
@@ -61,4 +69,11 @@ describe('generateIssueBody', () => {
     expect(body).not.toContain('View screenshot')
     expect(body).not.toContain('.screenshots')
   })
+
+  it('uses url fallback when html is not present', () => {
+    const body = generateIssueBody(findingWithEmptyOptionalFields, 'github/accessibility-scanner')
+
+    expect(body).toContain(`found an issue on ${findingWithEmptyOptionalFields.url}`)
+    expect(body).not.toContain('flagged the element')
+  })
 })

.github/actions/file/tests/openIssue.test.ts

@@ -60,7 +60,7 @@ describe('openIssue', () => {
     expect(octokit.request).toHaveBeenCalledWith(
       expect.any(String),
       expect.objectContaining({
-        labels: ['axe rule: color-contrast', 'axe-scanning-issue'],
+        labels: ['axe-scanning-issue', 'axe rule: color-contrast'],
       }),
     )
   })

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

@@ -48,6 +48,7 @@ export async function findForUrl(
             plugin,
             page,
             addFinding,
+            url,
           })
         } else {
           core.info(`Skipping plugin ${plugin.name} because it is not included in the 'scans' input`)

.github/actions/find/src/pluginManager.ts

@@ -12,7 +12,8 @@ const __dirname = path.dirname(__filename)
 
 type PluginDefaultParams = {
   page: playwright.Page
-  addFinding: (findingData: Finding) => void
+  addFinding: (findingData: Finding) => Promise<void>
+  url: string
 }
 
 type Plugin = {
@@ -65,7 +66,7 @@ export async function loadCustomPlugins() {
 
   // - currently, the plugin manager will abort loading
   //   all plugins if there's an error
-  // - the problem with this is that if a scanner user doesnt
+  // - the problem with this is that if a scanner user doesn't
   //   have custom plugins, they won't have a 'scanner-plugins' folder
   //   which will cause an error and abort loading all plugins, including built-in ones
   // - so for custom plugins, if the path doesn't exist, we can return early
@@ -87,7 +88,13 @@ export async function loadPluginsFromPath({pluginsPath}: {pluginsPath: string})
 
       if (fs.existsSync(pluginFolderPath) && fs.lstatSync(pluginFolderPath).isDirectory()) {
         core.info(`Found plugin: ${pluginFolder}`)
-        plugins.push(await dynamicImport(path.join(pluginsPath, pluginFolder, 'index.js')))
+        const plugin = await dynamicImport(path.join(pluginsPath, pluginFolder, 'index.js'))
+        // Prevents a plugin from running twice
+        if (plugins.some(p => p.name === plugin.name)) {
+          core.info(`Skipping duplicate plugin: ${plugin.name}`)
+          continue
+        }
+        plugins.push(plugin)
       }
     }
   } catch (e) {
@@ -102,6 +109,6 @@ export async function loadPluginsFromPath({pluginsPath}: {pluginsPath: string})
 type InvokePluginParams = PluginDefaultParams & {
   plugin: Plugin
 }
-export function invokePlugin({plugin, page, addFinding}: InvokePluginParams) {
-  return plugin.default({page, addFinding})
+export function invokePlugin({plugin, page, addFinding, url}: InvokePluginParams) {
+  return plugin.default({page, addFinding, url})
 }

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

@@ -1,7 +1,7 @@
 export type Finding = {
   scannerType: string
   url: string
-  html: string
+  html?: string
   problemShort: string
   problemUrl: string
   solutionShort: string

.github/actions/find/tests/pluginManager.test.ts

@@ -12,12 +12,17 @@ vi.mock('../src/pluginManager.js', {spy: true})
 vi.mock('@actions/core', {spy: true})
 
 describe('loadPlugins', () => {
-  vi.spyOn(dynamicImportModule, 'dynamicImport').mockImplementation(path => Promise.resolve(path))
+  let dynamicImportCallCount = 0
+  vi.spyOn(dynamicImportModule, 'dynamicImport').mockImplementation(() => {
+    dynamicImportCallCount++
+    return Promise.resolve({name: `plugin-${dynamicImportCallCount}`, default: vi.fn()})
+  })
   beforeEach(() => {
+    dynamicImportCallCount = 0
     // @ts-expect-error - we don't need the full fs readdirsync
     // method signature here
-    vi.spyOn(fs, 'readdirSync').mockImplementation(readPath => {
-      return [readPath + '/plugin-1', readPath + '/plugin-2']
+    vi.spyOn(fs, 'readdirSync').mockImplementation(() => {
+      return ['folder-a', 'folder-b']
     })
     vi.spyOn(fs, 'lstatSync').mockImplementation(() => {
       return {
@@ -61,4 +66,26 @@ describe('loadPlugins', () => {
       expect(logSpy).toHaveBeenCalledWith(pluginManager.abortError)
     })
   })
+
+  describe('when built-in and custom plugins share the same name', () => {
+    beforeEach(() => {
+      // @ts-expect-error - we don't need the full fs readdirsync
+      // method signature here
+      vi.spyOn(fs, 'readdirSync').mockImplementation(() => {
+        return ['reflow-scan']
+      })
+      vi.spyOn(dynamicImportModule, 'dynamicImport').mockImplementation(() => {
+        return Promise.resolve({name: 'reflow-scan', default: vi.fn()})
+      })
+    })
+
+    it('skips the duplicate and only loads the plugin once', async () => {
+      pluginManager.clearCache()
+      const infoSpy = vi.spyOn(core, 'info').mockImplementation(() => {})
+      const plugins = await pluginManager.loadPlugins()
+      expect(plugins.length).toBe(1)
+      expect(plugins[0].name).toBe('reflow-scan')
+      expect(infoSpy).toHaveBeenCalledWith('Skipping duplicate plugin: reflow-scan')
+    })
+  })
 })

.github/scanner-plugins/test-plugin/index.js → .github/scanner-plugins/reflow-scan/index.js

@@ -1,32 +1,31 @@
-export default async function test({ page, addFinding, url } = {}) {
-  console.log('test plugin');
-    // Check for horizontal scrolling at 320x256 viewport
+export default async function reflowScan({ page, addFinding, url } = {}) {
+  console.log('reflow plugin');
+  const originalViewport = page.viewportSize()
+  // Check for horizontal scrolling at 320x256 viewport
   try {
-    await page.setViewportSize({ width: 320, height: 256 });
-    const scrollWidth = await page.evaluate(() => document.documentElement.scrollWidth);
-    const clientWidth = await page.evaluate(() => document.documentElement.clientWidth);
+    await page.setViewportSize({width: 320, height: 256})
+    const scrollWidth = await page.evaluate(() => document.documentElement.scrollWidth)
+    const clientWidth = await page.evaluate(() => document.documentElement.clientWidth)
 
     // If horizontal scroll is required (with 1px tolerance for rounding)
     if (scrollWidth > clientWidth + 1) {
-      const htmlSnippet = await page.evaluate(() => {
-        return `<html lang="${document.documentElement.lang || 'en'}">`;
-      });
-
-      addFinding({
-        scannerType: 'viewport',
-        ruleId: 'horizontal-scroll-320x256',
+      await addFinding({
+        scannerType: 'reflow-scan',
         url,
-        html: htmlSnippet.replace(/'/g, "&apos;"),
         problemShort: 'page requires horizontal scrolling at 320x256 viewport',
         problemUrl: 'https://www.w3.org/WAI/WCAG21/Understanding/reflow.html',
         solutionShort: 'ensure content is responsive and does not require horizontal scrolling at small viewport sizes',
-        solutionLong: `The page has a scroll width of ${scrollWidth}px but a client width of only ${clientWidth}px at 320x256 viewport, requiring horizontal scrolling. This violates WCAG 2.1 Level AA Success Criterion 1.4.10 (Reflow).`
-      });
+        solutionLong: `The page has a scroll width of ${scrollWidth}px but a client width of only ${clientWidth}px at 320x256 viewport, requiring horizontal scrolling. This violates WCAG 2.1 Level AA Success Criterion 1.4.10 (Reflow).`,
+      })
     }
   } catch (e) {
-    console.error('Error checking horizontal scroll:', e);
+    console.error('Error checking horizontal scroll:', e)
+  } finally {
+    // Restore original viewport so subsequent scans (e.g. Axe) aren't affected
+    if (originalViewport) {
+      await page.setViewportSize(originalViewport)
+    }
   }
-
 }
 
-export const name = 'test-plugin';
+export const name = 'reflow-scan';

.github/scanner-plugins/reflow-scan/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "reflow-scan",
+  "version": "1.0.0",
+  "description": "Scans pages at a 320x256 viewport size to identify potential reflow issues, such as horizontal scrolling and content overflow.",
+  "type": "module"
+}

.github/workflows/test.yml

@@ -80,6 +80,7 @@ jobs:
           repository: ${{ env.TESTING_REPOSITORY }}
           token: ${{ secrets.GH_TOKEN }}
           cache_key: ${{ steps.cache_key.outputs.cache_key }}
+          scans: '["axe", "reflow-scan"]'
 
       - name: Retrieve cached results
         uses: ./.github/actions/gh-cache/restore

PLUGINS.md

@@ -1,6 +1,6 @@
 # Plugins
 
-The plugin system allows teams to create custom scans/tests to run on their pages. An example of this is Axe interaction tests. In some cases, it might be desirable to perform specific interactions on elements of a given page before doing an Axe scan. These interactions are usually unique to each page that is scanned, so it would require the owning team to write a custom plugin that can interact with the page and run the Axe scan when ready. See the example under [.github/scanner-plugins/test-plugin](https://github.com/github/accessibility-scanner/tree/main/.github/scanner-plugins/test-plugin) (this is not an Axe interaction test, but should give a general understanding of plugin structure).
+The plugin system allows teams to create custom scans/tests to run on their pages. An example of this is Axe interaction tests. In some cases, it might be desirable to perform specific interactions on elements of a given page before doing an Axe scan. These interactions are usually unique to each page that is scanned, so it would require the owning team to write a custom plugin that can interact with the page and run the Axe scan when ready. See the existing plugins under [.github/scanner-plugins](https://github.com/github/accessibility-scanner/tree/main/.github/scanner-plugins) for examples of plugin structure.
 
 Some plugins come built-in with the scanner and can be enabled via [actions inputs](https://github.com/github/accessibility-scanner/tree/main/action.yml#L48-L50).
 
@@ -22,6 +22,10 @@ A async function (you must use `await` or `.then` when invoking this function) t
 
 - An object that should match the [`Finding` type](https://github.com/github/accessibility-scanner/blob/main/.github/actions/find/src/types.d.ts#L1-L9).
 
+#### `url`
+
+Passes in the URL of the page being scanned to be used when a finding is added.
+
 ## How to create plugins
 
 As mentioned above, plugins need to exist under `./.github/scanner-plugins`. For a plugin to work, it needs to meet the following criteria:

README.md

@@ -56,6 +56,7 @@ jobs:
           # open_grouped_issues: false # Optional: Set to true to open an issue grouping individual issues per violation
           # reduced_motion: no-preference # Optional: Playwright reduced motion configuration option
           # color_scheme: light # Optional: Playwright color scheme configuration option
+          # scans: '["axe","reflow-scan"]' # Optional: An array of scans (or plugins) to be performed. If not provided, only Axe will be performed.
 ```
 
 > 👉 Update all `REPLACE_THIS` placeholders with your actual values. See [Action Inputs](#action-inputs) for details.
@@ -125,7 +126,7 @@ Trigger the workflow manually or automatically based on your configuration. The
 | `include_screenshots`     | No       | Whether to capture screenshots of scanned pages and include links to them in filed issues. Screenshots are stored on the `gh-cache` branch of the repository running the workflow. Default: `false` | `true`                                                      |
 | `reduced_motion`          | No       | Playwright `reducedMotion` setting for scan contexts. Allowed values: `reduce`, `no-preference`                                                                                                     | `reduce`                                                    |
 | `color_scheme`            | No       | Playwright `colorScheme` setting for scan contexts. Allowed values: `light`, `dark`, `no-preference`                                                                                                | `dark`                                                      |
-| `scans`                   | No       | An array of scans (or plugins) to be performed. If not provided, only Axe will be performed.                                                                                                        | `['axe', ...other plugins]`                                 |
+| `scans`                   | No       | An array of scans (or plugins) to be performed. If not provided, only Axe will be performed.                                                                                                        | `'["axe", "reflow-scan", ...other plugins]'`                                 |
 
 ---
 

sites/site-with-errors/404.html

@@ -15,11 +15,15 @@
     line-height: 1;
     letter-spacing: -1px;
   }
+  .wide-element {
+    width: 500px;
+  }
 </style>
 
 <div class="container">
   <h1>404</h1>
 
   <p><strong>Page not found :(</strong></p>
   <p>The requested page could not be found.</p>
+  <div class="wide-element">This element is too wide for small viewports.</div>
 </div>

tests/site-with-errors.test.ts

@@ -43,10 +43,12 @@ describe('site-with-errors', () => {
       // Check volatile fields for existence only
       expect(issueUrl).toBeDefined()
       expect(problemUrl).toBeDefined()
-      expect(solutionLong).toBeDefined()
-      // Check `problemUrl`, ignoring axe version
-      expect(problemUrl.startsWith('https://dequeuniversity.com/rules/axe/')).toBe(true)
-      expect(problemUrl.endsWith(`/${finding.ruleId}?application=playwright`)).toBe(true)
+      // Axe-specific assertions
+      if (finding.scannerType === 'axe') {
+        expect(solutionLong).toBeDefined()
+        expect(problemUrl.startsWith('https://dequeuniversity.com/rules/axe/')).toBe(true)
+        expect(problemUrl.endsWith(`/${finding.ruleId}?application=playwright`)).toBe(true)
+      }
       // screenshotId is only present when include_screenshots is enabled
       if (screenshotId !== undefined) {
         expect(screenshotId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)
@@ -107,6 +109,12 @@ describe('site-with-errors', () => {
         ruleId: 'empty-heading',
         solutionShort: 'ensure headings have discernible text',
       },
+      {
+        scannerType: 'reflow-scan',
+        url: 'http://127.0.0.1:4000/404.html',
+        problemShort: 'page requires horizontal scrolling at 320x256 viewport',
+        solutionShort: 'ensure content is responsive and does not require horizontal scrolling at small viewport sizes',
+      },
     ]
     // Check that:
     // - every expected object exists (no more and no fewer), and
@@ -153,6 +161,7 @@ describe('site-with-errors', () => {
         'Accessibility issue: Headings should not be empty on /404.html',
         'Accessibility issue: Elements must meet minimum color contrast ratio thresholds on /about/',
         'Accessibility issue: Elements must meet minimum color contrast ratio thresholds on /jekyll/update/2025/07/30/welcome-to-jekyll.html',
+        'Accessibility issue: Page requires horizontal scrolling at 320x256 viewport on /404.html',
       ]
       expect(actualTitles).toHaveLength(expectedTitles.length)
       expect(actualTitles).toEqual(expect.arrayContaining(expectedTitles))

tests/types.d.ts

@@ -2,7 +2,7 @@ export type Finding = {
   scannerType: string
   ruleId: string
   url: string
-  html: string
+  html?: string
   problemShort: string
   problemUrl: string
   solutionShort: string