Add screen-reader integration test

Introduce a new `test/screenreader/` suite that drives a real screen
reader (NVDA on Windows, VoiceOver on macOS) via `@guidepup/guidepup`,
and use it to cover bug 2034568.

Author: calixteman

.github/workflows/screenreader_tests.yml

@@ -0,0 +1,97 @@
+name: Screen reader tests
+on:
+  push:
+    paths:
+      - 'gulpfile.mjs'
+      - 'src/**'
+      - 'test/test.mjs'
+      - 'test/integration/test_utils.mjs'
+      - 'test/screenreader/**'
+      - 'web/**'
+      - '.github/workflows/screenreader_tests.yml'
+    branches:
+      - master
+  pull_request:
+    paths:
+      - 'gulpfile.mjs'
+      - 'src/**'
+      - 'test/test.mjs'
+      - 'test/integration/test_utils.mjs'
+      - 'test/screenreader/**'
+      - 'web/**'
+      - '.github/workflows/screenreader_tests.yml'
+    branches:
+      - master
+  workflow_dispatch:
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / ${{ matrix.browser }}
+
+    # Real screen-reader automation only works on Windows (NVDA) and macOS
+    # (VoiceOver), so Linux is intentionally absent from the matrix.
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [lts/*]
+        os: [windows-latest, macos-latest]
+        browser: [firefox, chrome]
+        include:
+          - browser: firefox
+            skip: --noChrome
+          - browser: chrome
+            skip: --noFirefox
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Installs the portable NVDA build (Windows) or grants the
+      # accessibility / Apple Events permissions VoiceOver needs (macOS)
+      # so guidepup can drive the screen reader. Inlined as an `npx` call
+      # rather than `guidepup/setup-action` because Mozilla's repo-level
+      # actions allowlist does not include the action.
+      - name: Set up screen reader
+        run: npx @guidepup/setup
+
+      - name: Restore cached PDF files
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: test/pdfs/*.pdf
+          key: cached-pdf-files-${{ hashFiles('test/pdfs/*.pdf') }}
+          restore-keys: |
+            cached-pdf-files-
+          enableCrossOsArchive: true
+
+      # Screen-reader automation cannot run headless, so a real display
+      # resolution is configured for the headful browser windows. macOS
+      # runners already provide one.
+      - name: Update resolution (Windows)
+        if: ${{ matrix.os == 'windows-latest' }}
+        run: Set-DisplayResolution -Width 1920 -Height 1080 -Force
+
+      - name: Run screen reader tests
+        run: npx gulp screenreadertest ${{ matrix.skip }}
+
+      - name: Save cached PDF files
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: test/pdfs/*.pdf
+          key: cached-pdf-files-${{ hashFiles('test/pdfs/*.pdf') }}
+          enableCrossOsArchive: true

gulpfile.mjs

@@ -752,6 +752,9 @@ function runTests(testsName, { bot = false } = {}) {
       case "integration":
         args.push("--integration");
         break;
+      case "screenreader":
+        args.push("--screenReader");
+        break;
       default:
         reject(new Error(`Unknown tests name '${testsName}'`));
         return;
@@ -2028,6 +2031,13 @@ gulp.task(
   })
 );
 
+gulp.task(
+  "screenreadertest",
+  gulp.series(setTestEnv, "generic", async function runScreenReaderTest() {
+    await runTests("screenreader");
+  })
+);
+
 gulp.task(
   "fonttest",
   gulp.series(setTestEnv, async function runFontTest() {