feat: allow setting of start options (#17)

Author: jlp-craigmorten

.gitignore

@@ -106,3 +106,4 @@ dist
 lib
 .DS_Store
 test-results
+recordings

README.md

@@ -110,12 +110,30 @@ await nvda.navigateToWebContent();
 
 // ... some commands
 
-// Collect all spoken phrasees
+// Collect all spoken phrases
 const allSpokenPhrases = [...spokenPhrases, ...(await nvda.spokenPhraseLog())];
 
 // ... do something with spoken phrases
 ```
 
+### Providing Screen Reader Start Options
+
+The options provided to `nvda.start([options])` or `voiceOver.start([options])` can be configured using `test.use(config)` as follows:
+
+```ts
+// VoiceOver Example
+import { voiceOverTest as test } from "@guidepup/playwright";
+
+test.use({ voiceOverStartOptions: { capture: "initial" } });
+```
+
+```ts
+// NVDA Example
+import { nvdaTest as test } from "@guidepup/playwright";
+
+test.use({ nvdaStartOptions: { capture: "initial" } });
+```
+
 ### VoiceOver Example
 
 `playwright.config.ts`:

examples/playwright-nvda/tests/chromium/chromium.spec.ts

@@ -5,6 +5,8 @@ import { windowsRecord } from "@guidepup/guidepup";
 import spokenPhraseSnapshot from "./chromium.spokenPhrase.snapshot.json";
 import { nvdaTest as test } from "../../../../src";
 
+test.use({ nvdaStartOptions: { capture: "initial" } });
+
 test.describe("Chromium Playwright NVDA", () => {
   test("I can navigate the Guidepup Github page", async ({
     browser,

examples/playwright-nvda/tests/firefox/firefox.spec.ts

@@ -5,6 +5,8 @@ import { windowsRecord } from "@guidepup/guidepup";
 import spokenPhraseSnapshot from "./firefox.spokenPhrase.snapshot.json";
 import { nvdaTest as test } from "../../../../src";
 
+test.use({ nvdaStartOptions: { capture: "initial" } });
+
 test.describe("Firefox Playwright VoiceOver", () => {
   test("I can navigate the Guidepup Github page", async ({
     browser,

examples/playwright-voiceover/tests/chromium/chromium.spec.ts

@@ -6,6 +6,8 @@ import { macOSRecord } from "@guidepup/guidepup";
 import spokenPhraseSnapshot from "./chromium.spokenPhrase.snapshot.json";
 import { voiceOverTest as test } from "../../../../src";
 
+test.use({ voiceOverStartOptions: { capture: "initial" } });
+
 test.describe("Chromium Playwright VoiceOver", () => {
   test("I can navigate the Guidepup Github page", async ({
     browser,

examples/playwright-voiceover/tests/firefox/firefox.spec.ts

@@ -6,6 +6,8 @@ import { macOSRecord } from "@guidepup/guidepup";
 import spokenPhraseSnapshot from "./firefox.spokenPhrase.snapshot.json";
 import { voiceOverTest as test } from "../../../../src";
 
+test.use({ voiceOverStartOptions: { capture: "initial" } });
+
 test.describe("Firefox Playwright VoiceOver", () => {
   test("I can navigate the Guidepup Github page", async ({
     browser,

examples/playwright-voiceover/tests/webkit/webkit.spec.ts

@@ -6,6 +6,8 @@ import { macOSRecord } from "@guidepup/guidepup";
 import spokenPhraseSnapshot from "./webkit.spokenPhrase.snapshot.json";
 import { voiceOverTest as test } from "../../../../src";
 
+test.use({ voiceOverStartOptions: { capture: "initial" } });
+
 test.describe("Webkit Playwright VoiceOver", () => {
   test("I can navigate the Guidepup Github page", async ({
     browser,

src/nvdaTest.ts

@@ -1,8 +1,15 @@
 import { test } from "@playwright/test";
 import { nvda, WindowsKeyCodes, WindowsModifiers } from "@guidepup/guidepup";
-import type { NVDA } from "@guidepup/guidepup";
+import type { CommandOptions, NVDA } from "@guidepup/guidepup";
 import { applicationNameMap } from "./applicationNameMap";
 
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+  // eslint-disable-next-line @typescript-eslint/ban-types
+} & {};
+
+type CaptureCommandOptions = Prettify<Pick<CommandOptions, "capture">>;
+
 /**
  * [API Reference](https://www.guidepup.dev/docs/api/class-nvda)
  *
@@ -108,8 +115,15 @@ export const nvdaTest = test.extend<{
    * ```
    */
   nvda: NVDAPlaywright;
+  /**
+   * [API Reference](https://www.guidepup.dev/docs/api/class-command-options)
+   *
+   * Options to start NVDA with, see also [nvda.start([options])](https://www.guidepup.dev/docs/api/class-nvda#nvda-start).
+   */
+  nvdaStartOptions: CaptureCommandOptions;
 }>({
-  nvda: async ({ browserName, page }, use) => {
+  nvdaStartOptions: {},
+  nvda: async ({ browserName, page, nvdaStartOptions }, use) => {
     try {
       const applicationName = applicationNameMap[browserName];
 
@@ -158,7 +172,7 @@ export const nvdaTest = test.extend<{
         await nvdaPlaywright.clearSpokenPhraseLog();
       };
 
-      await nvdaPlaywright.start();
+      await nvdaPlaywright.start(nvdaStartOptions);
 
       await use(nvdaPlaywright);
     } finally {

src/voiceOverTest.ts

@@ -1,6 +1,6 @@
 import { test } from "@playwright/test";
 import { voiceOver, macOSActivate } from "@guidepup/guidepup";
-import type { VoiceOver } from "@guidepup/guidepup";
+import type { CommandOptions, VoiceOver } from "@guidepup/guidepup";
 import { applicationNameMap } from "./applicationNameMap";
 
 /**
@@ -74,8 +74,15 @@ export const voiceOverTest = test.extend<{
    * ```
    */
   voiceOver: VoiceOverPlaywright;
+  /**
+   * [API Reference](https://www.guidepup.dev/docs/api/class-command-options)
+   *
+   * Options to start VoiceOver with, see also [voiceOver.start([options])](https://www.guidepup.dev/docs/api/class-voiceover#voiceover-start).
+   */
+  voiceOverStartOptions: CommandOptions;
 }>({
-  voiceOver: async ({ browserName, page }, use) => {
+  voiceOverStartOptions: {},
+  voiceOver: async ({ browserName, page, voiceOverStartOptions }, use) => {
     try {
       const applicationName = applicationNameMap[browserName];
 
@@ -103,7 +110,7 @@ export const voiceOverTest = test.extend<{
         await voiceOverPlaywright.clearSpokenPhraseLog();
       };
 
-      await voiceOverPlaywright.start();
+      await voiceOverPlaywright.start(voiceOverStartOptions);
       await macOSActivate(applicationName);
       await use(voiceOverPlaywright);
     } finally {