@guidepup/playwright - npm Package Compare versions

Comparing version 0.12.0 to 0.13.0

lib/index.d.ts

@@ -1,2 +0,5 @@
-export { voTest } from "./voTest";
-export { voConfig } from "./voConfig";
+export { nvdaTest } from "./nvdaTest";
+export type { NVDAPlaywright } from "./nvdaTest";
+export { screenReaderConfig } from "./screenReaderConfig";
+export { voiceOverTest } from "./voiceOverTest";
+export type { VoiceOverPlaywright } from "./voiceOverTest";

lib/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.voConfig = exports.voTest = void 0;
-var voTest_1 = require("./voTest");
-Object.defineProperty(exports, "voTest", { enumerable: true, get: function () { return voTest_1.voTest; } });
-var voConfig_1 = require("./voConfig");
-Object.defineProperty(exports, "voConfig", { enumerable: true, get: function () { return voConfig_1.voConfig; } });
+exports.voiceOverTest = exports.screenReaderConfig = exports.nvdaTest = void 0;
+var nvdaTest_1 = require("./nvdaTest");
+Object.defineProperty(exports, "nvdaTest", { enumerable: true, get: function () { return nvdaTest_1.nvdaTest; } });
+var screenReaderConfig_1 = require("./screenReaderConfig");
+Object.defineProperty(exports, "screenReaderConfig", { enumerable: true, get: function () { return screenReaderConfig_1.screenReaderConfig; } });
+var voiceOverTest_1 = require("./voiceOverTest");
+Object.defineProperty(exports, "voiceOverTest", { enumerable: true, get: function () { return voiceOverTest_1.voiceOverTest; } });

package.json

 {
   "name": "@guidepup/playwright",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Screen reader driver for Playwright tests.",
@@ -27,3 +27,3 @@ "main": "lib/index.js",
     "ci": "yarn clean && yarn lint && yarn build",
-    "clean": "rimraf lib",
+    "clean": "rimraf lib test-results recordings",
     "compile": "tsc",
@@ -34,13 +34,16 @@ "lint": "eslint . --ext .ts",
     "pretest": "npx playwright install chromium firefox webkit",
-    "test": "yarn test:chromium && yarn test:firefox && yarn test:webkit",
-    "test:chromium": "playwright test --config ./example/chromium.config.ts ./example/tests/chromium/",
-    "test:firefox": "playwright test --config ./example/firefox.config.ts ./example/tests/firefox/",
-    "test:webkit": "playwright test --config ./example/webkit.config.ts ./example/tests/webkit/"
+    "test:nvda": "yarn test:nvda:chromium && yarn test:nvda:firefox",
+    "test:voiceover": "yarn test:voiceover:chromium && yarn test:voiceover:firefox && yarn test:voiceover:webkit",
+    "test:nvda:chromium": "playwright test --config ./examples/playwright-nvda/chromium.config.ts ./examples/playwright-nvda/tests/chromium/",
+    "test:nvda:firefox": "playwright test --config ./examples/playwright-nvda/firefox.config.ts ./examples/playwright-nvda/tests/firefox/",
+    "test:voiceover:chromium": "playwright test --config ./examples/playwright-voiceover/chromium.config.ts ./examples/playwright-voiceover/tests/chromium/",
+    "test:voiceover:firefox": "playwright test --config ./examples/playwright-voiceover/firefox.config.ts ./examples/playwright-voiceover/tests/firefox/",
+    "test:voiceover:webkit": "playwright test --config ./examples/playwright-voiceover/webkit.config.ts ./examples/playwright-voiceover/tests/webkit/"
   },
   "devDependencies": {
-    "@guidepup/guidepup": "^0.21.0",
+    "@guidepup/guidepup": "^0.22.0",
     "@playwright/test": "^1.40.1",
-    "@types/node": "^20.10.5",
-    "@typescript-eslint/eslint-plugin": "^6.16.0",
-    "@typescript-eslint/parser": "^6.16.0",
+    "@types/node": "^20.10.6",
+    "@typescript-eslint/eslint-plugin": "^6.18.0",
+    "@typescript-eslint/parser": "^6.18.0",
     "eslint": "^8.56.0",
@@ -50,8 +53,8 @@ "eslint-config-prettier": "^9.1.0",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.25.4",
+    "typedoc": "^0.25.6",
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
-    "@guidepup/guidepup": "^0.21.0",
-    "@playwright/test": "^1.29.2"
+    "@guidepup/guidepup": "^0.22.0",
+    "@playwright/test": "^1.40.1"
   },
@@ -58,0 +61,0 @@ "resolutions": {

README.md

@@ -1,33 +0,24 @@
-<h1 align="center">Guidepup Playwright</h1>
-<p align="center">
-  <i>Screen reader driver for Playwright tests.</i>
-</p>
-<p align="center">
-  <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>
-  <a href="https://www.npmjs.com/package/@guidepup/playwright"><img alt="@guidepup/playwright available on NPM" src="https://img.shields.io/npm/dt/@guidepup/playwright"></a>
-  <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>
-  <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>
-</p>
-<p align="center">
-  Reliable automation for your screen reader a11y workflows in Playwright supporting:
-</p>
-<p align="center">
-  <a href="https://www.guidepup.dev/docs/api/class-voiceover"><b>VoiceOver on MacOS</b></a>
-</p>
-<p align="center">
-  <b>NVDA on Windows</b> - <a href="https://github.com/guidepup/guidepup/pull/33">Coming Soon!</a>
-</p>
+# Guidepup Playwright
 
-## Intro
+<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>
+<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>
+<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>
 
-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!**
+## [Documentation](https://guidepup.dev) | [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
 
-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!
+[![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)
+[![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)
+[![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)
+[![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)
 
-## Quick Features
+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>.
 
-- **Full Control** - if a screen reader has a keyboard command, then Guidepup supports it.
-- **Mirrors Real User Experience** - assert on what users really do and hear when using screen readers.
-- **Framework Agnostic** - run with Jest, with Playwright, as an independent script, no vendor lock-in.
+## Capabilities
 
+- **Full Control** - If a screen reader has a keyboard command, then Guidepup supports it.
+- **Mirrors Real User Experience** - Assert on what users really do and hear when using screen readers.
+- **Framework Agnostic** - Run with Jest, with Playwright, as an independent script, no vendor lock-in.
+
 ## Getting Started
@@ -37,9 +28,16 @@
 
-```console
+```sh
 npx @guidepup/setup
 ```
 
+If you are using GitHub Actions, check out the dedicated [`guidepup/setup-action`](https://github.com/marketplace/actions/guidepup-setup):
+
+```yaml
+- name: Setup Environment
+  uses: guidepup/setup-action
+```
+
 Install `@guidepup/playwright` to your project:
 
-```console
+```sh
 npm install --save-dev @guidepup/playwright @guidepup/guidepup @playwright/test
@@ -52,8 +50,61 @@ ```
 
+## Examples
+
+Head over to the [Guidepup Website](https://www.guidepup.dev/) for guides, real world examples, environment setup, and complete API documentation with examples.
+
+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.
+
+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.
+
+### Playwright Config
+
+In your `playwright.config.ts` add the following for the best results with Guidepup for Screen Reader automation:
+
 ```ts
-import { voTest as test } from "@guidepup/playwright";
+import { devices, PlaywrightTestConfig } from "@playwright/test";
+import { screenReaderConfig } from "@guidepup/playwright";
+
+const config: PlaywrightTestConfig = {
+  ...screenReaderConfig,
+
+  // ... your custom config
+};
+
+export default config;
+```
+
+Check out the configuration this adds [in the `config.ts`` file](./src/config.ts).
+
+### VoiceOver
+
+`playwright.config.ts`:
+
+```ts
+import { devices, PlaywrightTestConfig } from "@playwright/test";
+import { screenReaderConfig } from "@guidepup/playwright";
+
+const config: PlaywrightTestConfig = {
+  ...screenReaderConfig,
+  reportSlowTests: null,
+  timeout: 5 * 60 * 1000,
+  retries: 2,
+  projects: [
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"], headless: false },
+    },
+  ],
+};
+
+export default config;
+```
+
+`voiceOver.spec.ts`:
+
+```ts
+import { voiceOverTest as test } from "@guidepup/playwright";
 import { expect } from "@playwright/test";
 
 test.describe("Playwright VoiceOver", () => {
-  test("I can navigate the Guidepup Github page", async ({
+  test("I can navigate the Guidepup Github page with VoiceOver", async ({
     page,
@@ -64,29 +115,42 @@ voiceOver,
     await page.goto("https://github.com/guidepup/guidepup", {
-      waitUntil: "domcontentloaded",
+      waitUntil: "load",
     });
 
-    // Wait for page to be ready and interact
-    await expect(page.locator('header[role="banner"]')).toBeVisible();
-    await voiceOver.interact();
+    // Wait for page to be ready
+    const header = page.locator('header[role="banner"]');
+    await header.waitFor();
 
+    // Interact with the page
+    await voiceOver.navigateToWebContent();
+
     // Move across the page menu to the Guidepup heading using VoiceOver
     while ((await voiceOver.itemText()) !== "Guidepup heading level 1") {
-      await voiceOver.perform(voiceOver.keyboard.commands.findNextHeading);
+      await voiceOver.perform(voiceOver.keyboardCommands.findNextHeading);
     }
+
+    // Assert that the spoken phrases are as expected
+    expect(JSON.stringify(await voiceOver.spokenPhraseLog())).toMatchSnapshot();
+  });
 });
 ```
 
-## Playwright Config
+### NVDA
 
-In your `playwright.config.ts` add the following for the best results with
-Guidepup for VoiceOver automation.
+`playwright.config.ts`:
 
 ```ts
 import { devices, PlaywrightTestConfig } from "@playwright/test";
-import { voConfig } from "@guidepup/playwright";
+import { screenReaderConfig } from "@guidepup/playwright";
 
 const config: PlaywrightTestConfig = {
-  ...voConfig,
-
-  // Your custom config ...
+  ...screenReaderConfig,
+  reportSlowTests: null,
+  timeout: 5 * 60 * 1000,
+  retries: 2,
+  projects: [
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"], headless: false },
+    },
+  ],
 };
@@ -97,35 +161,53 @@
 
-Check out the configuration this adds [in the voConfig.ts file](./src/voConfig.ts).
+`nvda.spec.ts`:
 
-## Environment Setup
+```ts
+import { nvdaTest as test } from "@guidepup/playwright";
+import { expect } from "@playwright/test";
 
-Set up your environment for screen-read automation with [`@guidepup/setup`](https://github.com/guidepup/setup):
+test.describe("Playwright NVDA", () => {
+  test("I can navigate the Guidepup Github page with NVDA", async ({
+    page,
+    nvda,
+  }) => {
+    // Navigate to Guidepup GitHub page
+    await page.goto("https://github.com/guidepup/guidepup", {
+      waitUntil: "load",
+    });
 
-```console
-npx @guidepup/setup
-```
+    // Wait for page to be ready and setup
+    const header = page.locator('header[role="banner"]');
+    await header.waitFor();
 
-If you are using GitHub Actions, check out the dedicated [`guidepup/setup-action`](https://github.com/marketplace/actions/guidepup-setup):
+    // Interact with the page
+    await nvda.navigateToWebContent();
 
-```yaml
-- name: Setup Environment
-  uses: guidepup/setup-action@0.13.0
+    // Move across the page menu to the Guidepup heading using NVDA
+    while (
+      !(await nvda.lastSpokenPhrase()).includes("Guidepup, heading, level 1")
+    ) {
+      await nvda.perform(nvda.keyboardCommands.moveToNextHeading);
+    }
+
+    // Assert that the spoken phrases are as expected
+    expect(JSON.stringify(await nvda.spokenPhraseLog())).toMatchSnapshot();
+  });
+});
 ```
 
-## Documentation
+## Powerful Tooling
 
-Head over to the [Guidepup Website](https://www.guidepup.dev/) for guides, real world examples, environment setup, and complete Guidepup API documentation with examples.
+Check out some of the other Guidepup modules:
 
-## Example
+- [`@guidepup/guidepup`](https://github.com/guidepup/guidepup/) - Reliable automation for your screen reader a11y workflows through JavaScript supporting VoiceOver and NVDA.
+- [`@guidepup/setup`](https://github.com/guidepup/setup/) - Set up your local or CI environment for screen reader test automation.
+- [`@guidepup/virtual-screen-reader`](https://github.com/guidepup/virtual-screen-reader/) - Reliable unit testing for your screen reader a11y workflows.
+- [`@guidepup/jest`](https://github.com/guidepup/jest/) - Jest matchers for reliable unit testing of your screen reader a11y workflows.
 
-Check out [this cross-browser VoiceOver example](./example/).
+## Resources
 
-## See Also
-
-Checkout the core [`@guidepup/guidepup`](https://github.com/guidepup/guidepup)
-project to learn more about how you can automate your screen reader workflows
-using Guidepup.
-
-## License
-
-[MIT](https://github.com/guidepup/guidepup/blob/main/LICENSE)
+- [Documentation](https://www.guidepup.dev/docs/example)
+- [API Reference](https://www.guidepup.dev/docs/api/class-guidepup)
+- [Contributing](.github/CONTRIBUTING.md)
+- [Changelog](https://github.com/guidepup/guidepup-playwright/releases)
+- [MIT License](https://github.com/guidepup/guidepup-playwright/blob/main/LICENSE)

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24254

increased by123.68%

Number of package files

13

increased by44.44%

Lines of code

347

increased by308.24%

Number of lines in readme file

210

increased by64.06%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes