feat: add Drag step type

package.json

@@ -52,41 +52,41 @@
   "license": "Apache-2.0",
   "type": "module",
   "devDependencies": {
-    "@rollup/plugin-commonjs": "25.0.3",
-    "@rollup/plugin-node-resolve": "15.1.0",
-    "@rollup/plugin-typescript": "11.1.2",
-    "@types/chai": "4.3.3",
+    "@rollup/plugin-commonjs": "25.0.4",
+    "@rollup/plugin-node-resolve": "15.2.1",
+    "@rollup/plugin-typescript": "11.1.3",
+    "@types/chai": "4.3.6",
     "@types/cssesc": "^3.0.0",
     "@types/mime": "3.0.1",
     "@types/mocha": "10.0.1",
-    "@types/node": "20.4.6",
+    "@types/node": "20.6.2",
     "@types/ws": "8.5.5",
     "@types/yargs": "17.0.24",
-    "@typescript-eslint/eslint-plugin": "6.2.1",
-    "@typescript-eslint/parser": "6.2.1",
+    "@typescript-eslint/eslint-plugin": "6.7.2",
+    "@typescript-eslint/parser": "6.7.2",
     "c8": "8.0.1",
-    "chai": "4.3.7",
+    "chai": "4.3.8",
     "cross-env": "7.0.3",
-    "eslint": "8.46.0",
+    "eslint": "8.49.0",
     "eslint-config-google": "0.14.0",
-    "eslint-config-prettier": "8.10.0",
+    "eslint-config-prettier": "9.0.0",
     "eslint-plugin-prettier": "5.0.0",
     "eslint-plugin-tsdoc": "0.2.17",
-    "lighthouse": "^10.0.1",
+    "lighthouse": "^11.1.0",
     "mime": "3.0.0",
     "mocha": "10.2.0",
-    "prettier": "3.0.1",
-    "puppeteer": "21.2.1",
-    "puppeteer-core": "21.1.1",
+    "prettier": "3.0.3",
+    "puppeteer": "21.3.0",
+    "puppeteer-core": "21.3.0",
     "rimraf": "5.0.1",
-    "rollup": "3.27.1",
-    "rollup-plugin-dts": "5.3.1",
+    "rollup": "3.29.2",
+    "rollup-plugin-dts": "6.0.2",
     "snap-shot-it": "7.9.10",
     "ts-node": "10.9.1",
-    "tslib": "2.6.1",
-    "typedoc": "0.24.8",
-    "typedoc-plugin-markdown": "3.15.4",
-    "typescript": "5.1.6"
+    "tslib": "2.6.2",
+    "typedoc": "0.25.1",
+    "typedoc-plugin-markdown": "3.16.0",
+    "typescript": "5.2.2"
   },
   "peerDependencies": {
     "lighthouse": ">=10.0.0",

rollup.config.cjs

@@ -19,7 +19,7 @@ module.exports = [
       },
     ],
     external: Object.keys(pkg.peerDependencies),
-    plugins: [typescript({ module: 'NodeNext' })],
+    plugins: [typescript({ module: 'NodeNext', moduleResolution: 'NodeNext' })],
   },
   {
     input: 'src/main.ts',

src/PuppeteerRunnerExtension.ts

@@ -13,15 +13,9 @@
     See the License for the specific language governing permissions and
     limitations under the License.
  */
-import type {
-  Browser,
-  ElementHandle,
-  Frame,
-  LocatorEmittedEvents,
-  Page,
-} from 'puppeteer';
-import { Frame as InternalFrame } from 'puppeteer-core/internal/common/Frame.js';
-import { CDPPage as InternalPage } from 'puppeteer-core/internal/common/Page.js';
+import type { Browser, ElementHandle, Frame, Page } from 'puppeteer';
+import { CdpFrame as InternalFrame } from 'puppeteer-core/internal/cdp/Frame.js';
+import { CdpPage as InternalPage } from 'puppeteer-core/internal/cdp/Page.js';
 import { RunnerExtension } from './RunnerExtension.js';
 import {
   AssertedEventType,
@@ -33,8 +27,8 @@ import {
 } from './Schema.js';
 import {
   assertAllStepTypesAreHandled,
-  selectorToPElementSelector,
   mouseButtonMap,
+  selectorToPElementSelector,
 } from './SchemaUtils.js';
 
 const comparators = {
@@ -130,9 +124,7 @@ export class PuppeteerRunnerExtension extends RunnerExtension {
           })
         )
           .setTimeout(timeout)
-          .on('action' as LocatorEmittedEvents.Action, () =>
-            startWaitingForEvents()
-          )
+          .on('action', () => startWaitingForEvents())
           .click({
             count: 2,
             button: step.button && mouseButtonMap.get(step.button),
@@ -152,9 +144,7 @@ export class PuppeteerRunnerExtension extends RunnerExtension {
           })
         )
           .setTimeout(timeout)
-          .on('action' as LocatorEmittedEvents.Action, () =>
-            startWaitingForEvents()
-          )
+          .on('action', () => startWaitingForEvents())
           .click({
             delay: step.duration,
             button: step.button && mouseButtonMap.get(step.button),
@@ -164,6 +154,24 @@ export class PuppeteerRunnerExtension extends RunnerExtension {
             },
           });
         break;
+      case StepType.Drag: {
+        let [x, y] = [step.offsetX, step.offsetY];
+        await mainPage.mouse.move(x, y);
+        await mainPage.mouse.down({
+          button: step.button && mouseButtonMap.get(step.button),
+        });
+        for (let i = 0; i < step.deltas.length; i += 2) {
+          [x, y] = [
+            x + (step.deltas[i] as number),
+            y + (step.deltas[i + 1] as number),
+          ];
+          await mainPage.mouse.move(x, y);
+        }
+        await mainPage.mouse.up({
+          button: step.button && mouseButtonMap.get(step.button),
+        });
+        break;
+      }
       case StepType.Hover:
         await locatorRace(
           step.selectors.map((selector) => {
@@ -173,9 +181,7 @@ export class PuppeteerRunnerExtension extends RunnerExtension {
           })
         )
           .setTimeout(timeout)
-          .on('action' as LocatorEmittedEvents.Action, () =>
-            startWaitingForEvents()
-          )
+          .on('action', () => startWaitingForEvents())
           .hover();
         break;
       case StepType.EmulateNetworkConditions:
@@ -214,9 +220,7 @@ export class PuppeteerRunnerExtension extends RunnerExtension {
             );
           })
         )
-          .on('action' as LocatorEmittedEvents.Action, () =>
-            startWaitingForEvents()
-          )
+          .on('action', () => startWaitingForEvents())
           .setTimeout(timeout)
           .fill(step.value);
         break;
@@ -236,9 +240,7 @@ export class PuppeteerRunnerExtension extends RunnerExtension {
               );
             })
           )
-            .on('action' as LocatorEmittedEvents.Action, () =>
-              startWaitingForEvents()
-            )
+            .on('action', () => startWaitingForEvents())
             .setTimeout(timeout)
             .scroll({
               scrollLeft: step.x || 0,

src/PuppeteerStringifyExtension.ts

@@ -24,6 +24,7 @@ import type {
   HoverStep,
   KeyDownStep,
   KeyUpStep,
+  DragStep,
   NavigateStep,
   ScrollStep,
   SetViewportStep,
@@ -302,6 +303,8 @@ export class PuppeteerStringifyExtension extends StringifyExtension {
         return this.#appendScrollStep(out, step);
       case StepType.Navigate:
         return this.#appendNavigationStep(out, step);
+      case StepType.Drag:
+        return this.#appendDragStep(out, step);
       case StepType.WaitForElement:
         return this.#appendWaitForElementStep(out, step);
       case StepType.WaitForExpression:
@@ -322,6 +325,21 @@ export class PuppeteerStringifyExtension extends StringifyExtension {
     );
   }
 
+  #appendDragStep(out: LineWriter, step: DragStep): void {
+    out.appendLine(`
+{
+  const deltas = new Int8Array("${step.deltas.toString()}".split(","));
+
+  let [x, y] = [${step.offsetX}, ${step.offsetY}];
+  await targetPage.mouse.move(x, y);
+  for (let i = 0; i < deltas.length; i += 2) {
+    [x, y] = [x + deltas[i], y + deltas[i + 1]];
+    await targetPage.mouse.move(x, y);
+  }
+}
+`);
+  }
+
   #appendWaitExpressionStep(
     out: LineWriter,
     step: WaitForExpressionStep

src/Schema.ts

@@ -40,6 +40,7 @@ export enum StepType {
   KeyDown = 'keyDown',
   KeyUp = 'keyUp',
   Navigate = 'navigate',
+  Drag = 'move',
   Scroll = 'scroll',
   SetViewport = 'setViewport',
   WaitForElement = 'waitForElement',
@@ -110,11 +111,13 @@ export type PointerButtonType =
 
 export interface ClickAttributes {
   /**
-   * Pointer type for the event. Defaults to 'mouse'.
+   * Pointer type for the event.
+   *
+   * @defaultValue `'mouse'`
    */
   deviceType?: PointerDeviceType;
   /**
-   * Defaults to 'primary' if the device type is a mouse.
+   * @defaultValue `'primary'` if the {@link deviceType} is `'mouse'`.
    */
   button?: PointerButtonType;
   /**
@@ -141,6 +144,22 @@ export interface DoubleClickStep extends ClickAttributes, StepWithSelectors {
 
 export interface ClickStep extends ClickAttributes, StepWithSelectors {
   type: StepType.Click;
+  /**
+   * Delay (in ms) between the mouse up and mouse down of the click.
+   *
+   * @defaultValue `50`
+   */
+  duration?: number;
+}
+
+export interface DragStep extends ClickAttributes, StepWithTarget {
+  type: StepType.Drag;
+  /**
+   * An flattened array of (offsetX, offsetY)-deltas to defining the movement.
+   *
+   * @defaultValue `[]`
+   */
+  deltas: Int8Array;
 }
 
 export interface HoverStep extends StepWithSelectors {
@@ -224,6 +243,7 @@ export type UserStep =
   | EmulateNetworkConditionsStep
   | KeyDownStep
   | KeyUpStep
+  | DragStep
   | NavigateStep
   | ScrollStep
   | SetViewportStep;

src/SchemaUtils.ts

@@ -29,6 +29,7 @@ import {
   Key,
   KeyDownStep,
   KeyUpStep,
+  DragStep,
   NavigateStep,
   ScrollStep,
   Selector,
@@ -154,6 +155,21 @@ function parseNumber(step: object, prop: string): number {
   throw new Error(`Step.${prop} is not a number`);
 }
 
+function parseInt8Array(step: object, prop: string): Int8Array {
+  if (hasProperty(step, prop)) {
+    const value = step[prop];
+    if (value instanceof Int8Array) {
+      return value;
+    } else if (isIntegerArray(value)) {
+      return new Int8Array(value);
+    } else if (isString(value)) {
+      // The Int8Array constructor automatically does the number conversion.
+      return new Int8Array(value.split(',') as unknown as number[]);
+    }
+  }
+  throw new Error(`Step.${prop} is not an typed byte array`);
+}
+
 function parseBoolean(step: object, prop: string): boolean {
   if (hasProperty(step, prop)) {
     const maybeBoolean = step[prop];
@@ -427,6 +443,16 @@ function parseNavigateStep(step: object): NavigateStep {
   };
 }
 
+function parseDragStep(step: object): DragStep {
+  return {
+    ...parseStepWithTarget(StepType.Drag, step),
+    type: StepType.Drag,
+    offsetX: parseNumber(step, 'offsetX'),
+    offsetY: parseNumber(step, 'offsetY'),
+    deltas: parseInt8Array(step, 'deltas'),
+  };
+}
+
 function parseWaitForElementStep(step: object): WaitForElementStep {
   const operator = parseOptionalString(step, 'operator');
   if (operator && operator !== '>=' && operator !== '==' && operator !== '<=') {
@@ -533,6 +559,8 @@ export function parseStep(step: unknown, idx?: number): Step {
       return parseScrollStep(step);
     case StepType.Navigate:
       return parseNavigateStep(step);
+    case StepType.Drag:
+      return parseDragStep(step);
     case StepType.CustomStep:
       return parseCustomStep(step);
     case StepType.WaitForElement:

test/SchemaUtils.test.ts

@@ -14,15 +14,15 @@
     limitations under the License.
  */
 
+import { assert } from 'chai';
+import puppeteer, { Browser, Page } from 'puppeteer';
+import snapshot from 'snap-shot-it';
+import { AssertedEventType, SelectorType, StepType } from '../src/Schema.js';
 import {
-  parse,
   getSelectorType,
+  parse,
   selectorToPElementSelector,
 } from '../src/SchemaUtils.js';
-import { AssertedEventType, SelectorType, StepType } from '../src/Schema.js';
-import { assert } from 'chai';
-import snapshot from 'snap-shot-it';
-import puppeteer from 'puppeteer';
 
 describe('SchemaUtils', () => {
   describe('Schema parser', () => {
@@ -816,8 +816,8 @@ describe('SchemaUtils', () => {
     });
 
     describe('selectorToPElementSelector', () => {
-      let browser: puppeteer.Browser;
-      let page: puppeteer.Page;
+      let browser: Browser;
+      let page: Page;
 
       before(async () => {
         browser = await puppeteer.launch({

test/resources/drawable-canvas.html

@@ -0,0 +1,22 @@
+<canvas width="100" height="100"></canvas>
+<script>
+  const canvas = document.querySelector('canvas');
+
+  // Drawing code.
+  const context = canvas.getContext('2d');
+  window.addEventListener('pointerdown', (event) => {
+    context.beginPath();
+    context.moveTo(event.offsetX, event.offsetY);
+    const handlePointerMove = (event) => {
+      context.lineTo(event.offsetX, event.offsetY);
+      context.stroke();
+    };
+
+    const handlePointerUp = () => {
+      window.removeEventListener('pointermove', handlePointerMove);
+      window.removeEventListener('pointerup', handlePointerUp);
+    };
+    window.addEventListener('pointermove', handlePointerMove);
+    window.addEventListener('pointerup', handlePointerUp);
+  });
+</script>