@web/test-runner-commands 0.0.0-canary-20230403143511

package/src/selectOptionPlugin.ts

@@ -0,0 +1,122 @@
+import { TestRunnerPlugin } from '@web/test-runner-core';
+import type { ChromeLauncher } from '@web/test-runner-chrome';
+import type { PlaywrightLauncher } from '@web/test-runner-playwright';
+
+type SelectByValuePayload = { selector: string; value: string };
+type SelectByLabelPayload = { selector: string; label: string };
+type SelectMultipleValuesPayload = { selector: string; values: string[] };
+
+export type SelectOptionPayload =
+  | SelectByLabelPayload
+  | SelectByValuePayload
+  | SelectMultipleValuesPayload;
+
+function isObject(payload: unknown): payload is Record<string, unknown> {
+  return payload != null && typeof payload === 'object';
+}
+
+function isSelectOptionPayload(payload: unknown): boolean {
+  const validOptions = ['value', 'label', 'values'];
+
+  if (!isObject(payload)) throw new Error('You must provide a `SelectOptionPayload` object');
+
+  if (!payload.selector || typeof payload.selector !== 'string') {
+    throw new Error(`You must provide a selector representing the select you wish to locate`);
+  }
+
+  const numberOfValidOptions = Object.keys(payload).filter(key =>
+    validOptions.includes(key),
+  ).length;
+  const unknownOptions = Object.keys(payload).filter(
+    key => ![...validOptions, 'selector'].includes(key),
+  );
+
+  if (numberOfValidOptions === 0)
+    throw new Error(
+      `You must provide one of the following properties to pass to the browser runner: ${validOptions.join(
+        ', ',
+      )}.`,
+    );
+  if (unknownOptions.length > 0) {
+    throw new Error('Unknown options `' + unknownOptions.join(', ') + '` present.');
+  }
+  return true;
+}
+
+function isValuePayload(payload: SelectOptionPayload): payload is SelectByValuePayload {
+  return 'selector' in payload && 'value' in payload;
+}
+
+function isLabelPayload(payload: SelectOptionPayload): payload is SelectByLabelPayload {
+  return 'selector' in payload && 'label' in payload;
+}
+
+function isMultiplePayload(payload: SelectOptionPayload): payload is SelectMultipleValuesPayload {
+  return 'selector' in payload && 'values' in payload;
+}
+
+export function selectOptionPlugin(): TestRunnerPlugin<SelectOptionPayload> {
+  return {
+    name: 'select-option-command',
+    async executeCommand({ command, payload, session }): Promise<any> {
+      if (command === 'select-option') {
+        if (!isSelectOptionPayload(payload) || !payload) {
+          throw new Error('You must provide a `SelectOptionPayload` object');
+        }
+        // handle specific behavior for playwright
+        if (session.browser.type === 'playwright') {
+          const page = (session.browser as PlaywrightLauncher).getPage(session.id);
+          if (isValuePayload(payload)) {
+            const { selector, value } = payload;
+            await page.locator(selector).selectOption(value);
+            return true;
+          } else if (isLabelPayload(payload)) {
+            const { selector, label } = payload;
+            await page.locator(selector).selectOption({ label });
+            return true;
+          } else if (isMultiplePayload(payload)) {
+            const { selector, values } = payload;
+            await page.locator(selector).selectOption([...values]);
+            return true;
+          }
+        }
+
+        // handle specific behavior for puppeteer
+        if (session.browser.type === 'puppeteer') {
+          const page = (session.browser as ChromeLauncher).getPage(session.id);
+          if (isValuePayload(payload)) {
+            const { selector, value } = payload;
+            await page.select(selector, value);
+            return true;
+          } else if (isMultiplePayload(payload)) {
+            const { selector, values } = payload;
+            await page.select(selector, ...values);
+            return true;
+          } else {
+            throw new Error(`Puppeteer only supports selection of an option by its value(s):
+            https://pptr.dev/next/api/puppeteer.page.select#parameters
+            `);
+          }
+        }
+
+        // handle specific behavior for webdriver
+        if (session.browser.type === 'webdriver') {
+          throw new Error(`Selecting an option via a browser driver command is not currently implemented in WebDriver yet.
+            https://www.selenium.dev/documentation/webdriver/elements/select_lists/
+            
+            When using WebDriver, the current recommended (September 2022) approach is to:
+            - locate your select element (via querySelector or querySelectorAll)
+            - focus the element
+            - use sendKeys() to type the label of the option you wish to select
+            - use select.dispatchEvent(new Event('change')) to trigger a change event on the select.
+            `);
+        }
+
+        // you might not be able to support all browser launchers
+        throw new Error(
+          `Selection of select element options is not supported for browser type ${session.browser.type}.`,
+        );
+      }
+    },
+  };
+}

package/src/sendKeysPlugin.ts

@@ -0,0 +1,124 @@
+import { TestRunnerPlugin } from '@web/test-runner-core';
+import type { ChromeLauncher, puppeteerCore } from '@web/test-runner-chrome';
+import type { PlaywrightLauncher } from '@web/test-runner-playwright';
+import type { WebdriverLauncher } from '@web/test-runner-webdriver';
+
+type TypePayload = { type: string };
+type PressPayload = { press: string };
+type DownPayload = { down: string };
+type UpPayload = { up: string };
+
+export type SendKeysPayload = TypePayload | PressPayload | DownPayload | UpPayload;
+
+function isObject(payload: unknown): payload is Record<string, unknown> {
+  return payload != null && typeof payload === 'object';
+}
+
+function isSendKeysPayload(payload: unknown): boolean {
+  const validOptions = ['type', 'press', 'down', 'up'];
+
+  if (!isObject(payload)) throw new Error('You must provide a `SendKeysPayload` object');
+
+  const numberOfValidOptions = Object.keys(payload).filter(key =>
+    validOptions.includes(key),
+  ).length;
+  const unknownOptions = Object.keys(payload).filter(key => !validOptions.includes(key));
+
+  if (numberOfValidOptions > 1)
+    throw new Error(
+      `You must provide ONLY one of the following properties to pass to the browser runner: ${validOptions.join(
+        ', ',
+      )}.`,
+    );
+  if (numberOfValidOptions === 0)
+    throw new Error(
+      `You must provide one of the following properties to pass to the browser runner: ${validOptions.join(
+        ', ',
+      )}.`,
+    );
+  if (unknownOptions.length > 0) {
+    throw new Error('Unknown options `' + unknownOptions.join(', ') + '` present.');
+  }
+  return true;
+}
+
+function isTypePayload(payload: SendKeysPayload): payload is TypePayload {
+  return 'type' in payload;
+}
+
+function isPressPayload(payload: SendKeysPayload): payload is PressPayload {
+  return 'press' in payload;
+}
+
+function isDownPayload(payload: SendKeysPayload): payload is DownPayload {
+  return 'down' in payload;
+}
+
+function isUpPayload(payload: SendKeysPayload): payload is UpPayload {
+  return 'up' in payload;
+}
+
+export function sendKeysPlugin(): TestRunnerPlugin<SendKeysPayload> {
+  return {
+    name: 'send-keys-command',
+    async executeCommand({ command, payload, session }): Promise<any> {
+      if (command === 'send-keys') {
+        if (!isSendKeysPayload(payload) || !payload) {
+          throw new Error('You must provide a `SendKeysPayload` object');
+        }
+        // handle specific behavior for playwright
+        if (session.browser.type === 'playwright') {
+          const page = (session.browser as PlaywrightLauncher).getPage(session.id);
+          if (isTypePayload(payload)) {
+            await page.keyboard.type(payload.type);
+            return true;
+          } else if (isPressPayload(payload)) {
+            await page.keyboard.press(payload.press);
+            return true;
+          } else if (isDownPayload(payload)) {
+            await page.keyboard.down(payload.down);
+            return true;
+          } else if (isUpPayload(payload)) {
+            await page.keyboard.up(payload.up);
+            return true;
+          }
+        }
+
+        // handle specific behavior for puppeteer
+        if (session.browser.type === 'puppeteer') {
+          const page = (session.browser as ChromeLauncher).getPage(session.id);
+          if (isTypePayload(payload)) {
+            await page.keyboard.type(payload.type);
+            return true;
+          } else if (isPressPayload(payload)) {
+            await page.keyboard.press(payload.press as puppeteerCore.KeyInput);
+            return true;
+          } else if (isDownPayload(payload)) {
+            await page.keyboard.down(payload.down as puppeteerCore.KeyInput);
+            return true;
+          } else if (isUpPayload(payload)) {
+            await page.keyboard.up(payload.up as puppeteerCore.KeyInput);
+            return true;
+          }
+        }
+
+        // handle specific behavior for webdriver
+        if (session.browser.type === 'webdriver') {
+          const browser = session.browser as WebdriverLauncher;
+          if (isTypePayload(payload)) {
+            await browser.sendKeys(session.id, payload.type.split(''));
+            return true;
+          } else if (isPressPayload(payload)) {
+            await browser.sendKeys(session.id, [payload.press]);
+            return true;
+          } else {
+            throw new Error('Only "press" and "type" are supported by webdriver.');
+          }
+        }
+
+        // you might not be able to support all browser launchers
+        throw new Error(`Sending keys is not supported for browser type ${session.browser.type}.`);
+      }
+    },
+  };
+}

package/src/sendMousePlugin.ts

@@ -0,0 +1,191 @@
+import { TestRunnerPlugin } from '@web/test-runner-core';
+import type { ChromeLauncher } from '@web/test-runner-chrome';
+import type { PlaywrightLauncher } from '@web/test-runner-playwright';
+import type { WebdriverLauncher } from '@web/test-runner-webdriver';
+
+type MousePosition = [number, number];
+type MouseButton = 'left' | 'middle' | 'right';
+
+export type SendMousePayload = MovePayload | ClickPayload | DownPayload | UpPayload;
+
+export type MovePayload = {
+  type: 'move';
+  position: MousePosition;
+};
+
+export type ClickPayload = {
+  type: 'click';
+  position: MousePosition;
+  button?: MouseButton;
+};
+
+export type DownPayload = {
+  type: 'down';
+  button?: MouseButton;
+};
+
+export type UpPayload = {
+  type: 'up';
+  button?: MouseButton;
+};
+
+function isObject(payload: unknown): payload is Record<string, unknown> {
+  return payload != null && typeof payload === 'object';
+}
+
+function isSendMousePayload(payload: unknown): payload is SendMousePayload {
+  const validTypes = ['move', 'click', 'down', 'up'];
+  const validButtons = ['left', 'middle', 'right'];
+
+  if (!isObject(payload)) {
+    throw new Error('You must provide a `SendMousePayload` object');
+  }
+
+  if (typeof payload.type !== 'string' || !validTypes.includes(payload.type)) {
+    throw new Error(
+      `You must provide a type option with one of the following values: ${validTypes.join(', ')}.`,
+    );
+  }
+
+  if (['click', 'move'].includes(payload.type)) {
+    if (
+      !Array.isArray(payload.position) ||
+      typeof payload.position[0] !== 'number' ||
+      typeof payload.position[1] !== 'number' ||
+      !Number.isInteger(payload.position[0]) ||
+      !Number.isInteger(payload.position[1])
+    ) {
+      throw new Error(
+        'You must provide a position option as a [x, y] tuple where x and y are integers.',
+      );
+    }
+  }
+
+  if (['click', 'up', 'down'].includes(payload.type)) {
+    if (typeof payload.button === 'string' && !validButtons.includes(payload.button)) {
+      throw new Error(
+        `The button option must be one of the following values when provided: ${validButtons.join(
+          ', ',
+        )}.`,
+      );
+    }
+  }
+
+  return true;
+}
+
+export function sendMousePlugin(): TestRunnerPlugin<SendMousePayload> {
+  return {
+    name: 'send-mouse-command',
+    async executeCommand({ command, payload, session }): Promise<any> {
+      if (command === 'send-mouse') {
+        if (!payload || !isSendMousePayload(payload)) {
+          throw new Error('You must provide a `SendMousePayload` object');
+        }
+
+        // handle specific behavior for playwright
+        if (session.browser.type === 'playwright') {
+          const page = (session.browser as PlaywrightLauncher).getPage(session.id);
+          switch (payload.type) {
+            case 'move':
+              await page.mouse.move(payload.position[0], payload.position[1]);
+              return true;
+            case 'click':
+              await page.mouse.click(payload.position[0], payload.position[1], {
+                button: payload.button,
+              });
+              return true;
+            case 'down':
+              await page.mouse.down({ button: payload.button });
+              return true;
+            case 'up':
+              await page.mouse.up({ button: payload.button });
+              return true;
+          }
+        }
+
+        // handle specific behavior for puppeteer
+        if (session.browser.type === 'puppeteer') {
+          const page = (session.browser as ChromeLauncher).getPage(session.id);
+          switch (payload.type) {
+            case 'move':
+              await page.mouse.move(payload.position[0], payload.position[1]);
+              return true;
+            case 'click':
+              await page.mouse.click(payload.position[0], payload.position[1], {
+                button: payload.button,
+              });
+              return true;
+            case 'down':
+              await page.mouse.down({ button: payload.button });
+              return true;
+            case 'up':
+              await page.mouse.up({ button: payload.button });
+              return true;
+          }
+        }
+
+        // handle specific behavior for webdriver
+        if (session.browser.type === 'webdriver') {
+          const page = session.browser as WebdriverLauncher;
+          switch (payload.type) {
+            case 'move':
+              await page.sendMouseMove(session.id, payload.position[0], payload.position[1]);
+              return true;
+            case 'click':
+              await page.sendMouseClick(
+                session.id,
+                payload.position[0],
+                payload.position[1],
+                payload.button,
+              );
+              return true;
+            case 'down':
+              await page.sendMouseDown(session.id, payload.button);
+              return true;
+            case 'up':
+              await page.sendMouseUp(session.id, payload.button);
+              return true;
+          }
+        }
+
+        // you might not be able to support all browser launchers
+        throw new Error(`Sending mouse is not supported for browser type ${session.browser.type}.`);
+      }
+
+      if (command === 'reset-mouse') {
+        // handle specific behavior for playwright
+        if (session.browser.type === 'playwright') {
+          const page = (session.browser as PlaywrightLauncher).getPage(session.id);
+          await page.mouse.up({ button: 'left' });
+          await page.mouse.up({ button: 'middle' });
+          await page.mouse.up({ button: 'right' });
+          await page.mouse.move(0, 0);
+          return true;
+        }
+
+        // handle specific behavior for puppeteer
+        if (session.browser.type === 'puppeteer') {
+          const page = (session.browser as ChromeLauncher).getPage(session.id);
+          await page.mouse.up({ button: 'left' });
+          await page.mouse.up({ button: 'middle' });
+          await page.mouse.up({ button: 'right' });
+          await page.mouse.move(0, 0);
+          return true;
+        }
+
+        // handle specific behavior for webdriver
+        if (session.browser.type === 'webdriver') {
+          const page = session.browser as WebdriverLauncher;
+          await page.resetMouse(session.id);
+          return true;
+        }
+
+        // you might not be able to support all browser launchers
+        throw new Error(
+          `Resetting mouse is not supported for browser type ${session.browser.type}.`,
+        );
+      }
+    },
+  };
+}

package/src/setUserAgentPlugin.ts

@@ -0,0 +1,25 @@
+import { TestRunnerPlugin } from '@web/test-runner-core';
+import type { ChromeLauncher } from '@web/test-runner-chrome';
+
+export function setUserAgentPlugin(): TestRunnerPlugin {
+  return {
+    name: 'set-user-agent-command',
+
+    async executeCommand({ command, payload, session }) {
+      if (command === 'set-user-agent') {
+        if (typeof payload !== 'string') {
+          throw new Error('You must provide a user agent as a string');
+        }
+
+        if (session.browser.type === 'puppeteer') {
+          const page = (session.browser as ChromeLauncher).getPage(session.id);
+
+          await page.setUserAgent(payload);
+          return true;
+        }
+
+        throw new Error('set user agent is only supported on puppeteer.');
+      }
+    },
+  };
+}

package/src/setViewportPlugin.ts

@@ -0,0 +1,59 @@
+import { TestRunnerPlugin } from '@web/test-runner-core';
+import type { ChromeLauncher } from '@web/test-runner-chrome';
+import type { PlaywrightLauncher } from '@web/test-runner-playwright';
+
+export interface Viewport {
+  width: number;
+  height: number;
+
+  // puppeteer only
+  deviceScaleFactor?: number;
+  isLandscape?: boolean;
+}
+
+function isObject(payload: unknown): payload is Record<string, unknown> {
+  return payload != null && typeof payload === 'object';
+}
+
+function isViewportObject(payload: unknown): payload is { width: number; height: number } {
+  if (!isObject(payload)) throw new Error('You must provide a viewport object');
+  if (payload.height == null) throw new Error('You must provide a viewport width');
+  if (payload.width == null) throw new Error('You must provide a viewport width');
+  if (typeof payload.height !== 'number') throw new Error('Viewport height must be a number');
+  if (typeof payload.height !== 'number') throw new Error('Viewport width must be a number');
+  if (payload.isMobile != null)
+    throw new Error('isMobile cannot be used because it triggers a page reload');
+  if (payload.hasTouch != null)
+    throw new Error('hasTouch cannot be used because it triggers a page reload');
+  return true;
+}
+
+export function setViewportPlugin(): TestRunnerPlugin {
+  return {
+    name: 'set-viewport-command',
+
+    async executeCommand({ command, payload, session }) {
+      if (command === 'set-viewport') {
+        if (!isViewportObject(payload)) {
+          throw new Error('You must provide a viewport object');
+        }
+
+        if (session.browser.type === 'puppeteer') {
+          const page = (session.browser as ChromeLauncher).getPage(session.id);
+          await page.setViewport(payload);
+          return true;
+        }
+
+        if (session.browser.type === 'playwright') {
+          const page = (session.browser as PlaywrightLauncher).getPage(session.id);
+          await page.setViewportSize(payload);
+          return true;
+        }
+
+        throw new Error(
+          `Setting viewport is not supported for browser type ${session.browser.type}.`,
+        );
+      }
+    },
+  };
+}