@guidepup/playwright 0.11.0 → 0.13.0
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.
- package/README.md +155 -71
- package/lib/applicationNameMap.d.ts +10 -0
- package/lib/applicationNameMap.js +13 -0
- package/lib/index.d.ts +5 -2
- package/lib/index.js +7 -5
- package/lib/nvdaTest.d.ts +65 -0
- package/lib/nvdaTest.js +96 -0
- package/lib/screenReaderConfig.d.ts +6 -0
- package/lib/screenReaderConfig.js +24 -0
- package/lib/voiceOverTest.d.ts +69 -0
- package/lib/voiceOverTest.js +50 -0
- package/package.json +21 -15
- package/lib/voConfig.d.ts +0 -6
- package/lib/voConfig.js +0 -20
- package/lib/voTest.d.ts +0 -11
- package/lib/voTest.js +0 -39
package/README.md
CHANGED
|
@@ -1,125 +1,209 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
<
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
</
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
A11y static analysis tools [only cover 25% of WCAG](https://karlgroves.com/web-accessibility-testing-what-can-be-tested-and-how/) and don't assure on the quality of the user experience for screen reader users. This means teams need to perform lots of manual tests with multiple screen readers to ensure great UX which can take a lot of time... **not anymore!**
|
|
24
|
-
|
|
25
|
-
With [Guidepup](https://www.guidepup.dev/) you can automate your screen reader test workflows the same you as would for mouse or keyboard based scenarios, no sweat!
|
|
26
|
-
|
|
27
|
-
## Quick Features
|
|
28
|
-
|
|
29
|
-
- **Full Control** - if a screen reader has a keyboard command, then Guidepup supports it.
|
|
30
|
-
- **Mirrors Real User Experience** - assert on what users really do and hear when using screen readers.
|
|
31
|
-
- **Framework Agnostic** - run with Jest, with Playwright, as an independent script, no vendor lock-in.
|
|
1
|
+
# Guidepup Playwright
|
|
2
|
+
|
|
3
|
+
<a href="https://www.npmjs.com/package/@guidepup/playwright"><img alt="@guidepup/playwright available on NPM" src="https://img.shields.io/npm/v/@guidepup/playwright" /></a>
|
|
4
|
+
<a href="https://github.com/guidepup/guidepup-playwright/actions/workflows/test.yml"><img alt="@guidepup/playwright test workflows" src="https://github.com/guidepup/guidepup-playwright/workflows/Test/badge.svg" /></a>
|
|
5
|
+
<a href="https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE"><img alt="@guidepup/playwright uses the MIT license" src="https://img.shields.io/github/license/guidepup/guidepup-playwright" /></a>
|
|
6
|
+
|
|
7
|
+
## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
|
|
8
|
+
|
|
9
|
+
[](https://apps.apple.com/id/app/macos-big-sur/id1526878132)
|
|
10
|
+
[](https://apps.apple.com/us/app/macos-monterey/id1576738294)
|
|
11
|
+
[](https://apps.apple.com/us/app/macos-ventura/id1638787999)
|
|
12
|
+
[](https://www.microsoft.com/en-gb/software-download/windows10ISO)
|
|
13
|
+
[](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2019)
|
|
14
|
+
[](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022)
|
|
15
|
+
|
|
16
|
+
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>.
|
|
17
|
+
|
|
18
|
+
## Capabilities
|
|
19
|
+
|
|
20
|
+
- **Full Control** - If a screen reader has a keyboard command, then Guidepup supports it.
|
|
21
|
+
- **Mirrors Real User Experience** - Assert on what users really do and hear when using screen readers.
|
|
22
|
+
- **Framework Agnostic** - Run with Jest, with Playwright, as an independent script, no vendor lock-in.
|
|
32
23
|
|
|
33
24
|
## Getting Started
|
|
34
25
|
|
|
35
26
|
Set up your environment for screen reader automation with [`@guidepup/setup`](https://github.com/guidepup/setup):
|
|
36
27
|
|
|
37
|
-
```
|
|
28
|
+
```sh
|
|
38
29
|
npx @guidepup/setup
|
|
39
30
|
```
|
|
40
31
|
|
|
32
|
+
If you are using GitHub Actions, check out the dedicated [`guidepup/setup-action`](https://github.com/marketplace/actions/guidepup-setup):
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
- name: Setup Environment
|
|
36
|
+
uses: guidepup/setup-action
|
|
37
|
+
```
|
|
38
|
+
|
|
41
39
|
Install `@guidepup/playwright` to your project:
|
|
42
40
|
|
|
43
|
-
```
|
|
44
|
-
npm install --save-dev @guidepup/playwright @playwright/test
|
|
41
|
+
```sh
|
|
42
|
+
npm install --save-dev @guidepup/playwright @guidepup/guidepup @playwright/test
|
|
45
43
|
```
|
|
46
44
|
|
|
45
|
+
Note: you require `@guidepup/guidepup` and `@playwright/test` as they are peer dependencies to this project.
|
|
46
|
+
|
|
47
47
|
And get cracking with your first screen reader tests in Playwright!
|
|
48
48
|
|
|
49
|
+
## Examples
|
|
50
|
+
|
|
51
|
+
Head over to the [Guidepup Website](https://www.guidepup.dev/) for guides, real world examples, environment setup, and complete API documentation with examples.
|
|
52
|
+
|
|
53
|
+
You can also check out these [awesome examples](https://github.com/guidepup/guidepup/tree/main/examples) to learn how you could use Guidepup with Playwright in your projects.
|
|
54
|
+
|
|
55
|
+
Alternatively check out [this project](https://github.com/guidepup/aria-at-tests) which runs several thousand tests to assert screen reader compatibility against [W3C ARIA-AT](https://github.com/w3c/aria-at) test suite.
|
|
56
|
+
|
|
57
|
+
### Playwright Config
|
|
58
|
+
|
|
59
|
+
In your `playwright.config.ts` add the following for the best results with Guidepup for Screen Reader automation:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import { devices, PlaywrightTestConfig } from "@playwright/test";
|
|
63
|
+
import { screenReaderConfig } from "@guidepup/playwright";
|
|
64
|
+
|
|
65
|
+
const config: PlaywrightTestConfig = {
|
|
66
|
+
...screenReaderConfig,
|
|
67
|
+
|
|
68
|
+
// ... your custom config
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
export default config;
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Check out the configuration this adds [in the `config.ts`` file](./src/config.ts).
|
|
75
|
+
|
|
76
|
+
### VoiceOver
|
|
77
|
+
|
|
78
|
+
`playwright.config.ts`:
|
|
79
|
+
|
|
49
80
|
```ts
|
|
50
|
-
import {
|
|
81
|
+
import { devices, PlaywrightTestConfig } from "@playwright/test";
|
|
82
|
+
import { screenReaderConfig } from "@guidepup/playwright";
|
|
83
|
+
|
|
84
|
+
const config: PlaywrightTestConfig = {
|
|
85
|
+
...screenReaderConfig,
|
|
86
|
+
reportSlowTests: null,
|
|
87
|
+
timeout: 5 * 60 * 1000,
|
|
88
|
+
retries: 2,
|
|
89
|
+
projects: [
|
|
90
|
+
{
|
|
91
|
+
name: "webkit",
|
|
92
|
+
use: { ...devices["Desktop Safari"], headless: false },
|
|
93
|
+
},
|
|
94
|
+
],
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
export default config;
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`voiceOver.spec.ts`:
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
import { voiceOverTest as test } from "@guidepup/playwright";
|
|
51
104
|
import { expect } from "@playwright/test";
|
|
52
105
|
|
|
53
106
|
test.describe("Playwright VoiceOver", () => {
|
|
54
|
-
test("I can navigate the Guidepup Github page", async ({
|
|
107
|
+
test("I can navigate the Guidepup Github page with VoiceOver", async ({
|
|
55
108
|
page,
|
|
56
109
|
voiceOver,
|
|
57
110
|
}) => {
|
|
58
111
|
// Navigate to Guidepup GitHub page
|
|
59
112
|
await page.goto("https://github.com/guidepup/guidepup", {
|
|
60
|
-
waitUntil: "
|
|
113
|
+
waitUntil: "load",
|
|
61
114
|
});
|
|
62
115
|
|
|
63
|
-
// Wait for page to be ready
|
|
64
|
-
|
|
65
|
-
await
|
|
116
|
+
// Wait for page to be ready
|
|
117
|
+
const header = page.locator('header[role="banner"]');
|
|
118
|
+
await header.waitFor();
|
|
119
|
+
|
|
120
|
+
// Interact with the page
|
|
121
|
+
await voiceOver.navigateToWebContent();
|
|
66
122
|
|
|
67
123
|
// Move across the page menu to the Guidepup heading using VoiceOver
|
|
68
124
|
while ((await voiceOver.itemText()) !== "Guidepup heading level 1") {
|
|
69
|
-
await voiceOver.perform(voiceOver.
|
|
125
|
+
await voiceOver.perform(voiceOver.keyboardCommands.findNextHeading);
|
|
70
126
|
}
|
|
127
|
+
|
|
128
|
+
// Assert that the spoken phrases are as expected
|
|
129
|
+
expect(JSON.stringify(await voiceOver.spokenPhraseLog())).toMatchSnapshot();
|
|
130
|
+
});
|
|
71
131
|
});
|
|
72
132
|
```
|
|
73
133
|
|
|
74
|
-
|
|
134
|
+
### NVDA
|
|
75
135
|
|
|
76
|
-
|
|
77
|
-
Guidepup for VoiceOver automation.
|
|
136
|
+
`playwright.config.ts`:
|
|
78
137
|
|
|
79
138
|
```ts
|
|
80
139
|
import { devices, PlaywrightTestConfig } from "@playwright/test";
|
|
81
|
-
import {
|
|
140
|
+
import { screenReaderConfig } from "@guidepup/playwright";
|
|
82
141
|
|
|
83
142
|
const config: PlaywrightTestConfig = {
|
|
84
|
-
...
|
|
85
|
-
|
|
86
|
-
|
|
143
|
+
...screenReaderConfig,
|
|
144
|
+
reportSlowTests: null,
|
|
145
|
+
timeout: 5 * 60 * 1000,
|
|
146
|
+
retries: 2,
|
|
147
|
+
projects: [
|
|
148
|
+
{
|
|
149
|
+
name: "firefox",
|
|
150
|
+
use: { ...devices["Desktop Firefox"], headless: false },
|
|
151
|
+
},
|
|
152
|
+
],
|
|
87
153
|
};
|
|
88
154
|
|
|
89
155
|
export default config;
|
|
90
156
|
```
|
|
91
157
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
## Environment Setup
|
|
158
|
+
`nvda.spec.ts`:
|
|
95
159
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
npx @guidepup/setup
|
|
100
|
-
```
|
|
160
|
+
```ts
|
|
161
|
+
import { nvdaTest as test } from "@guidepup/playwright";
|
|
162
|
+
import { expect } from "@playwright/test";
|
|
101
163
|
|
|
102
|
-
|
|
164
|
+
test.describe("Playwright NVDA", () => {
|
|
165
|
+
test("I can navigate the Guidepup Github page with NVDA", async ({
|
|
166
|
+
page,
|
|
167
|
+
nvda,
|
|
168
|
+
}) => {
|
|
169
|
+
// Navigate to Guidepup GitHub page
|
|
170
|
+
await page.goto("https://github.com/guidepup/guidepup", {
|
|
171
|
+
waitUntil: "load",
|
|
172
|
+
});
|
|
103
173
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
```
|
|
174
|
+
// Wait for page to be ready and setup
|
|
175
|
+
const header = page.locator('header[role="banner"]');
|
|
176
|
+
await header.waitFor();
|
|
108
177
|
|
|
109
|
-
|
|
178
|
+
// Interact with the page
|
|
179
|
+
await nvda.navigateToWebContent();
|
|
110
180
|
|
|
111
|
-
|
|
181
|
+
// Move across the page menu to the Guidepup heading using NVDA
|
|
182
|
+
while (
|
|
183
|
+
!(await nvda.lastSpokenPhrase()).includes("Guidepup, heading, level 1")
|
|
184
|
+
) {
|
|
185
|
+
await nvda.perform(nvda.keyboardCommands.moveToNextHeading);
|
|
186
|
+
}
|
|
112
187
|
|
|
113
|
-
|
|
188
|
+
// Assert that the spoken phrases are as expected
|
|
189
|
+
expect(JSON.stringify(await nvda.spokenPhraseLog())).toMatchSnapshot();
|
|
190
|
+
});
|
|
191
|
+
});
|
|
192
|
+
```
|
|
114
193
|
|
|
115
|
-
|
|
194
|
+
## Powerful Tooling
|
|
116
195
|
|
|
117
|
-
|
|
196
|
+
Check out some of the other Guidepup modules:
|
|
118
197
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
198
|
+
- [`@guidepup/guidepup`](https://github.com/guidepup/guidepup/) - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.
|
|
199
|
+
- [`@guidepup/setup`](https://github.com/guidepup/setup/) - Set up your local or CI environment for screen reader test automation.
|
|
200
|
+
- [`@guidepup/virtual-screen-reader`](https://github.com/guidepup/virtual-screen-reader/) - Reliable unit testing for your screen reader a11y workflows.
|
|
201
|
+
- [`@guidepup/jest`](https://github.com/guidepup/jest/) - Jest matchers for reliable unit testing of your screen reader a11y workflows.
|
|
122
202
|
|
|
123
|
-
##
|
|
203
|
+
## Resources
|
|
124
204
|
|
|
125
|
-
[
|
|
205
|
+
- [Documentation](https://www.guidepup.dev/docs/example)
|
|
206
|
+
- [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
|
|
207
|
+
- [Contributing](.github/CONTRIBUTING.md)
|
|
208
|
+
- [Changelog](https://github.com/guidepup/guidepup-playwright/releases)
|
|
209
|
+
- [MIT License](https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE)
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.applicationNameMap = void 0;
|
|
4
|
+
exports.applicationNameMap = {
|
|
5
|
+
chromium: "Chromium",
|
|
6
|
+
chrome: "Google Chrome",
|
|
7
|
+
"chrome-beta": "Google Chrome Beta",
|
|
8
|
+
msedge: "Microsoft Edge",
|
|
9
|
+
"msedge-beta": "Microsoft Edge Beta",
|
|
10
|
+
"msedge-dev": "Microsoft Edge Dev",
|
|
11
|
+
firefox: "Nightly",
|
|
12
|
+
webkit: "Playwright",
|
|
13
|
+
};
|
package/lib/index.d.ts
CHANGED
|
@@ -1,2 +1,5 @@
|
|
|
1
|
-
export {
|
|
2
|
-
export {
|
|
1
|
+
export { nvdaTest } from "./nvdaTest";
|
|
2
|
+
export type { NVDAPlaywright } from "./nvdaTest";
|
|
3
|
+
export { screenReaderConfig } from "./screenReaderConfig";
|
|
4
|
+
export { voiceOverTest } from "./voiceOverTest";
|
|
5
|
+
export type { VoiceOverPlaywright } from "./voiceOverTest";
|
package/lib/index.js
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.
|
|
4
|
-
var
|
|
5
|
-
Object.defineProperty(exports, "
|
|
6
|
-
var
|
|
7
|
-
Object.defineProperty(exports, "
|
|
3
|
+
exports.voiceOverTest = exports.screenReaderConfig = exports.nvdaTest = void 0;
|
|
4
|
+
var nvdaTest_1 = require("./nvdaTest");
|
|
5
|
+
Object.defineProperty(exports, "nvdaTest", { enumerable: true, get: function () { return nvdaTest_1.nvdaTest; } });
|
|
6
|
+
var screenReaderConfig_1 = require("./screenReaderConfig");
|
|
7
|
+
Object.defineProperty(exports, "screenReaderConfig", { enumerable: true, get: function () { return screenReaderConfig_1.screenReaderConfig; } });
|
|
8
|
+
var voiceOverTest_1 = require("./voiceOverTest");
|
|
9
|
+
Object.defineProperty(exports, "voiceOverTest", { enumerable: true, get: function () { return voiceOverTest_1.voiceOverTest; } });
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import type { NVDA } from "@guidepup/guidepup";
|
|
2
|
+
/**
|
|
3
|
+
* [API Reference](https://www.guidepup.dev/docs/api/class-nvda)
|
|
4
|
+
*
|
|
5
|
+
* This object can be used to launch and control NVDA.
|
|
6
|
+
*
|
|
7
|
+
* Here's a typical example:
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { nvda } from "@guidepup/guidepup";
|
|
11
|
+
*
|
|
12
|
+
* (async () => {
|
|
13
|
+
* // Start NVDA.
|
|
14
|
+
* await nvda.start();
|
|
15
|
+
*
|
|
16
|
+
* // Move to the next item.
|
|
17
|
+
* await nvda.next();
|
|
18
|
+
*
|
|
19
|
+
* // Stop NVDA.
|
|
20
|
+
* await nvda.stop();
|
|
21
|
+
* })();
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
export interface NVDAPlaywright extends NVDA {
|
|
25
|
+
/**
|
|
26
|
+
* Guidepup Playwright specific command that navigates NVDA to the beginning
|
|
27
|
+
* of the browser's web content.
|
|
28
|
+
*
|
|
29
|
+
* This command should be used after page navigation.
|
|
30
|
+
*
|
|
31
|
+
* Note: this command clears all logs.
|
|
32
|
+
*/
|
|
33
|
+
navigateToWebContent(): Promise<void>;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* These tests extend the default Playwright environment that launches the
|
|
37
|
+
* browser with a running instance of the NVDA screen reader for Windows.
|
|
38
|
+
*
|
|
39
|
+
* A fresh started NVDA instance `nvda` is provided to each test.
|
|
40
|
+
*/
|
|
41
|
+
export declare const nvdaTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
|
|
42
|
+
/**
|
|
43
|
+
* [API Reference](https://www.guidepup.dev/docs/api/class-nvda)
|
|
44
|
+
*
|
|
45
|
+
* This object can be used to launch and control NVDA.
|
|
46
|
+
*
|
|
47
|
+
* Here's a typical example:
|
|
48
|
+
*
|
|
49
|
+
* ```ts
|
|
50
|
+
* import { nvda } from "@guidepup/guidepup";
|
|
51
|
+
*
|
|
52
|
+
* (async () => {
|
|
53
|
+
* // Start NVDA.
|
|
54
|
+
* await nvda.start();
|
|
55
|
+
*
|
|
56
|
+
* // Move to the next item.
|
|
57
|
+
* await nvda.next();
|
|
58
|
+
*
|
|
59
|
+
* // Stop NVDA.
|
|
60
|
+
* await nvda.stop();
|
|
61
|
+
* })();
|
|
62
|
+
* ```
|
|
63
|
+
*/
|
|
64
|
+
nvda: NVDAPlaywright;
|
|
65
|
+
}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
|
package/lib/nvdaTest.js
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.nvdaTest = void 0;
|
|
4
|
+
const test_1 = require("@playwright/test");
|
|
5
|
+
const guidepup_1 = require("@guidepup/guidepup");
|
|
6
|
+
const applicationNameMap_1 = require("./applicationNameMap");
|
|
7
|
+
const nvdaPlaywright = guidepup_1.nvda;
|
|
8
|
+
const MAX_APPLICATION_SWITCH_RETRY_COUNT = 10;
|
|
9
|
+
const SWITCH_APPLICATION = {
|
|
10
|
+
keyCode: [guidepup_1.WindowsKeyCodes.Escape],
|
|
11
|
+
modifiers: [guidepup_1.WindowsModifiers.Alt],
|
|
12
|
+
};
|
|
13
|
+
const focusBrowser = async ({ applicationName, page, }) => {
|
|
14
|
+
await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
|
|
15
|
+
let windowTitle = await nvdaPlaywright.lastSpokenPhrase();
|
|
16
|
+
if (windowTitle.includes(applicationName)) {
|
|
17
|
+
return;
|
|
18
|
+
}
|
|
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
|
+
let applicationSwitchRetryCount = 0;
|
|
24
|
+
while (applicationSwitchRetryCount < MAX_APPLICATION_SWITCH_RETRY_COUNT) {
|
|
25
|
+
applicationSwitchRetryCount++;
|
|
26
|
+
await nvdaPlaywright.perform(SWITCH_APPLICATION);
|
|
27
|
+
await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.reportTitle);
|
|
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)) {
|
|
48
|
+
break;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* These tests extend the default Playwright environment that launches the
|
|
54
|
+
* browser with a running instance of the NVDA screen reader for Windows.
|
|
55
|
+
*
|
|
56
|
+
* A fresh started NVDA instance `nvda` is provided to each test.
|
|
57
|
+
*/
|
|
58
|
+
exports.nvdaTest = test_1.test.extend({
|
|
59
|
+
nvda: async ({ browserName, page }, use) => {
|
|
60
|
+
try {
|
|
61
|
+
const applicationName = applicationNameMap_1.applicationNameMap[browserName];
|
|
62
|
+
if (!applicationName) {
|
|
63
|
+
throw new Error(`Browser ${browserName} is not installed.`);
|
|
64
|
+
}
|
|
65
|
+
await page.goto("about:blank", { waitUntil: "load" });
|
|
66
|
+
await page.bringToFront();
|
|
67
|
+
nvdaPlaywright.navigateToWebContent = async () => {
|
|
68
|
+
// Make sure NVDA is not in focus mode.
|
|
69
|
+
await nvdaPlaywright.perform(nvdaPlaywright.keyboardCommands.exitFocusMode);
|
|
70
|
+
await nvdaPlaywright.lastSpokenPhrase();
|
|
71
|
+
// Ensure application is brought to front and focused.
|
|
72
|
+
await focusBrowser({ applicationName, page });
|
|
73
|
+
// Make sure NVDA is not in focus mode.
|
|
74
|
+
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();
|
|
80
|
+
// Clear out logs.
|
|
81
|
+
await nvdaPlaywright.clearItemTextLog();
|
|
82
|
+
await nvdaPlaywright.clearSpokenPhraseLog();
|
|
83
|
+
};
|
|
84
|
+
await nvdaPlaywright.start();
|
|
85
|
+
await use(nvdaPlaywright);
|
|
86
|
+
}
|
|
87
|
+
finally {
|
|
88
|
+
try {
|
|
89
|
+
await nvdaPlaywright.stop();
|
|
90
|
+
}
|
|
91
|
+
catch {
|
|
92
|
+
// swallow stop failure
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
});
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { PlaywrightTestConfig } from "@playwright/test";
|
|
2
|
+
export type ScreenReaderPlaywrightTestConfig = PlaywrightTestConfig;
|
|
3
|
+
/**
|
|
4
|
+
* Minimal required configuration for Screen Reader tests in Playwright.
|
|
5
|
+
*/
|
|
6
|
+
export declare const screenReaderConfig: ScreenReaderPlaywrightTestConfig;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.screenReaderConfig = void 0;
|
|
4
|
+
/**
|
|
5
|
+
* Minimal required configuration for Screen Reader tests in Playwright.
|
|
6
|
+
*/
|
|
7
|
+
exports.screenReaderConfig = {
|
|
8
|
+
/**
|
|
9
|
+
* We can only run a single instance of Screen Readers, so we must run a
|
|
10
|
+
* single test at a time.
|
|
11
|
+
*/
|
|
12
|
+
workers: 1,
|
|
13
|
+
/**
|
|
14
|
+
* We can't parallelize Screen Reader tests as they are singletons, you can't
|
|
15
|
+
* start multiple instances at once.
|
|
16
|
+
*/
|
|
17
|
+
fullyParallel: false,
|
|
18
|
+
use: {
|
|
19
|
+
/**
|
|
20
|
+
* Screen Readers don't work against headless browsers.
|
|
21
|
+
*/
|
|
22
|
+
headless: false,
|
|
23
|
+
},
|
|
24
|
+
};
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import type { VoiceOver } from "@guidepup/guidepup";
|
|
2
|
+
/**
|
|
3
|
+
* [API Reference](https://www.guidepup.dev/docs/api/class-voiceover)
|
|
4
|
+
*
|
|
5
|
+
* This object can be used to launch and control VoiceOver.
|
|
6
|
+
*
|
|
7
|
+
* Here's a typical example:
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { voiceOver } from "@guidepup/guidepup";
|
|
11
|
+
*
|
|
12
|
+
* (async () => {
|
|
13
|
+
* // Start VoiceOver.
|
|
14
|
+
* await voiceOver.start();
|
|
15
|
+
*
|
|
16
|
+
* // Move to the next item.
|
|
17
|
+
* await voiceOver.next();
|
|
18
|
+
*
|
|
19
|
+
* // ... perform some commands.
|
|
20
|
+
*
|
|
21
|
+
* // Stop VoiceOver.
|
|
22
|
+
* await voiceOver.stop();
|
|
23
|
+
* })();
|
|
24
|
+
* ```
|
|
25
|
+
*/
|
|
26
|
+
export interface VoiceOverPlaywright extends VoiceOver {
|
|
27
|
+
/**
|
|
28
|
+
* Guidepup Playwright specific command that navigates VoiceOver to the beginning
|
|
29
|
+
* of the browser's web content.
|
|
30
|
+
*
|
|
31
|
+
* This command should be used after page navigation.
|
|
32
|
+
*
|
|
33
|
+
* Note: this command clears all logs.
|
|
34
|
+
*/
|
|
35
|
+
navigateToWebContent(): Promise<void>;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* These tests extend the default Playwright environment that launches the
|
|
39
|
+
* browser with a running instance of the VoiceOver screen reader for MacOS.
|
|
40
|
+
*
|
|
41
|
+
* A fresh started VoiceOver instance `voiceOver` is provided to each test.
|
|
42
|
+
*/
|
|
43
|
+
export declare const voiceOverTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
|
|
44
|
+
/**
|
|
45
|
+
* [API Reference](https://www.guidepup.dev/docs/api/class-voiceover)
|
|
46
|
+
*
|
|
47
|
+
* This object can be used to launch and control VoiceOver.
|
|
48
|
+
*
|
|
49
|
+
* Here's a typical example:
|
|
50
|
+
*
|
|
51
|
+
* ```ts
|
|
52
|
+
* import { voiceOver } from "@guidepup/guidepup";
|
|
53
|
+
*
|
|
54
|
+
* (async () => {
|
|
55
|
+
* // Start VoiceOver.
|
|
56
|
+
* await voiceOver.start();
|
|
57
|
+
*
|
|
58
|
+
* // Move to the next item.
|
|
59
|
+
* await voiceOver.next();
|
|
60
|
+
*
|
|
61
|
+
* // ... perform some commands.
|
|
62
|
+
*
|
|
63
|
+
* // Stop VoiceOver.
|
|
64
|
+
* await voiceOver.stop();
|
|
65
|
+
* })();
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
voiceOver: VoiceOverPlaywright;
|
|
69
|
+
}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.voiceOverTest = void 0;
|
|
4
|
+
const test_1 = require("@playwright/test");
|
|
5
|
+
const guidepup_1 = require("@guidepup/guidepup");
|
|
6
|
+
const applicationNameMap_1 = require("./applicationNameMap");
|
|
7
|
+
const voiceOverPlaywright = guidepup_1.voiceOver;
|
|
8
|
+
/**
|
|
9
|
+
* These tests extend the default Playwright environment that launches the
|
|
10
|
+
* browser with a running instance of the VoiceOver screen reader for MacOS.
|
|
11
|
+
*
|
|
12
|
+
* A fresh started VoiceOver instance `voiceOver` is provided to each test.
|
|
13
|
+
*/
|
|
14
|
+
exports.voiceOverTest = test_1.test.extend({
|
|
15
|
+
voiceOver: async ({ browserName, page }, use) => {
|
|
16
|
+
try {
|
|
17
|
+
const applicationName = applicationNameMap_1.applicationNameMap[browserName];
|
|
18
|
+
if (!applicationName) {
|
|
19
|
+
throw new Error(`Browser ${browserName} is not installed.`);
|
|
20
|
+
}
|
|
21
|
+
voiceOverPlaywright.navigateToWebContent = async () => {
|
|
22
|
+
// Ensure application is brought to front and focused.
|
|
23
|
+
await (0, guidepup_1.macOSActivate)(applicationName);
|
|
24
|
+
// Ensure the document is ready and focused.
|
|
25
|
+
await page.bringToFront();
|
|
26
|
+
await page.locator("body").waitFor();
|
|
27
|
+
await page.locator("body").focus();
|
|
28
|
+
// Navigate to the beginning of the web content.
|
|
29
|
+
await voiceOverPlaywright.interact();
|
|
30
|
+
await voiceOverPlaywright.lastSpokenPhrase();
|
|
31
|
+
await voiceOverPlaywright.perform(voiceOverPlaywright.keyboardCommands.jumpToLeftEdge);
|
|
32
|
+
await voiceOverPlaywright.lastSpokenPhrase();
|
|
33
|
+
// Clear out logs.
|
|
34
|
+
await voiceOverPlaywright.clearItemTextLog();
|
|
35
|
+
await voiceOverPlaywright.clearSpokenPhraseLog();
|
|
36
|
+
};
|
|
37
|
+
await voiceOverPlaywright.start();
|
|
38
|
+
await (0, guidepup_1.macOSActivate)(applicationName);
|
|
39
|
+
await use(voiceOverPlaywright);
|
|
40
|
+
}
|
|
41
|
+
finally {
|
|
42
|
+
try {
|
|
43
|
+
await voiceOverPlaywright.stop();
|
|
44
|
+
}
|
|
45
|
+
catch {
|
|
46
|
+
// swallow stop failure
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guidepup/playwright",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.0",
|
|
4
4
|
"description": "Screen reader driver for Playwright tests.",
|
|
5
5
|
"main": "lib/index.js",
|
|
6
6
|
"typings": "lib/index.d.ts",
|
|
@@ -24,33 +24,39 @@
|
|
|
24
24
|
"scripts": {
|
|
25
25
|
"build": "yarn clean && yarn compile",
|
|
26
26
|
"ci": "yarn clean && yarn lint && yarn build",
|
|
27
|
-
"clean": "rimraf lib",
|
|
27
|
+
"clean": "rimraf lib test-results recordings",
|
|
28
28
|
"compile": "tsc",
|
|
29
29
|
"lint": "eslint . --ext .ts",
|
|
30
30
|
"lint:fix": "yarn lint --fix",
|
|
31
31
|
"prepublish": "yarn build",
|
|
32
32
|
"pretest": "npx playwright install chromium firefox webkit",
|
|
33
|
-
"test": "yarn test:chromium && yarn test:firefox
|
|
34
|
-
"test:
|
|
35
|
-
"test:
|
|
36
|
-
"test:
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
"
|
|
33
|
+
"test:nvda": "yarn test:nvda:chromium && yarn test:nvda:firefox",
|
|
34
|
+
"test:voiceover": "yarn test:voiceover:chromium && yarn test:voiceover:firefox && yarn test:voiceover:webkit",
|
|
35
|
+
"test:nvda:chromium": "playwright test --config ./examples/playwright-nvda/chromium.config.ts ./examples/playwright-nvda/tests/chromium/",
|
|
36
|
+
"test:nvda:firefox": "playwright test --config ./examples/playwright-nvda/firefox.config.ts ./examples/playwright-nvda/tests/firefox/",
|
|
37
|
+
"test:voiceover:chromium": "playwright test --config ./examples/playwright-voiceover/chromium.config.ts ./examples/playwright-voiceover/tests/chromium/",
|
|
38
|
+
"test:voiceover:firefox": "playwright test --config ./examples/playwright-voiceover/firefox.config.ts ./examples/playwright-voiceover/tests/firefox/",
|
|
39
|
+
"test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
|
+
"@guidepup/guidepup": "^0.22.0",
|
|
42
43
|
"@playwright/test": "^1.40.1",
|
|
43
|
-
"@types/node": "^20.10.
|
|
44
|
-
"@typescript-eslint/eslint-plugin": "^6.
|
|
45
|
-
"@typescript-eslint/parser": "^6.
|
|
46
|
-
"eslint": "^8.
|
|
44
|
+
"@types/node": "^20.10.6",
|
|
45
|
+
"@typescript-eslint/eslint-plugin": "^6.18.0",
|
|
46
|
+
"@typescript-eslint/parser": "^6.18.0",
|
|
47
|
+
"eslint": "^8.56.0",
|
|
47
48
|
"eslint-config-prettier": "^9.1.0",
|
|
48
49
|
"rimraf": "^5.0.5",
|
|
49
50
|
"ts-node": "^10.9.2",
|
|
50
|
-
"typedoc": "^0.25.
|
|
51
|
+
"typedoc": "^0.25.6",
|
|
51
52
|
"typescript": "^5.3.3"
|
|
52
53
|
},
|
|
53
54
|
"peerDependencies": {
|
|
54
|
-
"@
|
|
55
|
+
"@guidepup/guidepup": "^0.22.0",
|
|
56
|
+
"@playwright/test": "^1.40.1"
|
|
57
|
+
},
|
|
58
|
+
"resolutions": {
|
|
59
|
+
"strip-ansi": "6.0.1",
|
|
60
|
+
"string-width": "4.1.0"
|
|
55
61
|
}
|
|
56
62
|
}
|
package/lib/voConfig.d.ts
DELETED
package/lib/voConfig.js
DELETED
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.voConfig = void 0;
|
|
4
|
-
/**
|
|
5
|
-
* Minimal required configuration for VoiceOver tests in Playwright.
|
|
6
|
-
*/
|
|
7
|
-
exports.voConfig = {
|
|
8
|
-
/**
|
|
9
|
-
* We can only run a single instance of VoiceOver, so we must run a single
|
|
10
|
-
* test at a time.
|
|
11
|
-
*/
|
|
12
|
-
workers: 1,
|
|
13
|
-
use: {
|
|
14
|
-
/**
|
|
15
|
-
* Although VoiceOver can interact with headless applications, not all
|
|
16
|
-
* behaviours work as expected.
|
|
17
|
-
*/
|
|
18
|
-
headless: false,
|
|
19
|
-
},
|
|
20
|
-
};
|
package/lib/voTest.d.ts
DELETED
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
import type { VoiceOver } from "@guidepup/guidepup";
|
|
2
|
-
/**
|
|
3
|
-
* These tests extend the default Playwright environment that launches the
|
|
4
|
-
* browser with a running instance of the VoiceOver screen reader for MacOS.
|
|
5
|
-
*
|
|
6
|
-
* A fresh started VoiceOver instance `vo` is provided to each test.
|
|
7
|
-
*/
|
|
8
|
-
declare const voTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
|
|
9
|
-
voiceOver: VoiceOver;
|
|
10
|
-
}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
|
|
11
|
-
export { voTest };
|
package/lib/voTest.js
DELETED
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.voTest = void 0;
|
|
4
|
-
const test_1 = require("@playwright/test");
|
|
5
|
-
const guidepup_1 = require("@guidepup/guidepup");
|
|
6
|
-
const applicationNameMap = {
|
|
7
|
-
chromium: "Chromium",
|
|
8
|
-
chrome: "Google Chrome",
|
|
9
|
-
"chrome-beta": "Google Chrome Beta",
|
|
10
|
-
msedge: "Microsoft Edge",
|
|
11
|
-
"msedge-beta": "Microsoft Edge Beta",
|
|
12
|
-
"msedge-dev": "Microsoft Edge Dev",
|
|
13
|
-
firefox: "Nightly",
|
|
14
|
-
webkit: "Playwright",
|
|
15
|
-
};
|
|
16
|
-
/**
|
|
17
|
-
* These tests extend the default Playwright environment that launches the
|
|
18
|
-
* browser with a running instance of the VoiceOver screen reader for MacOS.
|
|
19
|
-
*
|
|
20
|
-
* A fresh started VoiceOver instance `vo` is provided to each test.
|
|
21
|
-
*/
|
|
22
|
-
const voTest = test_1.test.extend({
|
|
23
|
-
voiceOver: async ({ browserName }, use) => {
|
|
24
|
-
try {
|
|
25
|
-
await guidepup_1.voiceOver.start();
|
|
26
|
-
await (0, guidepup_1.macOSActivate)(applicationNameMap[browserName]);
|
|
27
|
-
await use(guidepup_1.voiceOver);
|
|
28
|
-
}
|
|
29
|
-
finally {
|
|
30
|
-
try {
|
|
31
|
-
await guidepup_1.voiceOver.stop();
|
|
32
|
-
}
|
|
33
|
-
catch {
|
|
34
|
-
// swallow stop failure
|
|
35
|
-
}
|
|
36
|
-
}
|
|
37
|
-
},
|
|
38
|
-
});
|
|
39
|
-
exports.voTest = voTest;
|