@guidepup/playwright 0.13.0 → 0.13.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +46 -3
  2. package/lib/nvdaTest.js +21 -32
  3. package/lib/voiceOverTest.js +0 -2
  4. package/package.json +12 -9
package/README.md CHANGED
@@ -9,6 +9,7 @@
9
9
  [![MacOS Big Sur Support](https://img.shields.io/badge/macos-Big_Sur-blue.svg?logo=apple)](https://apps.apple.com/id/app/macos-big-sur/id1526878132)
10
10
  [![MacOS Monetary Support](https://img.shields.io/badge/macos-Monetary-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-monterey/id1576738294)
11
11
  [![MacOS Ventura Support](https://img.shields.io/badge/macos-Ventura-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-ventura/id1638787999)
12
+ [![MacOS Sonoma Support](https://img.shields.io/badge/macos-Somona-blue.svg?logo=apple)](https://apps.apple.com/us/app/macos-sonoma/id6450717509)
12
13
  [![Windows 10 Support](https://img.shields.io/badge/windows-10-blue.svg?logo=windows10)](https://www.microsoft.com/en-gb/software-download/windows10ISO)
13
14
  [![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)
14
15
  [![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)
@@ -71,9 +72,51 @@ const config: PlaywrightTestConfig = {
71
72
  export default config;
72
73
  ```
73
74
 
74
- Check out the configuration this adds [in the `config.ts`` file](./src/config.ts).
75
+ Check out the configuration this adds [in the `config.ts` file](./src/config.ts).
75
76
 
76
- ### VoiceOver
77
+ ### Web Content Navigation
78
+
79
+ In addition to the Guidepup APIs the `voiceOver` and `nvda` instances provided by the Guidepup Playwright setup have an additional utility method `.navigateToWebContent()`.
80
+
81
+ This method will navigate the screen reader to the first element of the document body in the browser.
82
+
83
+ Use this method after you navigate to a page and have made any necessary checks that the page has loaded as expected. For example, this is how you might use the method with NVDA:
84
+
85
+ ```ts
86
+ // Navigate to the desired page
87
+ await page.goto("https://github.com/guidepup/guidepup", {
88
+ waitUntil: "load",
89
+ });
90
+
91
+ // Wait for page to be ready
92
+ await page.locator('header[role="banner"]').waitFor();
93
+
94
+ // Navigate to the web content
95
+ await nvda.navigateToWebContent();
96
+
97
+ // ... some commands
98
+ ```
99
+
100
+ **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:
101
+
102
+ ```ts
103
+ // ... some commands
104
+
105
+ // Store spoken phrases
106
+ const spokenPhrases = await nvda.spokenPhraseLog();
107
+
108
+ // Navigate to the web content
109
+ await nvda.navigateToWebContent();
110
+
111
+ // ... some commands
112
+
113
+ // Collect all spoken phrasees
114
+ const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];
115
+
116
+ // ... do something with spoken phrases
117
+ ```
118
+
119
+ ### VoiceOver Example
77
120
 
78
121
  `playwright.config.ts`:
79
122
 
@@ -131,7 +174,7 @@ test.describe("Playwright VoiceOver", () => {
131
174
  });
132
175
  ```
133
176
 
134
- ### NVDA
177
+ ### NVDA Example
135
178
 
136
179
  `playwright.config.ts`:
137
180
 
package/lib/nvdaTest.js CHANGED
@@ -10,41 +10,23 @@ const SWITCH_APPLICATION = {
10
10
  keyCode: [guidepup_1.WindowsKeyCodes.Escape],
11
11
  modifiers: [guidepup_1.WindowsModifiers.Alt],
12
12
  };
13
- const focusBrowser = async ({ applicationName, page, }) => {
13
+ const MOVE_TO_TOP = {
14
+ keyCode: [guidepup_1.WindowsKeyCodes.Home],
15
+ modifiers: [guidepup_1.WindowsModifiers.Control],
16
+ };
17
+ const focusBrowser = async ({ applicationName, }) => {
14
18
  await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
15
19
  let windowTitle = await nvdaPlaywright.lastSpokenPhrase();
16
20
  if (windowTitle.includes(applicationName)) {
17
21
  return;
18
22
  }
19
- // Firefox has a bug with NVDA where NVDA gets stuck in focus mode if
20
- // Firefox is the currently focused application.
21
- // REF: https://github.com/nvaccess/nvda/issues/5758
22
- // We swap to a different application, restart NVDA, and then switch back.
23
23
  let applicationSwitchRetryCount = 0;
24
24
  while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
25
25
  applicationSwitchRetryCount++;
26
26
  await nvdaPlaywright.perform(SWITCH_APPLICATION);
27
27
  await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
28
28
  windowTitle = await nvdaPlaywright.lastSpokenPhrase();
29
- if (!windowTitle.includes(applicationName)) {
30
- break;
31
- }
32
- }
33
- await nvdaPlaywright.stop();
34
- await nvdaPlaywright.start();
35
- await page.bringToFront();
36
- await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
37
- windowTitle = await nvdaPlaywright.lastSpokenPhrase();
38
- if (windowTitle.includes(applicationName)) {
39
- return;
40
- }
41
- applicationSwitchRetryCount = 0;
42
- while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
43
- applicationSwitchRetryCount++;
44
- await nvdaPlaywright.perform(SWITCH_APPLICATION);
45
- await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
46
- windowTitle = await nvdaPlaywright.lastSpokenPhrase();
47
- if (!windowTitle.includes(applicationName)) {
29
+ if (windowTitle.includes(applicationName)) {
48
30
  break;
49
31
  }
50
32
  }
@@ -67,16 +49,23 @@ exports.nvdaTest = test_1.test.extend({
67
49
  nvdaPlaywright.navigateToWebContent = async () => {
68
50
  // Make sure NVDA is not in focus mode.
69
51
  await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
70
- await nvdaPlaywright.lastSpokenPhrase();
71
52
  // Ensure application is brought to front and focused.
72
- await focusBrowser({ applicationName, page });
73
- // Make sure NVDA is not in focus mode.
53
+ await focusBrowser({ applicationName });
54
+ // NVDA appears to not work well with Firefox when switching between
55
+ // applications resulting in the entire browser window having NVDA focus
56
+ // with focus mode.
57
+ //
58
+ // One workaround is to tab to the next focusable item. From there we can
59
+ // toggle into (yes although we are already in it...) focus mode and back
60
+ // out. In case this ever transpires to not happen as expect, we then ensure
61
+ // we exit focus mode and move NVDA to the top of the page.
62
+ //
63
+ // REF: https://github.com/nvaccess/nvda/issues/5758
64
+ await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.readNextFocusableItem);
65
+ await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode);
66
+ await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.toggleBetweenBrowseAndFocusMode);
74
67
  await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
75
- await nvdaPlaywright.lastSpokenPhrase();
76
- // Ensure the document is ready and focused.
77
- await page.bringToFront();
78
- await page.locator("body").waitFor();
79
- await page.locator("body").focus();
68
+ await nvdaPlaywright.perform(MOVE_TO_TOP);
80
69
  // Clear out logs.
81
70
  await nvdaPlaywright.clearItemTextLog();
82
71
  await nvdaPlaywright.clearSpokenPhraseLog();
package/lib/voiceOverTest.js CHANGED
@@ -27,9 +27,7 @@ exports.voiceOverTest = test_1.test.extend({
27
27
  await page.locator("body").focus();
28
28
  // Navigate to the beginning of the web content.
29
29
  await voiceOverPlaywright.interact();
30
- await voiceOverPlaywright.lastSpokenPhrase();
31
30
  await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.jumpToLeftEdge);
32
- await voiceOverPlaywright.lastSpokenPhrase();
33
31
  // Clear out logs.
34
32
  await voiceOverPlaywright.clearItemTextLog();
35
33
  await voiceOverPlaywright.clearSpokenPhraseLog();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guidepup/playwright",
3
- "version": "0.13.0",
3
+ "version": "0.13.2",
4
4
  "description": "Screen reader driver for Playwright tests.",
5
5
  "main": "lib/index.js",
6
6
  "typings": "lib/index.d.ts",
@@ -16,10 +16,13 @@
16
16
  "homepage": "https://github.com/guidepup/guidepup-playwright",
17
17
  "keywords": [
18
18
  "playwright",
19
+ "screen reader",
19
20
  "screen-reader",
20
21
  "accessibility",
21
22
  "a11y",
22
- "voiceover"
23
+ "voiceover",
24
+ "nvda",
25
+ "guidepup"
23
26
  ],
24
27
  "scripts": {
25
28
  "build": "yarn clean && yarn compile",
@@ -39,20 +42,20 @@
39
42
  "test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
40
43
  },
41
44
  "devDependencies": {
42
- "@guidepup/guidepup": "^0.22.0",
43
- "@playwright/test": "^1.40.1",
44
- "@types/node": "^20.10.6",
45
- "@typescript-eslint/eslint-plugin": "^6.18.0",
46
- "@typescript-eslint/parser": "^6.18.0",
45
+ "@guidepup/guidepup": "^0.22.1",
46
+ "@playwright/test": "^1.41.1",
47
+ "@types/node": "^20.11.15",
48
+ "@typescript-eslint/eslint-plugin": "^6.20.0",
49
+ "@typescript-eslint/parser": "^6.20.0",
47
50
  "eslint": "^8.56.0",
48
51
  "eslint-config-prettier": "^9.1.0",
49
52
  "rimraf": "^5.0.5",
50
53
  "ts-node": "^10.9.2",
51
- "typedoc": "^0.25.6",
54
+ "typedoc": "^0.25.7",
52
55
  "typescript": "^5.3.3"
53
56
  },
54
57
  "peerDependencies": {
55
- "@guidepup/guidepup": "^0.22.0",
58
+ "@guidepup/guidepup": "^0.22.1",
56
59
  "@playwright/test": "^1.40.1"
57
60
  },
58
61
  "resolutions": {