feat: add touchMoveDelay option to realSwipe (#621)

* chore(docs): fix a few typos and issues in realSwipe docs

* feat(realSwipe): add `touchMoveDelay` option

closes #620

README.md

@@ -254,9 +254,11 @@ cy.realSwipe(direction, options);
 Options:
 
 - `Optional` **length**: undefined \| number **`default`** 10
+- `Optional` **step**: undefined \| number **`default`** 10
 - `Optional` **x**: undefined \| number ([more about coordinates](#coordinates))
 - `Optional` **y**: undefined \| number ([more about coordinates](#coordinates))
 - `Optional` **touchPosition**: "topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"
+- `Optional` **touchMoveDelay**: undefined \| number **`default`** 0
 
 ## cy.realMouseDown
 

cypress/e2e/swipe.cy.ts

@@ -57,3 +57,14 @@ describe("cy.realSwipe", () => {
     });
   });
 });
+
+describe("touchMoveDelay", () => {
+  it("adds a delay between touch start and touch move events", () => {
+    cy.visit("./cypress/fixtures/swipe-touch-move-delay");
+    cy.get("[role=gridcell]").contains("14").realSwipe("toRight", {
+      touchMoveDelay: 300,
+      length: 70,
+    });
+    cy.get("[role=gridcell][aria-selected=true]").should("have.length", 3);
+  });
+});

src/commands/realPress.ts

@@ -1,6 +1,7 @@
 import { fireCdpCommand } from "../fireCdpCommand";
 import { keyCodeDefinitions } from "../keyCodeDefinitions";
 import { keyToModifierBitMap } from "../keyToModifierBitMap";
+import { wait } from "../utils";
 
 export interface RealPressOptions {
   /**
@@ -78,7 +79,7 @@ export async function realPress(
       });
     }
 
-    await new Promise((res) => setTimeout(res, options.pressDelay ?? 25));
+    await wait(options.pressDelay ?? 25);
   }
 
   await Promise.all(

src/commands/realSwipe.ts

@@ -25,18 +25,25 @@ export interface RealSwipeOptions {
    */
   y?: number;
   /** Length of swipe (in pixels)
-   * @default 50
+   * @default 10
    * @example
    * cy.get(".drawer").realSwipe("toLeft", { length: 50 })
    */
   length?: number;
   /**
-   * Swipe step (how often new touch move will be generated). Less more precise
-   * ! Must be less than options.length
+   * Swipe step (how often new touch move will be generated).
+   * Must be less than or equal options.length
    * @default 10
    * cy.get(".drawer").realSwipe("toLeft", { step: 5 })
    */
   step?: number;
+
+  /**
+   * Delay between touchStart and touchMove events (ms)
+   * @default 0
+   * cy.get(".drawer").realSwipe("toLeft", { touchMoveDelay: 300 })
+   */
+  touchMoveDelay?: number;
 }
 
 async function forEachSwipePosition(
@@ -117,6 +124,12 @@ export async function realSwipe(
     touchPoints: [startPosition],
   });
 
+  if (options.touchMoveDelay) {
+    // cy.wait() can't be used here since we are in a command that returns a promise.
+    // Read more: https://on.cypress.io/returning-promise-and-commands-in-another-command
+    await wait(options.touchMoveDelay);
+  }
+
   await forEachSwipePosition(
     {
       length,
@@ -140,3 +153,4 @@ export async function realSwipe(
 
   return subject;
 }
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

src/commands/realType.ts

@@ -1,5 +1,6 @@
 import { keyCodeDefinitions } from "../keyCodeDefinitions";
 import { realPress } from "./realPress";
+import { wait } from "../utils";
 
 export interface RealTypeOptions {
   /**
@@ -58,7 +59,7 @@ export async function realType(text: string, options: RealTypeOptions = {}) {
       log: false,
     });
 
-    await new Promise((res) => setTimeout(res, options.delay ?? 25));
+    await wait(options.delay ?? 25);
   }
 
   log?.snapshot("after").end();

src/utils.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a Promise that resolves after `ms` milliseconds.
+ * @param ms wait time in milliseconds.
+ */
+export const wait = (ms: number) =>
+  new Promise((resolve) => setTimeout(resolve, ms));