├── .github └── workflows │ └── build.yml ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── assets ├── web-test-runner-voiceover.mp4 └── web-test-runner-voiceover.png ├── package-lock.json ├── package.json ├── src ├── browser │ └── index.ts ├── commands.ts ├── index.ts ├── test-one.spec.ts ├── test-three.spec.ts ├── test-two.spec.ts ├── types.d.ts └── voiceover │ ├── dom.ts │ ├── index.ts │ ├── settings.ts │ ├── system.ts │ └── utils.ts ├── tsconfig.json ├── tsconfig.lib.json └── web-test-runner.config.mjs /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: Build 2 | on: 3 | push: 4 | branches: 5 | - main 6 | 7 | jobs: 8 | build: 9 | runs-on: macos-latest 10 | strategy: 11 | matrix: 12 | node-version: [14.x] 13 | 14 | steps: 15 | - uses: actions/checkout@v1 16 | 17 | - name: Node ${{ matrix.node-version }} 18 | uses: actions/setup-node@v1 19 | with: 20 | node-version: ${{ matrix.node-version }} 21 | - name: npm ci and npm run ci 22 | run: | 23 | npm ci 24 | npm run ci -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | 9 | # Diagnostic reports (https://nodejs.org/api/report.html) 10 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 11 | 12 | # Runtime data 13 | pids 14 | *.pid 15 | *.seed 16 | *.pid.lock 17 | 18 | # Directory for instrumented libs generated by jscoverage/JSCover 19 | lib-cov 20 | 21 | # Coverage directory used by tools like istanbul 22 | coverage 23 | *.lcov 24 | 25 | # nyc test coverage 26 | .nyc_output 27 | 28 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 29 | .grunt 30 | 31 | # Bower dependency directory (https://bower.io/) 32 | bower_components 33 | 34 | # node-waf configuration 35 | .lock-wscript 36 | 37 | # Compiled binary addons (https://nodejs.org/api/addons.html) 38 | build/Release 39 | 40 | # Dependency directories 41 | node_modules/ 42 | jspm_packages/ 43 | 44 | # TypeScript v1 declaration files 45 | typings/ 46 | 47 | # TypeScript cache 48 | *.tsbuildinfo 49 | 50 | # Optional npm cache directory 51 | .npm 52 | 53 | # Optional eslint cache 54 | .eslintcache 55 | 56 | # Microbundle cache 57 | .rpt2_cache/ 58 | .rts2_cache_cjs/ 59 | .rts2_cache_es/ 60 | .rts2_cache_umd/ 61 | 62 | # Optional REPL history 63 | .node_repl_history 64 | 65 | # Output of 'npm pack' 66 | *.tgz 67 | 68 | # Yarn Integrity file 69 | .yarn-integrity 70 | 71 | # dotenv environment variables file 72 | .env 73 | .env.test 74 | 75 | # parcel-bundler cache (https://parceljs.org/) 76 | .cache 77 | 78 | # Next.js build output 79 | .next 80 | 81 | # Nuxt.js build / generate output 82 | .nuxt 83 | dist 84 | 85 | # Gatsby files 86 | .cache/ 87 | # Comment in the public line in if your project uses Gatsby and *not* Next.js 88 | # https://nextjs.org/blog/next-9-1#public-directory-support 89 | # public 90 | 91 | # vuepress build output 92 | .vuepress/dist 93 | 94 | # Serverless directories 95 | .serverless/ 96 | 97 | # FuseBox cache 98 | .fusebox/ 99 | 100 | # DynamoDB Local files 101 | .dynamodb/ 102 | 103 | # TernJS port file 104 | .tern-port 105 | 106 | dist -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 0.0.7 4 | - update `@playwright/test` for MacOS Monterey support 5 | - ensure close and reset of VO settings on test completion 6 | 7 | ## 0.0.6 8 | - retry/await on phrases 9 | - improved restart/permissions boot 10 | - overal improved test speed ~30% 11 | 12 | ## 0.0.4 13 | - improve interaction timing, reducing overal virtual cursor time and more accurate 14 | interaction delays. 15 | - Ensure to close Voice Over Utilities before reopening for settings validation. -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Cory Rylan 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # web-test-runner-voiceover 2 | 3 | [![npm version](https://badge.fury.io/js/web-test-runner-voiceover.svg)](https://badge.fury.io/js/web-test-runner-voiceover) ![CI Build](https://github.com/coryrylan/web-test-runner-voiceover/actions/workflows/build.yml/badge.svg) 4 | 5 | The Web Test Runner Voiceover provides plugins for [@web/test-runner](https://modern-web.dev/docs/test-runner/overview/) to automate Voiceover Screen reader testing. 6 | 7 | ![Web Test Runner Voiceover Example](https://github.com/coryrylan/web-test-runner-voiceover/blob/main/assets/web-test-runner-voiceover.png) 8 | 9 | ### Alternatives 10 | 11 | Not using `@web/test-runner`? No worries! There is another great VoiceOver testing tool available called [auto-vo](https://github.com/ckundo/auto-vo). This tool enables similar VoiceOver testing as `web-test-runner-voiceover` but is optimized for content-based sites and works stand alone without requiring using `@web/test-runner`. 12 | 13 | ## Setup 14 | 15 | Below you can find a minimal setup. To use `web-test-runner-voiceover` create a standalone test runner separate from your standard test runner config. Tests should be run independent of other tests and only run one test and browser at a time for the most accurate results. 16 | 17 | ```javascript 18 | // web-test-runner.voiceover.mjs 19 | import { playwrightLauncher } from '@web/test-runner-playwright'; 20 | import { esbuildPlugin } from '@web/dev-server-esbuild'; 21 | import { fromRollup } from '@web/dev-server-rollup'; 22 | import alias from '@rollup/plugin-alias'; 23 | import { voiceOverPlugin } from 'web-test-runner-voiceover'; 24 | 25 | export default /** @type {import("@web/test-runner").TestRunnerConfig} */ ({ 26 | concurrency: 1, 27 | concurrentBrowsers: 1, 28 | files: ['./src/**/*.spec.ts'], 29 | testsFinishTimeout: 60000, 30 | testFramework: { 31 | config: { timeout: '60000' } 32 | }, 33 | browsers: [playwrightLauncher({ product: 'webkit', launchOptions: { headless: false } })], 34 | nodeResolve: true, 35 | dedupe: true, 36 | plugins: [ 37 | voiceOverPlugin(), 38 | fromRollup(alias)({ 39 | entries: [{ find: /^my-cool-library/, replacement: `${process.cwd()}/dist` }], 40 | }), 41 | esbuildPlugin({ ts: true, json: true, target: 'auto', sourceMap: true }) 42 | ] 43 | }); 44 | ``` 45 | 46 | ## Permissions 47 | 48 | To run the tests certain permissions must be enabled. The first time running tests you will asked to allow permissions for `Terminal` to run have `Assistive Access` and to allow VoiceOver to be controlled by `AppleScript`. 49 | Allow both of these permissions. Once allowed you should not be asked again to enable. 50 | 51 | If you need to re-enable/disable 52 | you can find `Assistive Access` under `System Preferences` > `Security & Privacy` > `Accessibility`. Re-enabling `AppleScript` can be found in the `VoiceOver Utilities` app. 53 | 54 | The plugin will adjust VoiceOver preferences for optimal testing speed. The tests should **not** run in a headless browser. For optimal support for Mac users use the `webkit` option. 55 | 56 | ## Tests 57 | 58 | ```javascript 59 | import { expect } from '@esm-bundle/chai'; 60 | import { VoiceOverTest, Commands } from 'web-test-runner-voiceover/browser'; 61 | 62 | describe('should enable voice over tests with inputs', () => { 63 | let element: HTMLElement; 64 | 65 | beforeEach(async () => { 66 | element = document.createElement('div'); 67 | element.innerHTML = ` 68 | 69 | 70 | `; 71 | document.body.appendChild(element); 72 | }); 73 | 74 | afterEach(() => element.remove()); 75 | 76 | it('should read inputs', async () => { 77 | const test = new VoiceOverTest(); 78 | test.queue(Commands.right, 'first name edit text'); 79 | test.queue(Commands.right, 'last name edit text'); 80 | test.queue(Commands.left, 'first name edit text'); 81 | const result = await test.run(); 82 | expect(result.values).to.eql(result.expected); 83 | }); 84 | }); 85 | ``` 86 | 87 | The various commands available can be found [here](https://github.com/coryrylan/web-test-runner-voiceover/blob/main/src/commands.ts). 88 | Currently Github Action CI support is not available due to permission issues. To run tests locally and skip Github CI during a build a check can be added befor executing the tests. 89 | 90 | ```json 91 | // package.json 92 | "scripts": { 93 | "test": "node -e 'if (!process.env.GITHUB_ACTION)process.exit(1)' || web-test-runner", 94 | }, 95 | ``` -------------------------------------------------------------------------------- /assets/web-test-runner-voiceover.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/blueprintui/web-test-runner-voiceover/34665b99e1bcca37e6c234ae9ff8f0a1f874b7ae/assets/web-test-runner-voiceover.mp4 -------------------------------------------------------------------------------- /assets/web-test-runner-voiceover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/blueprintui/web-test-runner-voiceover/34665b99e1bcca37e6c234ae9ff8f0a1f874b7ae/assets/web-test-runner-voiceover.png -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "web-test-runner-voiceover", 3 | "version": "0.0.7", 4 | "description": "", 5 | "main": "./index.js", 6 | "module": "./index.js", 7 | "typings": "./index.d.ts", 8 | "type": "module", 9 | "files": [ 10 | "*" 11 | ], 12 | "scripts": { 13 | "ci": "npm run clean && npm run build && npm run test", 14 | "start": "web-dev-server --open demo/ --node-resolve --watch", 15 | "clean": "del ./dist", 16 | "test": "web-test-runner", 17 | "build": "tsc --project ./tsconfig.lib.json && cpy ./package.json dist/ && cpy ./README.md dist/", 18 | "build:watch": "tsc --watch --project ./tsconfig.lib.json" 19 | }, 20 | "repository": { 21 | "type": "git", 22 | "url": "git+https://github.com/coryrylan/web-test-runner-voiceover.git" 23 | }, 24 | "author": "Cory Rylan", 25 | "license": "MIT", 26 | "bugs": { 27 | "url": "https://github.com/coryrylan/web-test-runner-voiceover/issues" 28 | }, 29 | "homepage": "https://github.com/coryrylan/web-test-runner-voiceover#readme", 30 | "devDependencies": { 31 | "@esm-bundle/chai": "^4.3.4-fix.0", 32 | "cpy-cli": "^3.1.1", 33 | "del-cli": "^4.0.1", 34 | "typescript": "^4.5.2" 35 | }, 36 | "dependencies": { 37 | "@jxa/global-type": "^1.3.4", 38 | "@jxa/run": "^1.3.4", 39 | "@playwright/test": "1.18.0-alpha-dec-2-2021", 40 | "@rollup/plugin-alias": "^3.1.8", 41 | "@web/dev-server-esbuild": "^0.2.16", 42 | "@web/dev-server-rollup": "^0.3.13", 43 | "@web/test-runner": "^0.13.22", 44 | "@web/test-runner-commands": "^0.5.13", 45 | "@web/test-runner-playwright": "^0.8.8", 46 | "node-osascript": "^2.1.0", 47 | "tslib": "^2.3.1" 48 | } 49 | } 50 | -------------------------------------------------------------------------------- /src/browser/index.ts: -------------------------------------------------------------------------------- 1 | import { executeServerCommand } from '@web/test-runner-commands'; 2 | import { Command } from '../commands.js'; 3 | 4 | export * from '../commands.js'; 5 | 6 | export class VoiceOverTest { 7 | private commands: Command[] = []; 8 | private expected: string[] = []; 9 | 10 | async run(): Promise<{ values: string[], expected: string[] }> { 11 | const expected: string[] = [...this.expected]; 12 | const values: string[] = await executeServerCommand('voice-over', { commands: this.commands, expected: this.expected }); 13 | this.commands = []; 14 | this.expected = []; 15 | return { values, expected }; 16 | } 17 | 18 | queue(command: Command, expect: string) { 19 | this.commands.push(command); 20 | this.expected.push(expect); 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /src/commands.ts: -------------------------------------------------------------------------------- 1 | export interface Command { 2 | name: string, 3 | keyCode: number, 4 | modifiers: string[], 5 | } 6 | 7 | export const Commands: { [key: string]: Command } = { 8 | left: { 9 | name: 'Cursor Left', 10 | keyCode: 123, 11 | modifiers: ['control down', 'option down'], 12 | }, 13 | right: { 14 | name: 'Cursor Right', 15 | keyCode: 124, 16 | modifiers: ['control down', 'option down'], 17 | }, 18 | up: { 19 | name: 'Cursor Up', 20 | keyCode: 126, 21 | modifiers: ['control down', 'option down'], 22 | }, 23 | down: { 24 | name: 'Cursor Down', 25 | keyCode: 125, 26 | modifiers: ['control down', 'option down'], 27 | }, 28 | arrowLeft: { 29 | name: 'Arrow Left', 30 | keyCode: 123, 31 | modifiers: [], 32 | }, 33 | arrowRight: { 34 | name: 'Arrow Right', 35 | keyCode: 124, 36 | modifiers: [], 37 | }, 38 | arrowUp: { 39 | name: 'Arrow Up', 40 | keyCode: 126, 41 | modifiers: [], 42 | }, 43 | arrowDown: { 44 | name: 'Arrow Down', 45 | keyCode: 125, 46 | modifiers: [], 47 | }, 48 | interact: { 49 | name: 'Interact', 50 | keyCode: 124, 51 | modifiers: ['shift down', 'control down', 'option down'], 52 | }, 53 | tab: { 54 | name: 'Tab', 55 | keyCode: 48, 56 | modifiers: [], 57 | }, 58 | nextHeading: { 59 | name: 'Next Heading', 60 | keyCode: 4, 61 | modifiers: ['control down', 'option down', 'command down'], 62 | }, 63 | previousHeading: { 64 | name: 'Previous Heading', 65 | keyCode: 4, 66 | modifiers: ['shift down', 'control down', 'option down', 'command down'], 67 | }, 68 | space: { 69 | name: 'Space', 70 | keyCode: 49, 71 | modifiers: [], 72 | }, 73 | escape: { 74 | name: 'Escape', 75 | keyCode: 53, 76 | modifiers: [], 77 | }, 78 | home: { 79 | name: 'Home', 80 | keyCode: 115, 81 | modifiers: ['shift down'], 82 | } 83 | }; 84 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | import { VoiceOverBrowser } from './voiceover/index.js'; 2 | 3 | export interface PluginCommand { 4 | command: string; 5 | payload: any; 6 | session: any; 7 | } 8 | 9 | let voiceOver: VoiceOverBrowser = null; 10 | 11 | export function voiceOverPlugin() { 12 | return { 13 | name: 'voice-over-plugin', 14 | async executeCommand({ command, payload, session }: PluginCommand) { 15 | if (command === 'voice-over' && session.browser.type === 'playwright') { 16 | if (voiceOver === null) { 17 | voiceOver = new VoiceOverBrowser(); 18 | await voiceOver.boot(); 19 | } 20 | 21 | await voiceOver.start(session.browser.getPage(session.id)); 22 | let results: string[] = []; 23 | 24 | try { 25 | results = await voiceOver.runAll(payload); 26 | } catch (err) { 27 | console.log(err); 28 | await voiceOver.stop(); 29 | return err; 30 | } finally { 31 | return results; 32 | } 33 | } 34 | }, 35 | }; 36 | } 37 | -------------------------------------------------------------------------------- /src/test-one.spec.ts: -------------------------------------------------------------------------------- 1 | import { expect } from '@esm-bundle/chai'; 2 | import { VoiceOverTest, Commands } from 'web-test-runner-voiceover/browser'; 3 | 4 | describe('should enable voice over tests with inputs', () => { 5 | let element: HTMLElement; 6 | 7 | beforeEach(async () => { 8 | element = document.createElement('div'); 9 | element.innerHTML = /*html*/` 10 | 11 | 12 | `; 13 | document.body.appendChild(element); 14 | }); 15 | 16 | afterEach(() => element.remove()); 17 | 18 | it('should read inputs', async () => { 19 | const test = new VoiceOverTest(); 20 | test.queue(Commands.right, 'first name edit text'); 21 | test.queue(Commands.right, 'last name edit text'); 22 | test.queue(Commands.left, 'first name edit text'); 23 | const result = await test.run(); 24 | expect(result.values).to.eql(result.expected); 25 | }); 26 | }); 27 | 28 | describe('should enable voice over tests with buttons', () => { 29 | let element: HTMLElement; 30 | 31 | beforeEach(async () => { 32 | element = document.createElement('div'); 33 | element.innerHTML = /*html*/` 34 | 35 | 36 | 37 | `; 38 | document.body.appendChild(element); 39 | }); 40 | 41 | afterEach(() => element.remove()); 42 | 43 | it('should read buttons', async () => { 44 | const test = new VoiceOverTest(); 45 | test.queue(Commands.right, 'one button'); 46 | test.queue(Commands.right, 'two button'); 47 | test.queue(Commands.right, 'three button'); 48 | test.queue(Commands.left, 'two button'); 49 | test.queue(Commands.left, 'one button'); 50 | const result = await test.run(); 51 | expect(result.values).to.eql(result.expected); 52 | }); 53 | 54 | it('should read buttons again after reset for test', async () => { 55 | const test = new VoiceOverTest(); 56 | test.queue(Commands.right, 'one button'); 57 | test.queue(Commands.right, 'two button'); 58 | test.queue(Commands.left, 'one button'); 59 | const result = await test.run(); 60 | expect(result.values).to.eql(result.expected); 61 | }); 62 | }); 63 | -------------------------------------------------------------------------------- /src/test-three.spec.ts: -------------------------------------------------------------------------------- 1 | import { expect } from '@esm-bundle/chai'; 2 | import { VoiceOverTest, Commands } from 'web-test-runner-voiceover/browser'; 3 | 4 | describe('should enable voice over tests with radios', () => { 5 | let element: HTMLElement; 6 | 7 | beforeEach(async () => { 8 | element = document.createElement('div'); 9 | element.innerHTML = /*html*/` 10 |

Select Memory:

11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | `; 20 | document.body.appendChild(element); 21 | }); 22 | 23 | afterEach(() => element.remove()); 24 | 25 | it('should read radios', async () => { 26 | const test = new VoiceOverTest(); 27 | test.queue(Commands.right, 'select memory:'); 28 | test.queue(Commands.right, '128 gb'); 29 | test.queue(Commands.right, '128 gb selected radio button, 1 of 3'); 30 | test.queue(Commands.right, '256 gb'); 31 | test.queue(Commands.right, '256 gb radio button, 2 of 3'); 32 | test.queue(Commands.right, '512 gb'); 33 | test.queue(Commands.right, '512 gb radio button, 3 of 3'); 34 | test.queue(Commands.space, 'selected 512 gb radio button, 3 of 3'); 35 | const result = await test.run(); 36 | expect(result.values).to.eql(result.expected); 37 | }); 38 | }); 39 | -------------------------------------------------------------------------------- /src/test-two.spec.ts: -------------------------------------------------------------------------------- 1 | import { expect } from '@esm-bundle/chai'; 2 | import { VoiceOverTest, Commands } from 'web-test-runner-voiceover/browser'; 3 | 4 | describe('should enable voice over tests with buttons', () => { 5 | let element: HTMLElement; 6 | 7 | beforeEach(async () => { 8 | element = document.createElement('div'); 9 | element.innerHTML = /*html*/` 10 | 11 | 12 | 13 | `; 14 | document.body.appendChild(element); 15 | }); 16 | 17 | afterEach(() => element.remove()); 18 | 19 | it('should read buttons', async () => { 20 | const test = new VoiceOverTest(); 21 | test.queue(Commands.right, 'four button'); 22 | test.queue(Commands.right, 'five button'); 23 | test.queue(Commands.right, 'six button'); 24 | test.queue(Commands.left, 'five button'); 25 | test.queue(Commands.left, 'four button'); 26 | const result = await test.run(); 27 | expect(result.values).to.eql(result.expected); 28 | }); 29 | }); 30 | -------------------------------------------------------------------------------- /src/types.d.ts: -------------------------------------------------------------------------------- 1 | 2 | declare module 'node-osascript'; -------------------------------------------------------------------------------- /src/voiceover/dom.ts: -------------------------------------------------------------------------------- 1 | import { Page } from 'playwright'; 2 | 3 | export function appendMarker(page: Page) { 4 | return page.evaluate(() => { 5 | const startMarker = document.querySelector('[vo-mark="start"]'); 6 | if (!startMarker) { 7 | document.head.insertAdjacentHTML('beforeend', ``); 18 | const start = document.createElement('h2'); 19 | start.innerHTML = 'vo-start'; 20 | start.setAttribute('vo-mark', 'start'); 21 | document.querySelector('body').prepend(start); 22 | } 23 | }); 24 | } -------------------------------------------------------------------------------- /src/voiceover/index.ts: -------------------------------------------------------------------------------- 1 | import { run as jxaRun } from '@jxa/run'; 2 | import { Page } from 'playwright'; 3 | import '@jxa/global-type'; 4 | 5 | import { Command, Commands } from '../commands.js'; 6 | import { updateSettings, testSettings, defaultSettings } from './settings.js'; 7 | import { appendMarker } from './dom.js'; 8 | import { getAppleScriptVoiceOverPermissions, processHasStarted, startVoiceOverProcess, stopProcess } from './system.js'; 9 | 10 | for (const event of ['exit', 'SIGINT', 'SIGUSR1', 'SIGUSR2', 'uncaughtException', 'SIGTERM']) { 11 | process.on(event, () => { 12 | updateSettings(defaultSettings, false); 13 | stopProcess('VoiceOver'); 14 | }); 15 | } 16 | 17 | export class VoiceOverBrowser { 18 | async boot() { 19 | stopProcess('VoiceOver'); 20 | await updateSettings(testSettings); 21 | await getAppleScriptVoiceOverPermissions(); 22 | await startVoiceOverProcess(); 23 | await untilPhrase('web content'); 24 | } 25 | 26 | async start(page: Page) { 27 | await appendMarker(page); 28 | await processHasStarted('Playwright'); 29 | await processHasStarted('VoiceOver'); 30 | await focusBrowser(); 31 | await run(Commands.nextHeading); 32 | } 33 | 34 | async stop() { 35 | return stopProcess('VoiceOver'); 36 | } 37 | 38 | async runAll(config: { commands: Command[], expected: string[]}) { 39 | let i = 0; 40 | let results = []; 41 | while (i < config.commands.length) { 42 | await run(config.commands[i]); 43 | const result = await untilPhrase(config.expected[i]); 44 | console.log(result); 45 | results.push(result); 46 | i++; 47 | } 48 | return results; 49 | } 50 | } 51 | 52 | async function focusBrowser() { 53 | return jxaRun(() => { 54 | Application('System Events').applicationProcesses.byName('Playwright').windows[0].actions.byName('AXRaise'); 55 | }); 56 | } 57 | 58 | async function run(command: Command) { 59 | await jxaRun( 60 | ({ keyCode, modifiers }) => Application('System Events').keyCode(keyCode, { using: modifiers }), 61 | command 62 | ); 63 | } 64 | 65 | async function lastPhrase() { 66 | return jxaRun(() => (Application('VoiceOver').lastPhrase as any).content()).catch(err => console.log(err)); 67 | } 68 | 69 | async function untilPhrase(value: string): Promise { 70 | return new Promise(async (resolve) => { 71 | let count = 0; 72 | let phrases: string[] = []; 73 | while (count < 50) { 74 | const phrase = await lastPhrase(); 75 | const result = value.trim().toLocaleLowerCase(); 76 | if (phrase && phrase.trim().toLocaleLowerCase().includes(result)) { 77 | resolve(result); 78 | break; 79 | } else { 80 | count++; 81 | phrases.push(phrase as string); 82 | if (!(phrase as string)?.includes('. Speech off.')) { 83 | console.log(phrase); 84 | } 85 | await new Promise(r => setTimeout(() => r(null), 10)); 86 | } 87 | } 88 | 89 | if (count >= 1000) { 90 | resolve(`${[...new Set(phrases)].join('. ')}`); 91 | } 92 | }) 93 | } 94 | -------------------------------------------------------------------------------- /src/voiceover/settings.ts: -------------------------------------------------------------------------------- 1 | import { exec } from './utils.js'; 2 | 3 | interface VOSettings { 4 | voiceOverCursorEnabled?: string, 5 | doNotShowSplashScreen?: string; 6 | disableSpeech?: string; 7 | disableSound?: string; 8 | displayTextEnabled?: string; 9 | rateAsPercent?: string; 10 | loginGreeting?: string; 11 | } 12 | 13 | export const testSettings: VOSettings = { 14 | voiceOverCursorEnabled: '1', 15 | doNotShowSplashScreen: '1', 16 | disableSpeech: '1', 17 | disableSound: '1', 18 | displayTextEnabled: '0', 19 | rateAsPercent: '100', 20 | loginGreeting: '' 21 | }; 22 | 23 | export const defaultSettings: VOSettings = { 24 | voiceOverCursorEnabled: '1', 25 | doNotShowSplashScreen: '1', 26 | disableSpeech: '0', 27 | disableSound: '0', 28 | displayTextEnabled: '1', 29 | rateAsPercent: '45', 30 | loginGreeting: 'Welcome to macOS. VoiceOver is on.' 31 | }; 32 | 33 | export async function getSettingDefault(settingDefaults: string, async = true) { 34 | return await exec(`defaults read ${settingDefaults}`, async); 35 | } 36 | 37 | export function updateSettings(settings: VOSettings, async = true) { 38 | const commands = [ 39 | // `defaults write com.apple.VoiceOver4/default SCREnableAppleScript -bool YES`, 40 | `defaults write com.apple.VoiceOverTraining doNotShowSplashScreen ${settings.doNotShowSplashScreen}`, 41 | `defaults write com.apple.VoiceOver4/default SCRVoiceOverCursorEnabled ${settings.voiceOverCursorEnabled}`, 42 | `defaults write com.apple.VoiceOver4/default SCRCategories_SCRCategorySystemWide_SCRSpeechComponentSettings_SCRDisableSpeech ${settings.disableSpeech}`, 43 | `defaults write com.apple.VoiceOver4/default SCRCategories_SCRCategorySystemWide_SCRSoundComponentSettings_SCRDisableSound ${settings.disableSound}`, 44 | `defaults write com.apple.VoiceOver4/default SCRDisplayTextEnabled ${settings.displayTextEnabled}`, 45 | `defaults write com.apple.VoiceOver4/default SCRCategories_SCRCategorySystemWide_SCRSpeechLanguages_default_SCRSpeechComponentSettings_SCRRateAsPercent ${settings.rateAsPercent}`, 46 | `defaults write com.apple.VoiceOver4/default loginGreeting "${settings.loginGreeting}"`, 47 | ]; 48 | 49 | return async ? Promise.all(commands.map(c => exec(c))) : commands.forEach(c => exec(c, false)); 50 | } 51 | -------------------------------------------------------------------------------- /src/voiceover/system.ts: -------------------------------------------------------------------------------- 1 | import * as osascript from 'node-osascript'; 2 | import { getSettingDefault } from './settings.js'; 3 | import { exec, retry } from './utils.js'; 4 | 5 | export async function stopProcess(process: string) { 6 | return await new Promise((resolve, reject) => { 7 | const command = ` 8 | tell application "${process}" 9 | quit 10 | end tell`; 11 | osascript.execute(command, (err: any, result: any, _raw: any) => { 12 | err ? reject(err) : resolve(result); 13 | }); 14 | }); 15 | } 16 | 17 | async function processIsRunning(process: string) { 18 | return await new Promise((resolve, reject) => { 19 | const command = ` 20 | tell application "System Events" 21 | name of every process contains ("${process}") 22 | end tell`; 23 | osascript.execute(command, (err: any, result: any, _raw: any) => { 24 | err ? reject(err) : resolve(result); 25 | }); 26 | }); 27 | } 28 | 29 | export async function startVoiceOverProcess() { 30 | return exec('/System/Library/CoreServices/VoiceOver.app/Contents/MacOS/VoiceOverStarter'); 31 | } 32 | 33 | async function supportsAppleScript(): Promise { 34 | return new Promise(async (resolve) => { 35 | try { 36 | const value = await getSettingDefault('com.apple.VoiceOver4/default SCREnableAppleScript', false); 37 | resolve(value.stdout.trim() === '1'); 38 | } catch { 39 | resolve(false); 40 | } 41 | }) 42 | } 43 | 44 | export async function getAppleScriptVoiceOverPermissions() { 45 | return await new Promise(async (resolve, reject) => { 46 | const supports = await supportsAppleScript(); 47 | if (!process.env.GITHUB_ACTION && !supports) { 48 | const command = ` 49 | tell application "VoiceOver Utility" to quit 50 | delay 1 51 | tell application "VoiceOver Utility" to activate 52 | 53 | tell application "System Events" to tell application process "VoiceOver Utility" 54 | tell window "VoiceOver Utility" 55 | set theCheckbox to checkbox "Allow VoiceOver to be controlled with AppleScript" of splitter group 1 56 | tell theCheckbox 57 | if not (its value as boolean) then 58 | click theCheckbox 59 | delay 1 60 | end if 61 | end tell 62 | end tell 63 | end tell 64 | 65 | tell application "VoiceOver Utility" to quit`; 66 | osascript.execute(command, (err: any, result: any, _raw: any) => { 67 | err ? reject(err) : resolve(result); 68 | }); 69 | 70 | } else { 71 | resolve('1'); 72 | } 73 | }); 74 | } 75 | 76 | export async function processHasStarted(process: string) { 77 | return retry(() => processIsRunning(process)).catch(err => console.log(`${process}: ${err}`)); 78 | } 79 | 80 | -------------------------------------------------------------------------------- /src/voiceover/utils.ts: -------------------------------------------------------------------------------- 1 | import { promisify } from 'util'; 2 | import { exec as ex } from 'child_process'; 3 | 4 | export const exec = (cmd: string, async = true) => { 5 | return async ? promisify(ex)(cmd).catch((err: any) => console.log('ERROR: ', err)) : ex(cmd); 6 | } 7 | 8 | export function retry( 9 | fn: any, 10 | maxTries = 10, 11 | promise?: Promise, 12 | promiseObject: { resolve: any; reject: any } = { 13 | resolve: null, 14 | reject: null, 15 | } 16 | ) { 17 | maxTries--; 18 | 19 | promise = 20 | promise || 21 | new Promise((resolve, reject) => { 22 | promiseObject.resolve = resolve; 23 | promiseObject.reject = reject; 24 | }); 25 | 26 | fn() 27 | .then((result: any) => { 28 | promiseObject.resolve(result); 29 | }) 30 | .catch(() => { 31 | if (maxTries > 0) { 32 | retry(fn, maxTries, promise, promiseObject); 33 | } else { 34 | promiseObject.reject('Max attempts reached'); 35 | } 36 | }); 37 | 38 | return promise; 39 | } 40 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "es2019", 4 | "module": "esnext", 5 | "moduleResolution": "node", 6 | "lib": ["es2020", "dom"], 7 | "emitDecoratorMetadata": false, 8 | "experimentalDecorators": true, 9 | "allowSyntheticDefaultImports": true, 10 | "resolveJsonModule": true, 11 | "declaration": true, 12 | "alwaysStrict": true, 13 | "noImplicitAny": true, 14 | "noImplicitReturns": true, 15 | "noImplicitThis": true, 16 | "noUnusedLocals": false, 17 | "noUnusedParameters": true, 18 | "strictFunctionTypes": true, 19 | "noFallthroughCasesInSwitch": true, 20 | "strictNullChecks": false, 21 | "sourceMap": false, 22 | "inlineSourceMap": false, 23 | "importHelpers": true, 24 | "rootDir": "./src", 25 | "baseUrl": "./", 26 | "paths": { 27 | "web-test-runner-voiceover": ["./dist"], 28 | "web-test-runner-voiceover/*": ["./dist/*"] 29 | } 30 | }, 31 | "include": ["src/**/*.ts", "src/**/*.d.ts"], 32 | "exclude": ["node_modules"] 33 | } 34 | -------------------------------------------------------------------------------- /tsconfig.lib.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "./tsconfig.json", 3 | "compilerOptions": { 4 | "noEmit": false, 5 | "outDir": "./dist", 6 | }, 7 | "include": ["src/**/*.ts", "src/**/*.d.ts"], 8 | "exclude": ["dist", "node_modules", "src/**/*.spec.ts"] 9 | } 10 | -------------------------------------------------------------------------------- /web-test-runner.config.mjs: -------------------------------------------------------------------------------- 1 | import { playwrightLauncher } from '@web/test-runner-playwright'; 2 | import { esbuildPlugin } from '@web/dev-server-esbuild'; 3 | import { fromRollup } from '@web/dev-server-rollup'; 4 | import alias from '@rollup/plugin-alias'; 5 | import { voiceOverPlugin } from './dist/index.js'; // web-test-runner-voiceover 6 | 7 | export default /** @type {import("@web/test-runner").TestRunnerConfig} */ ({ 8 | concurrency: 1, 9 | concurrentBrowsers: 1, 10 | files: ['./src/**/*.spec.ts'], 11 | testsFinishTimeout: 60000, 12 | testFramework: { 13 | config: { timeout: '60000' } 14 | }, 15 | browsers: [playwrightLauncher({ product: 'webkit', launchOptions: { headless: false } })], 16 | nodeResolve: true, 17 | dedupe: true, 18 | plugins: [ 19 | voiceOverPlugin(), 20 | fromRollup(alias)({ 21 | entries: [ 22 | { find: /^web-test-runner-voiceover/, replacement: `${process.cwd()}/dist` } 23 | ], 24 | }), 25 | esbuildPlugin({ ts: true, json: true, target: 'auto', sourceMap: true }) 26 | ] 27 | }); 28 | --------------------------------------------------------------------------------