@redhat-developer/page-objects 1.22.0 → 1.23.1

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.d.ts

@@ -60,6 +60,40 @@ export declare class TextEditor extends Editor {
      * @returns Promise resolving to ContentAssist object when opening, void otherwise
      */
     toggleContentAssist(open: boolean): Promise<ContentAssist | void>;
+    /**
+     * Find out whether this editor currently has VS Code keyboard focus
+     * @returns Promise resolving to true when the editor's text input is focused
+     */
+    hasFocus(): Promise<boolean>;
+    /**
+     * Bring VS Code keyboard focus into this editor without moving the cursor.
+     *
+     * Editor commands (select all, clipboard actions, the `:Ln,Col` go-to prompt)
+     * and the status bar cursor position all target whichever editor VS Code has
+     * focused, and the editor's zero-width `native-edit-context` input element only
+     * accepts keys while it is the focused element. With several editor groups open
+     * this makes the page object act on its own editor instance instead of on the
+     * group that happened to be focused before.
+     *
+     * @returns Promise resolving once the editor has focus
+     */
+    focus(): Promise<void>;
+    /**
+     * Open the command palette with this editor focused, so editor commands
+     * (select all, clipboard actions, the `:Ln,Col` go-to prompt) run against
+     * this editor instance.
+     *
+     * Focus is moved into this editor first, then the palette is opened with the
+     * global `Ctrl/Cmd+Shift+P` chord. `Workbench.openCommandPrompt()` cannot be
+     * reused here: while any webview editor is open it sends the key to the first
+     * active tab of whatever group, which need not be this editor's group.
+     */
+    private openCommandPrompt;
+    /**
+     * Execute a command from the command palette opened on this editor
+     * @param command id or title of the command
+     */
+    private executeCommand;
     /**
      * Get all text from the editor
      * @returns Promise resolving to editor text

package/out/components/editor/TextEditor.js

@@ -113,6 +113,76 @@ class TextEditor extends Editor_1.Editor {
             }
         });
     }
+    /**
+     * Find out whether this editor currently has VS Code keyboard focus
+     * @returns Promise resolving to true when the editor's text input is focused
+     */
+    async hasFocus() {
+        const container = await this.findElement(TextEditor.locators.TextEditor.editorContainer);
+        const klass = (await container.getAttribute('class')) ?? '';
+        return klass.split(/\s+/).includes('focused');
+    }
+    /**
+     * Bring VS Code keyboard focus into this editor without moving the cursor.
+     *
+     * Editor commands (select all, clipboard actions, the `:Ln,Col` go-to prompt)
+     * and the status bar cursor position all target whichever editor VS Code has
+     * focused, and the editor's zero-width `native-edit-context` input element only
+     * accepts keys while it is the focused element. With several editor groups open
+     * this makes the page object act on its own editor instance instead of on the
+     * group that happened to be focused before.
+     *
+     * @returns Promise resolving once the editor has focus
+     */
+    async focus() {
+        if (await this.hasFocus()) {
+            return;
+        }
+        const inputarea = await this.findElement(TextEditor.locators.Editor.inputArea);
+        await this.getDriver().executeScript('arguments[0].focus()', inputarea);
+        await this.getWaitHelper().forCondition(() => this.hasFocus(), {
+            timeout: 2000,
+            pollInterval: 50,
+            message: 'Editor did not receive focus',
+        });
+    }
+    /**
+     * Open the command palette with this editor focused, so editor commands
+     * (select all, clipboard actions, the `:Ln,Col` go-to prompt) run against
+     * this editor instance.
+     *
+     * Focus is moved into this editor first, then the palette is opened with the
+     * global `Ctrl/Cmd+Shift+P` chord. `Workbench.openCommandPrompt()` cannot be
+     * reused here: while any webview editor is open it sends the key to the first
+     * active tab of whatever group, which need not be this editor's group.
+     */
+    async openCommandPrompt() {
+        await this.focus();
+        await this.getDriver()
+            .actions()
+            .keyDown(AbstractElement_1.AbstractElement.ctlKey)
+            .keyDown(selenium_webdriver_1.Key.SHIFT)
+            .sendKeys('p')
+            .keyUp(selenium_webdriver_1.Key.SHIFT)
+            .keyUp(AbstractElement_1.AbstractElement.ctlKey)
+            .perform();
+        return await __1.InputBox.create();
+    }
+    /**
+     * Execute a command from the command palette opened on this editor
+     * @param command id or title of the command
+     */
+    async executeCommand(command) {
+        const prompt = await this.openCommandPrompt();
+        await prompt.setText(`>${command}`);
+        const quickPicks = await Promise.all((await prompt.getQuickPicks()).map((item) => item.getLabel()));
+        if (quickPicks.includes(command)) {
+            await prompt.selectQuickPick(command);
+        }
+        else {
+            await prompt.confirm();
+        }
+    }
     /**
      * Get all text from the editor
      * @returns Promise resolving to editor text
@@ -128,8 +198,14 @@ 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'));
+            // The status bar position, the select-all/copy commands and the cursor
+            // restore below all act on the focused editor: make sure it is this one.
+            await self.focus();
+            // Store current position
+            const [line, col] = await self.getCoordinates();
+            // Select/copy contents
+            await self.executeCommand('editor.action.selectAll');
+            await self.executeCommand('editor.action.clipboardCopyAction');
             // Wait for clipboard operation to complete
             await self.getWaitHelper().forCondition(async () => {
                 try {
@@ -141,10 +217,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 self.setCursor(line, col);
+            }
+            catch {
+                await self.sendKeys(selenium_webdriver_1.Key.UP);
+            }
             return text;
         });
     }
@@ -164,9 +246,11 @@ 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
         }
+        await this.focus();
         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'));
+        await this.executeCommand('editor.action.selectAll');
+        await inputarea.sendKeys(selenium_webdriver_1.Key.chord(TextEditor.ctlKey, 'v'));
         if (originalClipboard.length > 0) {
             clipboard.writeSync(originalClipboard);
         }
@@ -346,7 +430,7 @@ class TextEditor extends Editor_1.Editor {
      * @returns Promise resolving when the cursor has reached the given coordinates
      */
     async setCursor(line, column, timeout = 2_500) {
-        const input = await new __1.Workbench().openCommandPrompt();
+        const input = await this.openCommandPrompt();
         await input.setText(`:${line},${column}`);
         try {
             await this.getWaitHelper().forCondition(async () => {

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.1",
   "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": "9c3230175f00a9210a7bc2238bc9d6e9101b86f1"
 }