feat(mouse button): Allow to specify button option for `realMouseDown…

…` and `realMouseUp` (#201)

README.md

@@ -275,6 +275,7 @@ Options:
 - `Optional` **pointer**: \"mouse\" \| \"pen\"
 - `Optional` **position**: "topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"
 - `Optional` **scrollBehavior**: "center" | "top" | "bottom" | "nearest" | false
+- `Optional` **button**: "left" | "middle" | "right" | "back" | "forward" | "none"
 
 ## cy.realMouseUp
 
@@ -296,6 +297,7 @@ Options:
 - `Optional` **pointer**: \"mouse\" \| \"pen\"
 - `Optional` **position**: "topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"
 - `Optional` **scrollBehavior**: "center" | "top" | "bottom" | "nearest" | false
+- `Optional` **button**: "left" | "middle" | "right" | "back" | "forward" | "none"
 
 ## Coordinates
 

cypress/integration/mouse.spec.ts

@@ -36,6 +36,32 @@ describe("cy.realMouseDown and cy.realMouseUp", () => {
         .realMouseDown({ position: "bottomRight" })
         .realMouseUp({ position: "bottomRight" });
     });
+
+    describe("options.button", () => {
+      it("should allow to press down mouse using middle button", (done) => {
+        cy.get(".action-btn")
+          .then(($button) => {
+            $button.get(0).addEventListener("mousedown", (ev) => {
+              if (ev.button === 1) {
+                done();
+              }
+            });
+          })
+          .realMouseDown({ button: "middle" });
+      });
+
+      it("should allow to release mouse using middle button", (done) => {
+        cy.get(".action-btn")
+          .then(($button) => {
+            $button.get(0).addEventListener("mouseup", (ev) => {
+              if (ev.button === 1) {
+                done();
+              }
+            });
+          })
+          .realMouseUp({ button: "middle" });
+      });
+    });
 
     describe("realMouseDown scroll behavior", () => {
       function getScreenEdges() {

src/commands/mouseDown.ts

@@ -4,6 +4,7 @@ import {
   ScrollBehaviorOptions,
   Position,
 } from "../getCypressElementCoordinates";
+import { mouseButtonNumbers } from "../mouseButtonNumbers";
 
 export interface realMouseDownOptions {
   /** Pointer type for realMouseDown, if "pen" touch simulated */
@@ -18,6 +19,11 @@ export interface realMouseDownOptions {
    * @example cy.realMouseDown({ scrollBehavior: "top" });
    */
   scrollBehavior?: ScrollBehaviorOptions;
+
+  /**
+   * @default "left"
+   */
+  button?: keyof typeof mouseButtonNumbers;
 }
 
 /** @ignore this, update documentation for this function at index.d.ts */
@@ -42,9 +48,9 @@ export async function realMouseDown(
     x,
     y,
     clickCount: 1,
-    buttons: 1,
+    buttons: mouseButtonNumbers[options.button ?? "left"],
     pointerType: options.pointer ?? "mouse",
-    button: "left",
+    button: options.button ?? "left",
   });
 
   log.snapshot("after").end();

src/commands/mouseUp.ts

@@ -4,6 +4,7 @@ import {
   ScrollBehaviorOptions,
   Position,
 } from "../getCypressElementCoordinates";
+import { mouseButtonNumbers } from "../mouseButtonNumbers";
 
 export interface realMouseUpOptions {
   /** Pointer type for realMouseUp, if "pen" touch simulated */
@@ -18,6 +19,10 @@ export interface realMouseUpOptions {
    * @example cy.realMouseUp({ scrollBehavior: "top" });
    */
   scrollBehavior?: ScrollBehaviorOptions;
+  /**
+   * @default "left"
+   */
+  button?: keyof typeof mouseButtonNumbers;
 }
 
 /** @ignore this, update documentation for this function at index.d.ts */
@@ -42,9 +47,9 @@ export async function realMouseUp(
     x,
     y,
     clickCount: 1,
-    buttons: 1,
+    buttons: mouseButtonNumbers[options.button ?? "left"],
     pointerType: options.pointer ?? "mouse",
-    button: "left",
+    button: options.button ?? "left",
   });
 
   log.snapshot("after").end();

src/mouseButtonNumbers.ts

@@ -0,0 +1,8 @@
+export const mouseButtonNumbers = {
+    "none": 0,
+    "left": 1,
+    "right": 2,
+    "middle": 4,
+    "back": 8,
+    "forward": 16,
+}