test: added debug helpers (#703)

Author: makhnatkin

docs/how-to-add-visual-test.md

@@ -95,6 +95,31 @@ See more: [Command line](https://playwright.dev/docs/test-cli)
   npm run playwright:docker:report
   ```
 
+## Writing Complex Tests
+
+### Editor helpers
+The core also includes helper functions designed to simplify UI interactions, testing, and debugging. These allow you to quickly switch editor modes, paste and clear text, visually highlight elements, and inspect their HTML markup during development.
+
+See:
+  ```
+  tests/playwright/core/editor.ts
+  tests/playwright/core/helpers.ts
+  ```
+
+## Clipboard specifics
+
+Playwright clipboard support varies across browsers. Keep this in mind when writing copy-paste tests.
+
+## Click testing
+
+Playwright provides three main ways to perform clicks:
+
+- `locator.click()`
+- `element.dispatchEvent('click', params)`
+- `page.mouse.click(x, y)`
+
+Choose the method based on your code specifics. For events involving bubbling, consider using `dispatchEvent` with `{ bubbles: true }`.
+
 ## Useful Links
 
 - [Playwright API](https://playwright.dev/docs/api/class-test)

tests/playwright/core/helpers.ts

@@ -1,4 +1,4 @@
-import type {BrowserContext, Page} from '@playwright/test';
+import type {BrowserContext, Locator, Page} from '@playwright/test';
 
 class Keymap {
     readonly selectAll = 'ControlOrMeta+A';
@@ -31,3 +31,92 @@ export class PlaywrightHelpers {
         });
     }
 }
+
+export class DebugHelpers {
+    private readonly page;
+
+    constructor({page}: {page: Page}) {
+        this.page = page;
+    }
+
+    /**
+     * Draws a red dot on the screen at the given (x, y) coordinates.
+     * Useful for debugging click locations.
+     *
+     * Example:
+     * ```ts
+     * const box = await element.boundingBox();
+     * if (box) {
+     *   const { x, y } = box;
+     *   await element.dispatchEvent('click', {
+     *     bubbles: true,
+     *     cancelable: true,
+     *     composed: true,
+     *     clientX: Math.floor(x + 2),
+     *     clientY: Math.floor(y + 2),
+     *   });
+     *   await markClick(page, x + 2, y + 2);
+     * }
+     * ```
+     */
+    async markClick(x: number, y: number) {
+        await this.page.evaluate(
+            ({x, y}) => {
+                const dot = document.createElement('div');
+                dot.style.position = 'absolute';
+                dot.style.width = '6px';
+                dot.style.height = '6px';
+                dot.style.borderRadius = '50%';
+                dot.style.background = 'red';
+                dot.style.zIndex = '999999';
+                dot.style.pointerEvents = 'none';
+                dot.style.left = `${x}px`;
+                dot.style.top = `${y}px`;
+                document.body.appendChild(dot);
+            },
+            {x, y},
+        );
+    }
+
+    /**
+     *  Logs the outer HTML of a given locator.
+     *  Useful for debugging or verifying the exact markup of an element.
+     */
+    async logHtml(locator: Locator) {
+        const html = await locator.evaluate((el) => el.outerHTML);
+        console.log('Outer HTML:', html);
+    }
+
+    /**
+     * Highlights a given locator by applying CSS styles.
+     * Useful for visually identifying elements during testing or debugging.
+     */
+    async highlight(
+        locator: Locator,
+        {
+            outline = true,
+            background = true,
+            border = false,
+        }: {
+            outline?: boolean;
+            background?: boolean;
+            border?: boolean;
+        } = {},
+    ) {
+        await locator.evaluate(
+            (el, opts) => {
+                if (opts.outline) {
+                    el.style.outline = '2px solid red';
+                    el.style.outlineOffset = '2px';
+                }
+                if (opts.border) {
+                    el.style.border = '2px solid red';
+                }
+                if (opts.background) {
+                    el.style.backgroundColor = 'rgba(255, 0, 0, 0.05)';
+                }
+            },
+            {outline, background, border},
+        );
+    }
+}

tests/playwright/core/index.ts

@@ -2,7 +2,7 @@ import {test as base, expect} from '@playwright/experimental-ct-react';
 
 import {MarkdownEditorPage} from './editor';
 import {expectScreenshot} from './expectScreenshot';
-import {PlaywrightHelpers} from './helpers';
+import {DebugHelpers, PlaywrightHelpers} from './helpers';
 import {mount} from './mount';
 import type {Fixtures} from './types';
 import {wait} from './wait';
@@ -19,6 +19,10 @@ export const test = base.extend<Fixtures>({
         const helpers = new PlaywrightHelpers({page, context});
         await use(helpers);
     },
+    debug: async ({page}, use) => {
+        const debug = new DebugHelpers({page});
+        await use(debug);
+    },
     platform: [process.platform, {scope: 'test'}],
 });
 

tests/playwright/core/types.ts

@@ -13,7 +13,7 @@ import type {
 } from '@playwright/test';
 
 import type {MarkdownEditorPage} from './editor';
-import type {PlaywrightHelpers} from './helpers';
+import type {DebugHelpers, PlaywrightHelpers} from './helpers';
 
 interface ComponentFixtures {
     mount<HooksConfig>(
@@ -36,6 +36,7 @@ export type Fixtures = {
     wait: WaitFixture;
     editor: MarkdownEditorPage;
     helpers: PlaywrightHelpers;
+    debug: DebugHelpers;
     platform: NodeJS.Platform;
 };