@redhat-developer/page-objects 1.22.0 → 1.23.0

package/README.md

@@ -1,9 +1,64 @@
 <h1 align="center">
-  <img alt="ExTester for Visual Studio Code" width="75%" height="75%" src="../../icons/logo-text-side.png">
+  <img alt="ExTester for Visual Studio Code" width="75%" src="https://raw.githubusercontent.com/redhat-developer/vscode-extension-tester/main/icons/logo-text-side.png">
 </h1>
 
 <h2 align="center">Page Objects</h2>
 
-<p align="center">
-Page Object API implementation for a VS Code editor used by <a href="https://github.com/redhat-developer/vscode-extension-tester">ExTester</a> framework.</br>📄 <a href="https://github.com/redhat-developer/vscode-extension-tester/wiki/Page-Object-APIs">Documentation</a>
-</p>
+<p align="center">Page Object API for the Visual Studio Code UI, used by the <a href="https://github.com/redhat-developer/vscode-extension-tester">ExTester</a> framework.</p>
+
+## What it is
+
+Page objects wrap the parts of the VS Code workbench in classes with meaningful methods, so a test can say `new ActivityBar().getViewControl('Explorer')` instead of searching the DOM. This package contains:
+
+- Page object classes for the activity bar, side bar views and tree sections, editors (text, diff, settings, custom and web view), the bottom panel (problems, output, terminal and debug console), the status bar, title bar and menus, dialogs, notifications and the debug views.
+- `AbstractElement`, the base class every page object extends, including your own custom ones.
+- `LocatorLoader` and `mergeLocators`, which assemble the locator set for the VS Code version under test from [`@redhat-developer/locators`](https://www.npmjs.com/package/@redhat-developer/locators) and an optional custom contribution.
+- `WaitHelper`, timeout constants and a re-export of `selenium-webdriver`, so one import gives you `WebDriver`, `By`, `Key` and the rest.
+
+## Installation
+
+[`vscode-extension-tester`](https://www.npmjs.com/package/vscode-extension-tester) depends on this package and re-exports everything from it. In an ExTester project you import page objects from `vscode-extension-tester` and never install this package directly:
+
+```typescript
+import { ActivityBar, EditorView, TextEditor } from "vscode-extension-tester";
+```
+
+Install it on its own only if you drive a VS Code instance with your own WebDriver setup:
+
+```bash
+npm install --save-dev @redhat-developer/page-objects @redhat-developer/locators selenium-webdriver
+```
+
+Peer dependencies: `selenium-webdriver ^4.48.0` and `typescript >= 4.6.2`.
+
+## Standalone usage
+
+The page objects must be initialised once before the first one is created. ExTester does this for you when `VSBrowser` starts; without ExTester, call `initPageObjects` yourself:
+
+```typescript
+import { getLocatorsPath } from "@redhat-developer/locators";
+import { initPageObjects } from "@redhat-developer/page-objects";
+
+initPageObjects(
+  "1.134.0", // VS Code version under test
+  "1.37.0", // version of the base locator set
+  getLocatorsPath(), // folder with the compiled locators
+  driver, // your selenium-webdriver WebDriver attached to VS Code
+  browserName, // name of the browser the page objects run in
+  "./out/test/pageObjects/locators.js", // optional custom locator contribution
+);
+```
+
+## Documentation
+
+- [Page Object Reference](https://redhat-developer.github.io/vscode-extension-tester/objects/) — every page object with examples
+- [Custom Page Objects](https://redhat-developer.github.io/vscode-extension-tester/guides/custom-page-objects/) — extend the API for your own extension's UI
+
+## Feedback
+
+- Bugs and feature requests: [open an issue](https://github.com/redhat-developer/vscode-extension-tester/issues/new/choose)
+- Questions: [GitHub Discussions](https://github.com/redhat-developer/vscode-extension-tester/discussions)
+
+## License
+
+[Apache License 2.0](https://github.com/redhat-developer/vscode-extension-tester/blob/main/LICENSE)

package/out/components/AbstractElement.d.ts

@@ -53,6 +53,14 @@ export declare abstract class AbstractElement extends WebElement {
      */
     constructor(base: Locator | WebElement, enclosingItem?: WebElement | Locator);
     isEnabled(): Promise<boolean>;
+    /**
+     * Click the element, recovering when a transient overlay intercepts the
+     * click. VS Code renders hovers/tooltips as DOM overlays that appear while
+     * the WebDriver pointer rests on the last click point and never auto-hide,
+     * so a plain W3C click deadlocks on its pre-dispatch hit-test. See
+     * {@link WaitHelper.clickThroughInterception} for the recovery strategy.
+     */
+    click(): Promise<void>;
     isSelected(): Promise<boolean>;
     /**
      * Wait for the element to become visible

package/out/components/AbstractElement.js

@@ -76,6 +76,16 @@ class AbstractElement extends selenium_webdriver_1.WebElement {
     async isEnabled() {
         return (await super.isEnabled()) && (await AbstractElement.locators.AbstractElement.enabled(this));
     }
+    /**
+     * Click the element, recovering when a transient overlay intercepts the
+     * click. VS Code renders hovers/tooltips as DOM overlays that appear while
+     * the WebDriver pointer rests on the last click point and never auto-hide,
+     * so a plain W3C click deadlocks on its pre-dispatch hit-test. See
+     * {@link WaitHelper.clickThroughInterception} for the recovery strategy.
+     */
+    async click() {
+        await AbstractElement.waitHelper.clickThroughInterception(this, () => super.click());
+    }
     async isSelected() {
         return (await super.isSelected()) && (await AbstractElement.locators.AbstractElement.selected(this));
     }

package/out/components/editor/EditorView.js

@@ -252,29 +252,9 @@ class EditorGroup extends AbstractElement_1.AbstractElement {
     async closeEditor(title) {
         const tab = await this.getTabByTitle(title);
         const closeButton = await tab.findElement(EditorView.locators.EditorView.closeTab);
-        // VS Code renders hover tooltip overlays (<div class="hover-contents">) that can
-        // intercept the click (ElementClickInterceptedError) on CI. Retry with an
-        // increasing delay; fall back to a JS-executor click on the last attempt which
-        // bypasses overlay elements entirely.
-        const maxAttempts = 3;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            try {
-                await closeButton.click();
-                return;
-            }
-            catch (err) {
-                if (err.name !== 'ElementClickInterceptedError' || attempt === maxAttempts - 1) {
-                    // On the final attempt use executeScript to bypass the overlay, then return.
-                    if (err.name === 'ElementClickInterceptedError') {
-                        await this.getDriver().executeScript('arguments[0].click()', closeButton);
-                        return;
-                    }
-                    throw err;
-                }
-                // Brief back-off so the tooltip has time to dismiss before the next attempt.
-                await this.getWaitHelper().sleep(300 * (attempt + 1));
-            }
-        }
+        // hover tooltip overlays can intercept the click on CI - the centralized
+        // recovery parks the pointer to dismiss them and retries the native click
+        await this.getWaitHelper().clickThroughInterception(closeButton);
     }
     /**
      * Close all open editor tabs

package/out/components/editor/TextEditor.js

@@ -128,8 +128,12 @@ class TextEditor extends Editor_1.Editor {
                 // workaround issue https://github.com/redhat-developer/vscode-extension-tester/issues/835
                 // do not fail if clipboard is empty
             }
-            const inputarea = await self.findElement(TextEditor.locators.Editor.inputArea);
-            await inputarea.sendKeys(selenium_webdriver_1.Key.chord(TextEditor.ctlKey, 'a'), selenium_webdriver_1.Key.chord(TextEditor.ctlKey, 'c'));
+            // Store current position
+            const [line, col] = await this.getCoordinates();
+            // Select/copy contents
+            const bench = new __1.Workbench();
+            await bench.executeCommand('editor.action.selectAll');
+            await bench.executeCommand('editor.action.clipboardCopyAction');
             // Wait for clipboard operation to complete
             await self.getWaitHelper().forCondition(async () => {
                 try {
@@ -141,10 +145,16 @@ class TextEditor extends Editor_1.Editor {
                 }
             }, { timeout: 2000, pollInterval: 50, message: 'Clipboard copy operation did not complete' });
             const text = clipboard.readSync();
-            await inputarea.sendKeys(selenium_webdriver_1.Key.UP);
             if (originalClipboard.length > 0) {
                 clipboard.writeSync(originalClipboard);
             }
+            try {
+                // Restore original cursor position
+                await this.setCursor(line, col);
+            }
+            catch {
+                await this.sendKeys(selenium_webdriver_1.Key.UP);
+            }
             return text;
         });
     }
@@ -166,7 +176,9 @@ class TextEditor extends Editor_1.Editor {
         }
         const inputarea = await this.findElement(TextEditor.locators.Editor.inputArea);
         clipboard.writeSync(text);
-        await inputarea.sendKeys(selenium_webdriver_1.Key.chord(TextEditor.ctlKey, 'a'), selenium_webdriver_1.Key.chord(TextEditor.ctlKey, 'v'));
+        const bench = new __1.Workbench();
+        await bench.executeCommand('editor.action.selectAll');
+        await inputarea.sendKeys(selenium_webdriver_1.Key.chord(TextEditor.ctlKey, 'v'));
         if (originalClipboard.length > 0) {
             clipboard.writeSync(originalClipboard);
         }

package/out/utils/WaitHelper.d.ts

@@ -189,6 +189,37 @@ export declare class WaitHelper {
      * @param ms Milliseconds to sleep
      */
     sleep(ms: number): Promise<void>;
+    /**
+     * Move the virtual pointer to a quiet spot: the title-bar drag region at the
+     * top-center of the window (the command center is disabled by the framework's
+     * default settings, and unlike the status bar the area has no hover targets).
+     *
+     * A WebDriver session has no OS mouse - the pointer rests wherever the last
+     * interaction left it. VS Code hovers appear while the pointer rests on an
+     * element and are torn down only when it moves away, so parking delivers the
+     * mouseout an open hover is waiting for and disarms pending hover timers.
+     */
+    parkPointer(): Promise<void>;
+    /**
+     * Click an element, recovering when a transient overlay intercepts the click.
+     *
+     * VS Code renders rich hovers/tooltips as DOM overlays that appear while the
+     * pointer rests on the last click point and never auto-hide. A W3C click
+     * hit-tests the click point BEFORE dispatching any event, so a resting hover
+     * over the target fails every attempt until the pointer actually moves -
+     * waiting alone can never resolve it. On interception this actively parks
+     * the pointer (dismissing pointer-rest overlays), waits for hover teardown
+     * and retries the native click. As a last resort it falls back to a
+     * JS-executor click, which bypasses hit-testing but also mousedown semantics
+     * (Monaco lists select on mousedown) - the fallback is logged so the call
+     * site's true blocker can be root-caused instead of silently papered over.
+     *
+     * @param element the element to click
+     * @param nativeClick override for the native click action (used by
+     * AbstractElement.click() to reach WebElement.prototype.click through its
+     * own override)
+     */
+    clickThroughInterception(element: WebElement, nativeClick?: () => Promise<void>): Promise<void>;
     /**
      * Get the WebDriver instance.
      */

package/out/utils/WaitHelper.js

@@ -450,6 +450,76 @@ class WaitHelper {
     async sleep(ms) {
         await new Promise((resolve) => setTimeout(resolve, ms));
     }
+    /**
+     * Move the virtual pointer to a quiet spot: the title-bar drag region at the
+     * top-center of the window (the command center is disabled by the framework's
+     * default settings, and unlike the status bar the area has no hover targets).
+     *
+     * A WebDriver session has no OS mouse - the pointer rests wherever the last
+     * interaction left it. VS Code hovers appear while the pointer rests on an
+     * element and are torn down only when it moves away, so parking delivers the
+     * mouseout an open hover is waiting for and disarms pending hover timers.
+     */
+    async parkPointer() {
+        const width = Number(await this.driver.executeScript('return window.innerWidth')) || 200;
+        await this.driver
+            .actions()
+            .move({ x: Math.floor(width / 2), y: 5 })
+            .perform();
+    }
+    /**
+     * Click an element, recovering when a transient overlay intercepts the click.
+     *
+     * VS Code renders rich hovers/tooltips as DOM overlays that appear while the
+     * pointer rests on the last click point and never auto-hide. A W3C click
+     * hit-tests the click point BEFORE dispatching any event, so a resting hover
+     * over the target fails every attempt until the pointer actually moves -
+     * waiting alone can never resolve it. On interception this actively parks
+     * the pointer (dismissing pointer-rest overlays), waits for hover teardown
+     * and retries the native click. As a last resort it falls back to a
+     * JS-executor click, which bypasses hit-testing but also mousedown semantics
+     * (Monaco lists select on mousedown) - the fallback is logged so the call
+     * site's true blocker can be root-caused instead of silently papered over.
+     *
+     * @param element the element to click
+     * @param nativeClick override for the native click action (used by
+     * AbstractElement.click() to reach WebElement.prototype.click through its
+     * own override)
+     */
+    async clickThroughInterception(element, nativeClick = () => element.click()) {
+        const maxNativeAttempts = 3;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await nativeClick();
+            }
+            catch (e) {
+                if (e.name !== 'ElementClickInterceptedError') {
+                    throw e;
+                }
+                // a modal dialog blocks the whole workbench by design - neither
+                // pointer parking nor a JS click may subvert it: JS-clicking
+                // through the blocker would trigger actions the real UI forbids.
+                // Fail fast with the original error so modal-aware callers (and
+                // test authors) see the true blocker.
+                const modalUp = await this.driver
+                    .executeScript('return Array.from(document.querySelectorAll(".monaco-dialog-modal-block, .monaco-dialog-box")).some((el) => el.checkVisibility());')
+                    .catch(() => false);
+                if (modalUp) {
+                    throw e;
+                }
+                if (attempt >= maxNativeAttempts - 1) {
+                    console.warn(`clickThroughInterception: falling back to a JS click after ${maxNativeAttempts} intercepted attempts: ${e.message}`);
+                    await this.driver.executeScript('arguments[0].click();', element);
+                    return;
+                }
+                await this.parkPointer();
+                // hover teardown is event-driven and near-instant once the pointer
+                // moved away; a non-hover interceptor (modal, toast) never passes
+                // this check, so time-box it and retry regardless
+                await this.forCondition(async () => await this.driver.executeScript('return !Array.from(document.querySelectorAll(".monaco-hover")).some((el) => el.checkVisibility());'), { timeout: 1500, pollInterval: 50, message: 'hover overlay did not dismiss after parking the pointer' }).catch(() => undefined);
+            }
+        }
+    }
     /**
      * Get the WebDriver instance.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redhat-developer/page-objects",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Page Object API implementation for a VS Code editor used by ExTester framework.",
   "main": "out/index.js",
   "types": "out/index.d.ts",
@@ -49,5 +49,5 @@
     "selenium-webdriver": "^4.48.0",
     "typescript": ">=4.6.2"
   },
-  "gitHead": "46f92f28229b4fd407b7fbb54488abb1bfc2b4a8"
+  "gitHead": "2333228475aff111f91b91d06e50a5b98e371886"
 }