feat: default capture to "initial", allow logs to be preserved in navigateToWebContent, improve navigateToWebContent command (#34)

cmorten · web-flow · commit 32ac9164ab4d · 2026-06-09T22:58:35.000+01:00
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -17,8 +17,6 @@ on:
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [main]
-  schedule:
-    - cron: "34 4 * * 6"
 
 jobs:
   analyze:
@@ -38,7 +36,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -1,24 +1,22 @@
 name: Publish
 
-permissions:
-  contents: read
-
 on:
   release:
     types: [created]
 
+permissions:
+  id-token: write
+  contents: read
+
 jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version-file: .nvmrc
-          registry-url: https://registry.npmjs.org/
-          always-auth: true
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
       - run: yarn install --frozen-lockfile
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NODE_AUTH_TOKEN}}
-          CI: true
+      - run: npm publish
diff --git a/.github/workflows/test-nvda.yml b/.github/workflows/test-nvda.yml
@@ -1,28 +1,29 @@
 name: Test NVDA
 
-permissions:
-  contents: read
-
 on:
   push:
     branches: [main]
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   test-nvda:
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         os: [windows-2022, windows-2025]
         browser: [chromium, firefox]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version-file: .nvmrc
       - name: Guidepup Setup
-        uses: guidepup/setup-action@0.19.0
+        uses: guidepup/setup-action@0.20.0
         with:
           record: true
       - run: yarn install --frozen-lockfile
diff --git a/.github/workflows/test-voiceover.yml b/.github/workflows/test-voiceover.yml
@@ -1,28 +1,29 @@
 name: Test VoiceOver
 
-permissions:
-  contents: read
-
 on:
   push:
     branches: [main]
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   test-voiceover:
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
-        os: [macos-14]
+        os: [macos-14, macos-15, macos-15-intel, macos-26, macos-26-intel]
         browser: [chromium, firefox, webkit]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version-file: .nvmrc
       - name: Guidepup Setup
-        uses: guidepup/setup-action@0.19.0
+        uses: guidepup/setup-action@0.20.0
         with:
           record: true
       - run: yarn install --frozen-lockfile
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -1,19 +1,19 @@
 name: Test
 
-permissions:
-  contents: read
-
 on:
   push:
     branches: [main]
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version-file: .nvmrc
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -8,5 +8,6 @@
   },
   "[typescript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
-  }
+  },
+  "js/ts.tsdk.path": "node_modules/typescript/lib"
 }
diff --git a/README.md b/README.md
@@ -6,12 +6,11 @@
 
 ## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
 
-[![MacOS Monetary Support](https://img.shields.io/badge/macos-Monetary-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-monterey/id1576738294)
-[![MacOS Ventura Support](https://img.shields.io/badge/macos-Ventura-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-ventura/id1638787999)
 [![MacOS Sonoma Support](https://img.shields.io/badge/macos-Somona-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sonoma/id6450717509)
-[![Windows 10 Support](https://img.shields.io/badge/windows-10-blue.svg?logo=windows10)](https://www.microsoft.com/en-gb/software-download/windows10ISO)
-[![Windows Server 2019 Support](https://img.shields.io/badge/windows_server-2019-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2019)
+[![MacOS Sequoia Support](https://img.shields.io/badge/macos-Somona-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sequoia/id6596773750)
+[![MacOS Tahoe Support](https://img.shields.io/badge/macos-Tahoe-blue.svg?logo=apple)](https://www.apple.com/uk/os/macos/)
 [![Windows Server 2022 Support](https://img.shields.io/badge/windows_server-2022-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022)
+[![Windows Server 2025 Support](https://img.shields.io/badge/windows_server-2025-blue.svg?logo=windows)](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2025)
 
 This package provides [Guidepup](https://github.com/guidepup/guidepup) integration with [Playwright](https://playwright.dev/) for writing screen reader tests that automate <a href="https://www.guidepup.dev/docs/api/class-voiceover"><b>VoiceOver on MacOS</b></a> and <a href="https://www.guidepup.dev/docs/api/class-nvda"><b>NVDA on Windows</b></a>.
 
@@ -95,7 +94,7 @@ await nvda.navigateToWebContent();
 // ... some commands
 ```
 
-**Note:** This command clears all logs meaning `.spokenPhraseLog()` and `.itemTextLog()` are emptied. If logs from prior to the command are required, first store the logs in a variable for later use:
+**Note:** This command clears all logs by default meaning `.spokenPhraseLog()` and `.itemTextLog()` are emptied. If logs from prior to the command are required, either store the logs in a variable for later use:
 
 ```ts
 // ... some commands
@@ -114,6 +113,17 @@ const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];
 // ... do something with spoken phrases
 ```
 
+or pass a flag to prevent log clearing:
+
+```ts
+// ... some commands
+
+// Navigate to the web content
+await nvda.navigateToWebContent(false);
+
+// ... some commands
+```
+
 ### Providing Screen Reader Start Options
 
 The options provided to `nvda.start([options])` or `voiceOver.start([options])` can be configured using `test.use(config)` as follows:
@@ -122,16 +132,20 @@ The options provided to `nvda.start([options])` or `voiceOver.start([options])`
 // VoiceOver Example
 import { voiceOverTest as test } from "@guidepup/playwright";
 
-test.use({ voiceOverStartOptions: { capture: "initial" } });
+// Capture all spoken phrases, including usage hints
+test.use({ voiceOverStartOptions: { capture: true } });
 ```
 
 ```ts
 // NVDA Example
 import { nvdaTest as test } from "@guidepup/playwright";
 
-test.use({ nvdaStartOptions: { capture: "initial" } });
+// Capture all spoken phrases, including usage hints
+test.use({ nvdaStartOptions: { capture: true } });
 ```
 
+The default for VoiceOver and NVDA is set to `"initial"`. `true` captures all spoken phrases, including usage hints. `false` disables spoken phrase capture.
+
 ### VoiceOver Example
 
 `playwright.config.ts`:
@@ -148,6 +162,8 @@ const config: PlaywrightTestConfig = {
   projects: [
     {
       name: "webkit",
+      // Take care to ensure all usage is headed - screen readers cannot
+      // operate against headless browsers.
       use: { ...devices["Desktop Safari"], headless: false },
     },
   ],
@@ -206,6 +222,8 @@ const config: PlaywrightTestConfig = {
   projects: [
     {
       name: "firefox",
+      // Take care to ensure all usage is headed - screen readers cannot
+      // operate against headless browsers.
       use: { ...devices["Desktop Firefox"], headless: false },
     },
   ],
diff --git a/package.json b/package.json
@@ -1,14 +1,14 @@
 {
   "name": "@guidepup/playwright",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Screen reader driver for Playwright tests.",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "author": "Craig Morten <craig.morten@hotmail.co.uk>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/guidepup/guidepup-playwright"
+    "url": "git+https://github.com/guidepup/guidepup-playwright.git"
   },
   "bugs": {
     "url": "https://github.com/guidepup/guidepup-playwright/issues"
@@ -42,9 +42,9 @@
     "test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
   },
   "devDependencies": {
-    "@guidepup/guidepup": "^0.24.1",
+    "@guidepup/guidepup": "^0.25.0",
     "@guidepup/record": "^0.1.0",
-    "@playwright/test": "^1.58.0",
+    "@playwright/test": "^1.60.0",
     "@types/node": "^24.10.1",
     "@typescript-eslint/eslint-plugin": "^8.48.1",
     "@typescript-eslint/parser": "^8.48.1",
@@ -56,7 +56,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@guidepup/guidepup": ">=0.22.1",
+    "@guidepup/guidepup": ">=0.25.0",
     "@playwright/test": "^1.57.0"
   },
   "resolutions": {
diff --git a/src/nvdaTest.ts b/src/nvdaTest.ts
diff --git a/src/screenReaderConfig.ts b/src/screenReaderConfig.ts
diff --git a/src/voiceOverTest.ts b/src/voiceOverTest.ts
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -8,5 +8,6 @@`
`8`	`8`	`},`
`9`	`9`	`"[typescript]": {`
`10`	`10`	`"editor.defaultFormatter": "esbenp.prettier-vscode"`
`11`		`- }`
	`11`	`+ },`
	`12`	`+ "js/ts.tsdk.path": "node_modules/typescript/lib"`
`12`	`13`	`}`