feat: add resetMouse command (#1819)

Author: vursen

.changeset/shy-singers-love.md

@@ -0,0 +1,6 @@
+---
+'@web/test-runner-commands': minor
+'@web/test-runner-webdriver': minor
+---
+
+Add a resetMouse command that resets the mouse position and releases mouse buttons.

packages/test-runner-commands/browser/commands.d.ts

@@ -76,9 +76,15 @@ export function setUserAgent(userAgent: string): Promise<void>;
 export function sendKeys(payload: SendKeysPayload): Promise<void>;
 
 /**
- * Sends an action for the mouse to move it to a specific position or click a mouse button (left, middle or right).
+ * Sends an action for the mouse to move it to a specific position or click a mouse button (left, middle, or right).
  *
- * @param payload An object representing a mouse action specified by the `type` property (move, click, down, up) and including properties permitted for this type.
+ * WARNING: When moving the mouse or holding down a mouse button, the mouse stays in this state as long as
+ * you do not explicitly move it to another position or release the button. For this reason, it is recommended
+ * to reset the mouse state with the `resetMouse` command after each test case manipulating the mouse to avoid
+ * unexpected side effects.
+ *
+ * @param payload An object representing a mouse action specified by the `type` property (move, click, down, up)
+ *     and including some properties to configure this action.
  *
  * @example
  * ```ts
@@ -107,6 +113,25 @@ export function sendKeys(payload: SendKeysPayload): Promise<void>;
  **/
 export function sendMouse(payload: SendMousePayload): Promise<void>;
 
+/**
+ * Resets the mouse position to (0, 0) and releases mouse buttons.
+ *
+ * Use this command to reset the mouse state after mouse manipulations by the `sendMouse` command.
+ *
+ * @example
+ * ```
+ * it('does something with the mouse', () => {
+ *   await sendMouse({ type: 'move', position: [150, 150] });
+ *   await sendMouse({ type: 'down', button: 'middle' });
+ * });
+ *
+ * afterEach(() => {
+ *   await resetMouse();
+ * });
+ * ```
+ */
+export function resetMouse(): Promise<void>;
+
 /**
  * Request a snapshot of the Accessibility Tree of the entire page or starting from
  * the element that is obtained via the `selector` property of the `payload` argument.

packages/test-runner-commands/browser/commands.mjs

@@ -73,6 +73,10 @@ export function sendMouse(options) {
   return executeServerCommand('send-mouse', options);
 }
 
+export function resetMouse(options) {
+  return executeServerCommand('reset-mouse', options);
+}
+
 export function a11ySnapshot(options) {
   return executeServerCommand('a11y-snapshot', options);
 }

packages/test-runner-commands/src/sendMousePlugin.ts

@@ -152,6 +152,40 @@ export function sendMousePlugin(): TestRunnerPlugin<SendMousePayload> {
         // 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}.`,
+        );
+      }
     },
   };
 }

packages/test-runner-commands/test/send-mouse/browser-test.js

@@ -1,4 +1,4 @@
-import { sendMouse } from '../../browser/commands.mjs';
+import { sendMouse, resetMouse } from '../../browser/commands.mjs';
 import { expect } from '../chai.js';
 
 function spyEvent() {
@@ -14,8 +14,6 @@ function spyEvent() {
   return callback;
 }
 
-let element, x, y;
-
 before(() => {
   // The native context menu needs to be prevented from opening at least in WebKit
   // where it doesn't get automatically closed that, in turn, blocks the next `mouseup` event.
@@ -24,145 +22,180 @@ before(() => {
   });
 });
 
-beforeEach(() => {
-  element = document.createElement('div');
-  element.style.width = '100px';
-  element.style.height = '100px';
-  element.style.margin = '100px';
-
-  x = 150; // Horizontal middle of the element.
-  y = 150; // Vertical middle of the element.
-
-  document.body.appendChild(element);
-});
+describe('sendMouse', () => {
+  let element, x, y;
 
-afterEach(() => {
-  element.remove();
-});
+  beforeEach(() => {
+    element = document.createElement('div');
+    element.style.width = '100px';
+    element.style.height = '100px';
+    element.style.margin = '100px';
 
-describe('move', () => {
-  let spy;
+    x = 150; // Horizontal middle of the element.
+    y = 150; // Vertical middle of the element.
 
-  beforeEach(() => {
-    spy = spyEvent();
-    document.addEventListener('mousemove', spy);
+    document.body.appendChild(element);
   });
 
   afterEach(() => {
-    document.removeEventListener('mousemove', spy);
+    element.remove();
   });
 
-  it('can move mouse to a position', async () => {
-    await sendMouse({ type: 'move', position: [x, y] });
+  describe('move', () => {
+    let spy;
 
-    expect(spy.getLastEvent()).to.include({ x, y });
-  });
-});
+    beforeEach(() => {
+      spy = spyEvent();
+      document.addEventListener('mousemove', spy);
+    });
 
-describe('click', () => {
-  let spy;
+    afterEach(() => {
+      document.removeEventListener('mousemove', spy);
+    });
 
-  beforeEach(async () => {
-    spy = spyEvent();
-    element.addEventListener('mousedown', spy);
-    element.addEventListener('mouseup', spy);
+    it('can move mouse to a position', async () => {
+      await sendMouse({ type: 'move', position: [x, y] });
 
-    await sendMouse({ type: 'move', position: [0, 0] });
+      expect(spy.getLastEvent()).to.include({ x, y });
+    });
   });
 
-  it('can click the left mouse button', async () => {
-    await sendMouse({ type: 'click', position: [x, y], button: 'left' });
+  describe('click', () => {
+    let spy;
 
-    expect(spy.getEvents()).to.have.lengthOf(2);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
-    expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 0, x, y });
-  });
+    beforeEach(async () => {
+      spy = spyEvent();
+      element.addEventListener('mousedown', spy);
+      element.addEventListener('mouseup', spy);
 
-  it('should click the left mouse button by default', async () => {
-    await sendMouse({ type: 'click', position: [x, y] });
+      await sendMouse({ type: 'move', position: [0, 0] });
+    });
 
-    expect(spy.getEvents()).to.have.lengthOf(2);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
-    expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 0, x, y });
-  });
+    it('can click the left mouse button', async () => {
+      await sendMouse({ type: 'click', position: [x, y], button: 'left' });
 
-  it('can click the middle mouse button', async () => {
-    await sendMouse({ type: 'click', position: [x, y], button: 'middle' });
+      expect(spy.getEvents()).to.have.lengthOf(2);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
+      expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 0, x, y });
+    });
 
-    expect(spy.getEvents()).to.have.lengthOf(2);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 1, x, y });
-    expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 1, x, y });
-  });
+    it('should click the left mouse button by default', async () => {
+      await sendMouse({ type: 'click', position: [x, y] });
 
-  it('can click the right mouse button', async () => {
-    await sendMouse({ type: 'click', position: [x, y], button: 'right' });
+      expect(spy.getEvents()).to.have.lengthOf(2);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
+      expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 0, x, y });
+    });
 
-    expect(spy.getEvents()).to.have.lengthOf(2);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 2, x, y });
-    expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 2, x, y });
-  });
-});
+    it('can click the middle mouse button', async () => {
+      await sendMouse({ type: 'click', position: [x, y], button: 'middle' });
 
-describe('down and up', () => {
-  let spy;
+      expect(spy.getEvents()).to.have.lengthOf(2);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 1, x, y });
+      expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 1, x, y });
+    });
 
-  beforeEach(async () => {
-    spy = spyEvent();
-    element.addEventListener('mousedown', spy);
-    element.addEventListener('mouseup', spy);
+    it('can click the right mouse button', async () => {
+      await sendMouse({ type: 'click', position: [x, y], button: 'right' });
 
-    await sendMouse({ type: 'move', position: [x, y] });
+      expect(spy.getEvents()).to.have.lengthOf(2);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 2, x, y });
+      expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 2, x, y });
+    });
   });
 
-  it('can down and up the left mouse button', async () => {
-    await sendMouse({ type: 'down', button: 'left' });
+  describe('down and up', () => {
+    let spy;
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
+    beforeEach(async () => {
+      spy = spyEvent();
+      element.addEventListener('mousedown', spy);
+      element.addEventListener('mouseup', spy);
 
-    spy.resetHistory();
-    await sendMouse({ type: 'up', button: 'left' });
+      await sendMouse({ type: 'move', position: [x, y] });
+    });
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 0, x, y });
-  });
+    it('can down and up the left mouse button', async () => {
+      await sendMouse({ type: 'down', button: 'left' });
 
-  it('should down and up the left mouse button by default', async () => {
-    await sendMouse({ type: 'down' });
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
+      spy.resetHistory();
+      await sendMouse({ type: 'up', button: 'left' });
 
-    spy.resetHistory();
-    await sendMouse({ type: 'up' });
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 0, x, y });
+    });
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 0, x, y });
-  });
+    it('should down and up the left mouse button by default', async () => {
+      await sendMouse({ type: 'down' });
 
-  it('can down and up the middle mouse button', async () => {
-    await sendMouse({ type: 'down', button: 'middle' });
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 0, x, y });
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 1, x, y });
+      spy.resetHistory();
+      await sendMouse({ type: 'up' });
 
-    spy.resetHistory();
-    await sendMouse({ type: 'up', button: 'middle' });
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 0, x, y });
+    });
+
+    it('can down and up the middle mouse button', async () => {
+      await sendMouse({ type: 'down', button: 'middle' });
+
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 1, x, y });
+
+      spy.resetHistory();
+      await sendMouse({ type: 'up', button: 'middle' });
+
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 1, x, y });
+    });
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 1, x, y });
+    it('can down and up the right mouse button', async () => {
+      await sendMouse({ type: 'down', button: 'right' });
+
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 2, x, y });
+
+      spy.resetHistory();
+      await sendMouse({ type: 'up', button: 'right' });
+
+      expect(spy.getEvents()).to.have.lengthOf(1);
+      expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 2, x, y });
+    });
   });
+});
 
-  it('can down and up the right mouse button', async () => {
-    await sendMouse({ type: 'down', button: 'right' });
+describe('resetMouse', () => {
+  let spy;
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mousedown', button: 2, x, y });
+  beforeEach(() => {
+    spy = spyEvent();
+    document.addEventListener('mouseup', spy);
+    document.addEventListener('mousemove', spy);
+  });
+
+  afterEach(() => {
+    document.addEventListener('mouseup', spy);
+    document.removeEventListener('mousemove', spy);
+  });
+
+  it('can reset mouse', async () => {
+    await sendMouse({ type: 'move', position: [100, 100] });
+    await sendMouse({ type: 'down', button: 'left' });
+    await sendMouse({ type: 'down', button: 'right' });
+    await sendMouse({ type: 'down', button: 'middle' });
 
     spy.resetHistory();
-    await sendMouse({ type: 'up', button: 'right' });
+    await resetMouse();
 
-    expect(spy.getEvents()).to.have.lengthOf(1);
-    expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 2, x, y });
+    expect(spy.getEvents()).to.have.lengthOf(4);
+    expect(spy.getEvents()[0]).to.include({ type: 'mouseup', button: 0 });
+    expect(spy.getEvents()[1]).to.include({ type: 'mouseup', button: 1 });
+    expect(spy.getEvents()[2]).to.include({ type: 'mouseup', button: 2 });
+    expect(spy.getEvents()[3]).to.include({ type: 'mousemove', x: 0, y: 0 });
   });
 });

packages/test-runner-webdriver/src/webdriverLauncher.ts

@@ -203,6 +203,25 @@ export class WebdriverLauncher implements BrowserLauncher {
     ]);
   }
 
+  resetMouse(sessionId: string) {
+    if (!this.driverManager) {
+      throw new Error('Not initialized');
+    }
+
+    return this.driverManager.performActions(sessionId, [
+      {
+        type: 'pointer',
+        id: 'finger1',
+        actions: [
+          { type: 'pointerUp', button: getMouseButtonCode('left') },
+          { type: 'pointerUp', button: getMouseButtonCode('middle') },
+          { type: 'pointerUp', button: getMouseButtonCode('right') },
+          { type: 'pointerMove', duration: 0, x: 0, y: 0 },
+        ],
+      },
+    ]);
+  }
+
   sendKeys(sessionId: string, keys: string[]) {
     if (!this.driverManager) {
       throw new Error('Not initialized');