feat: add realActive() command

README.md

@@ -35,6 +35,7 @@ Here is a simple test that can be written with native events:
 
 ```js
 it("tests real events", () => {
+  cy.get("input").realActive(); // perform a native mouse press on the field
   cy.get("input").realClick(); // perform a native real click on the field
   cy.realType("cypress real event"); // fires native system keypress events and fills the field
   cy.realPress("Tab"); // native tab click switches the focus
@@ -74,13 +75,35 @@ If you are using typescript, also add the following to `cypress/tsconfig.json`
 The idea of the commands – they should be as similar as possible to cypress default commands (like `cy.type`), but starts with `real` – `cy.realType`.
 
 Here is an overview of the available **real** event commands:
+- [cy.realActive](#cyrealactive)
 - [cy.realClick](#cyrealclick)
 - [cy.realHover](#cyrealhover)
 - [cy.realPress](#cyrealpress)
 - [cy.realTouch](#cyrealtouch)
 - [cy.realType](#cyrealtype)
 - [cy.realSwipe](#cyrealswipe)
 
+## cy.realActive
+
+Fires native system mouse press event.
+
+```jsx
+cy.get("button").realActive();
+cy.get("button").realActive(options);
+```
+
+Example:
+
+```js
+cy.get("button").realActive({ position: "topLeft" }) // click on the top left corner of button
+```
+
+Options:
+
+- `Optional` **pointer**: \"mouse\" \| \"pen\"
+- `Optional` **position**: "topLeft" | "top" | "topRight" | "left"  | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"
+- `Optional` **scrollBehavior**: "center" | "top" | "bottom" | "nearest" | false
+
 ## cy.realClick
 
 Fires native system click event.

cypress/fixtures/frame-two.html

@@ -13,6 +13,7 @@
   <style>
     #target { width: 100px; height: 100px; background: green; }
     #target:hover { background: pink; }
+    #target:active { background: blue; }
 
     * { box-sizing: border-box; }
     html, body { height: 100%; }

cypress/integration/active.spec.ts

@@ -0,0 +1,169 @@
+describe("cy.realActive", () => {
+    beforeEach(() => {
+      cy.visit("https://example.cypress.io/commands/actions");
+    });
+
+    it("active state on the button", () => {
+      cy.get(".action-btn").should("have.css", "background-color", "rgb(217, 83, 79)");
+      cy.get(".action-btn").realActive();
+      cy.get(".action-btn").should("have.css", "background-color", "rgb(172, 41, 37)");
+    });
+
+    it("active/focused state on the text field", () => {
+      cy.get("#email1").realActive().should("be.focused");
+    });
+
+    it("active state on different positions", () => {
+      cy.get(".action-btn")
+        .realActive({ position: "topLeft" })
+        .realActive({ position: "top" })
+        .realActive({ position: "topRight" })
+        .realActive({ position: "left" })
+        .realActive({ position: "center" })
+        .realActive({ position: "right" })
+        .realActive({ position: "bottomLeft" })
+        .realActive({ position: "bottom" })
+        .realActive({ position: "bottomRight" });
+    });
+
+    describe("scroll behavior", () => {
+      function getScreenEdges() {
+        const cypressAppWindow = window.parent.document.querySelector("iframe")
+          .contentWindow;
+        const windowTopEdge = cypressAppWindow.document.documentElement.scrollTop;
+        const windowBottomEdge = windowTopEdge + cypressAppWindow.innerHeight;
+        const windowCenter = windowTopEdge + cypressAppWindow.innerHeight / 2;
+
+        return {
+          top: windowTopEdge,
+          bottom: windowBottomEdge,
+          center: windowCenter,
+        };
+      }
+
+      function getElementEdges($el: JQuery) {
+        const $elTop = $el.offset().top;
+
+        return {
+          top: $elTop,
+          bottom: $elTop + $el.outerHeight(),
+        };
+      }
+
+      beforeEach(() => {
+        cy.window().scrollTo("top");
+      });
+
+      it("defaults to scrolling the element to the top of the viewport", () => {
+        cy.get("#action-canvas")
+          .realActive()
+          .then(($canvas: JQuery) => {
+            const { top: $elTop } = getElementEdges($canvas);
+            const { top: screenTop } = getScreenEdges();
+
+            expect($elTop).to.equal(screenTop);
+          });
+      });
+
+      it("scrolls the element to center of viewport", () => {
+        cy.get("#action-canvas")
+          .realActive({ scrollBehavior: "center" })
+          .then(($canvas: JQuery) => {
+            const { top: $elTop, bottom: $elBottom } = getElementEdges($canvas);
+            const { top: screenTop, bottom: screenBottom } = getScreenEdges();
+
+            const screenCenter = screenTop + (screenBottom - screenTop) / 2;
+
+            expect($elTop).to.equal(screenCenter - $canvas.outerHeight() / 2);
+            expect($elBottom).to.equal(screenCenter + $canvas.outerHeight() / 2);
+          });
+      });
+
+      it("scrolls the element to the top of the viewport", () => {
+        cy.get("#action-canvas")
+          .realActive({ scrollBehavior: "top" })
+          .then(($canvas: JQuery) => {
+            const { top: $elTop } = getElementEdges($canvas);
+            const { top: screenTop } = getScreenEdges();
+
+            expect($elTop).to.equal(screenTop);
+          });
+      });
+
+      it("scrolls the element to the bottom of the viewport", () => {
+        cy.get("#action-canvas")
+          .realActive({ scrollBehavior: "bottom" })
+          .then(($canvas: JQuery) => {
+            const { bottom: $elBottom } = getElementEdges($canvas);
+            const { bottom: screenBottom } = getScreenEdges();
+
+            expect($elBottom).to.equal(screenBottom);
+          });
+      });
+
+      it("scrolls the element to the nearest edge of the viewport", () => {
+        cy.window().scrollTo("bottom");
+
+        cy.get("#action-canvas")
+          .realActive({ scrollBehavior: "nearest" })
+          .then(($canvas: JQuery) => {
+            const { top: $elTop } = getElementEdges($canvas);
+            const { top: screenTop } = getScreenEdges();
+
+            expect($elTop).to.equal(screenTop);
+          });
+
+        cy.window().scrollTo("top");
+
+        cy.get("#action-canvas")
+          .realActive({ scrollBehavior: "nearest" })
+          .then(($canvas: JQuery) => {
+            const { bottom: $elBottom } = getElementEdges($canvas);
+            const { bottom: screenBottom } = getScreenEdges();
+
+            expect($elBottom).to.equal(screenBottom);
+          });
+      });
+    });
+});
+
+describe('iframe behavior', () => {
+    beforeEach(() => {
+      cy.visit('./cypress/fixtures/iframe-page.html');
+    });
+
+    it('sets elements inside iframes to active state', () => {
+      cy.get('iframe').then(($firstIframe) => {
+        return cy.wrap($firstIframe.contents().find('iframe'));
+      }).then(($secondIframe) => {
+        return cy.wrap($secondIframe.contents().find('body'));
+      }).within(() => {
+        cy.get('#target').then(($target) => {
+          expect($target.css('background-color')).to.equal('rgb(0, 128, 0)');
+        });
+
+        cy.get('#target').realActive().then(($target) => {
+          expect($target.css('background-color')).to.equal('rgb(0, 0, 255)');
+        });
+      });
+    });
+
+    it('sets elements inside transformed iframes to active states', () => {
+      cy.get('iframe').then(($firstIframe) => {
+        $firstIframe.css('transform', 'scale(.5)');
+        return cy.wrap($firstIframe.contents().find('iframe'));
+      }).then(($secondIframe) => {
+        $secondIframe.css('transform', 'scale(.75)');
+        return cy.wrap($secondIframe.contents().find('body'));
+      }).within(() => {
+        cy.get('#target').then(($target) => {
+          expect($target.css('background-color')).to.equal('rgb(0, 128, 0)');
+        });
+
+        cy.get('#target').realActive().then(($target) => {
+          expect($target.css('background-color')).to.equal('rgb(0, 0, 255)');
+        });
+      });
+    });
+});
+

src/commands/realActive.ts

@@ -0,0 +1,53 @@
+import { fireCdpCommand } from "../fireCdpCommand";
+import {
+  getCypressElementCoordinates,
+  ScrollBehaviorOptions,
+  Position,
+} from "../getCypressElementCoordinates";
+
+export interface RealActiveOptions {
+  /** Pointer type for realClick, if "pen" touch simulated */
+  pointer?: "mouse" | "pen";
+  /**
+   * Position of the click event relative to the element
+   * @example cy.realClick({ position: "topLeft" })
+   */
+  position?: Position;
+  /**
+   * Controls how the page is scrolled to bring the subject into view, if needed.
+   * @example cy.realHover({ scrollBehavior: "top" });
+   */
+  scrollBehavior?: ScrollBehaviorOptions;
+}
+
+/** @ignore this, update documentation for this function at index.d.ts */
+export async function realActive(
+  subject: JQuery,
+  options: RealActiveOptions = {}
+) {
+  const { x, y } = getCypressElementCoordinates(subject, options.position, options.scrollBehavior);
+
+  const log = Cypress.log({
+    $el: subject,
+    name: "realActive",
+    consoleProps: () => ({
+      "Applied To": subject.get(0),
+      "Absolute Coordinates": { x, y },
+    }),
+  });
+
+  log.snapshot("before");
+  await fireCdpCommand("Input.dispatchMouseEvent", {
+    type: "mousePressed",
+    x,
+    y,
+    clickCount: 1,
+    buttons: 1,
+    pointerType: options.pointer ?? "mouse",
+    button: "left",
+  });
+
+  log.snapshot("after").end();
+
+  return subject;
+}

src/index.d.ts

@@ -8,6 +8,16 @@ type NormalizeCypressCommand<TFun> = TFun extends (
 
 declare namespace Cypress {
   interface Chainable {
+    /**
+     * Fires native system mousePressed event.
+     * @see https://github.com/dmtrKovalenko/cypress-real-events#cyrealactive
+     * @example
+     * cy.get("button").realActive()
+     * @param options mousePressed options
+     */
+    realActive: NormalizeCypressCommand<
+      typeof import("./commands/realActive").realActive
+    >;
     /**
      * Fires native system click event.
      * @see https://github.com/dmtrKovalenko/cypress-real-events#cyrealclick

src/support.ts

@@ -1,10 +1,12 @@
+import { realActive } from "./commands/realActive";
 import { realClick } from "./commands/realClick";
 import { realHover } from "./commands/realHover";
 import { realSwipe } from "./commands/realSwipe";
 import { realPress } from "./commands/realPress";
 import { realType } from "./commands/realType";
 import { realTouch } from './commands/realTouch';
 
+Cypress.Commands.add("realActive", { prevSubject: true }, realActive);
 Cypress.Commands.add("realClick", { prevSubject: true }, realClick);
 Cypress.Commands.add("realHover", { prevSubject: true }, realHover);
 Cypress.Commands.add("realTouch", { prevSubject: true }, realTouch);