Extra W3C commands implementation with unit and e2e tests:

getTitle, back, forward, setWindowsRect, getElementsScreenshot

Author: yuri-schwab

lib/commands/app.ts

@@ -17,8 +17,11 @@ import { sleep } from '../util';
 import { errors, W3C_ELEMENT_KEY } from '@appium/base-driver';
 import {
     getWindowAllHandlesForProcessIds,
+    keyDown,
+    keyUp,
     trySetForegroundWindow,
 } from '../winapi/user32';
+import { Key } from '../enums';
 
 const GET_PAGE_SOURCE_COMMAND = pwsh$ /* ps1 */ `
     $el = ${0}
@@ -215,6 +218,68 @@ export async function changeRootElement(this: NovaWindowsDriver, pathOrNativeWin
     throw new errors.UnknownError('Failed to locate window of the app.');
 }
 
+export async function back(this: NovaWindowsDriver): Promise<void> {
+    const elementId = (await this.sendPowerShellCommand(AutomationElement.automationRoot.buildCommand())).trim();
+    if (!elementId) {
+        throw new errors.NoSuchWindowError('No active window found for this session.');
+    }
+    keyDown(Key.ALT);
+    keyDown(Key.LEFT);
+    keyUp(Key.LEFT);
+    keyUp(Key.ALT);
+}
+
+export async function forward(this: NovaWindowsDriver): Promise<void> {
+    const elementId = (await this.sendPowerShellCommand(AutomationElement.automationRoot.buildCommand())).trim();
+    if (!elementId) {
+        throw new errors.NoSuchWindowError('No active window found for this session.');
+    }
+    keyDown(Key.ALT);
+    keyDown(Key.RIGHT);
+    keyUp(Key.RIGHT);
+    keyUp(Key.ALT);
+}
+
+export async function title(this: NovaWindowsDriver): Promise<string> {
+    const elementId = (await this.sendPowerShellCommand(AutomationElement.automationRoot.buildCommand())).trim();
+    if (!elementId) {
+        throw new errors.NoSuchWindowError('No active window found for this session.');
+    }
+    return await this.sendPowerShellCommand(
+        AutomationElement.automationRoot.buildGetPropertyCommand(Property.NAME)
+    );
+}
+
+export async function setWindowRect(
+    this: NovaWindowsDriver,
+    x: number | null,
+    y: number | null,
+    width: number | null,
+    height: number | null
+): Promise<Rect> {
+    if (width !== null && width < 0) {
+        throw new errors.InvalidArgumentError('width must be a non-negative integer.');
+    }
+    if (height !== null && height < 0) {
+        throw new errors.InvalidArgumentError('height must be a non-negative integer.');
+    }
+
+    const elementId = (await this.sendPowerShellCommand(AutomationElement.automationRoot.buildCommand())).trim();
+    if (!elementId) {
+        throw new errors.NoSuchWindowError('No active window found for this session.');
+    }
+
+    const el = new FoundAutomationElement(elementId);
+    if (x !== null && y !== null) {
+        await this.sendPowerShellCommand(el.buildMoveCommand(x, y));
+    }
+    if (width !== null && height !== null) {
+        await this.sendPowerShellCommand(el.buildResizeCommand(width, height));
+    }
+
+    return await this.getWindowRect();
+}
+
 export async function attachToApplicationWindow(this: NovaWindowsDriver, processIds: number[]): Promise<void> {
     const nativeWindowHandles = getWindowAllHandlesForProcessIds(processIds);
     this.log.debug(`Detected the following native window handles for the given process IDs: ${nativeWindowHandles.map((handle) => `0x${handle.toString(16).padStart(8, '0')}`).join(', ')}`);

lib/commands/element.ts

@@ -12,8 +12,9 @@ import {
     PSControlType,
     PSString,
     TreeScope,
+    pwsh$,
 } from '../powershell';
-import { W3C_ELEMENT_KEY } from '@appium/base-driver';
+import { errors, W3C_ELEMENT_KEY } from '@appium/base-driver';
 import { mouseDown, mouseMoveAbsolute, mouseUp } from '../winapi/user32';
 import { Key } from '../enums';
 import { sleep } from '../util';
@@ -239,4 +240,27 @@ export async function click(this: NovaWindowsDriver, elementId: string): Promise
     if (this.caps.delayAfterClick) {
         await sleep(this.caps.delayAfterClick ?? 0);
     }
+}
+
+const GET_ELEMENT_SCREENSHOT_COMMAND = pwsh$ /* ps1 */ `
+    $element = ${0}
+    $rect = $element.Current.BoundingRectangle
+    $bitmap = New-Object Drawing.Bitmap([int32]$rect.Width, [int32]$rect.Height)
+    $graphics = [Drawing.Graphics]::FromImage($bitmap)
+    $graphics.CopyFromScreen([int32]$rect.Left, [int32]$rect.Top, 0, 0, $bitmap.Size)
+    $graphics.Dispose()
+    $stream = New-Object IO.MemoryStream
+    $bitmap.Save($stream, [Drawing.Imaging.ImageFormat]::Png)
+    $bitmap.Dispose()
+    [Convert]::ToBase64String($stream.ToArray())
+`;
+
+export async function getElementScreenshot(this: NovaWindowsDriver, elementId: string): Promise<string> {
+    const rootId = (await this.sendPowerShellCommand(AutomationElement.automationRoot.buildCommand())).trim();
+    if (!rootId) {
+        throw new errors.NoSuchWindowError('No active window found for this session.');
+    }
+    return await this.sendPowerShellCommand(
+        GET_ELEMENT_SCREENSHOT_COMMAND.format(new FoundAutomationElement(elementId))
+    );
 }

lib/powershell/elements.ts

@@ -348,6 +348,8 @@ const MAXIMIZE_WINDOW = pwsh$ /* ps1 */ `${0}.GetCurrentPattern([WindowPattern]:
 const MINIMIZE_WINDOW = pwsh$ /* ps1 */ `${0}.GetCurrentPattern([WindowPattern]::Pattern).SetWindowVisualState([WindowVisualState]::Minimized)`;
 const RESTORE_WINDOW = pwsh$ /* ps1 */ `${0}.GetCurrentPattern([WindowPattern]::Pattern).SetWindowVisualState([WindowVisualState]::Normal)`;
 const CLOSE_WINDOW = pwsh$ /* ps1 */ `${0}.GetCurrentPattern([WindowPattern]::Pattern).Close()`;
+const MOVE_WINDOW = pwsh$ /* ps1 */ `${0}.GetCurrentPattern([TransformPattern]::Pattern).Move(${1}, ${2})`;
+const RESIZE_WINDOW = pwsh$ /* ps1 */ `${0}.GetCurrentPattern([TransformPattern]::Pattern).Resize(${1}, ${2})`;
 
 export const TreeScope = Object.freeze({
     ANCESTORS_OR_SELF: 'ancestors-or-self',
@@ -578,6 +580,14 @@ export class FoundAutomationElement extends AutomationElement {
         return CLOSE_WINDOW.format(this);
     }
 
+    buildMoveCommand(x: number, y: number): string {
+        return MOVE_WINDOW.format(this, x, y);
+    }
+
+    buildResizeCommand(width: number, height: number): string {
+        return RESIZE_WINDOW.format(this, width, height);
+    }
+
     override buildCommand(): string {
         return this.toString();
     }

test/commands/app/navigation.test.ts

@@ -0,0 +1,213 @@
+/**
+ * Unit tests for lib/commands/app.ts: back, forward, getTitle, setWindowRect
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { back, forward, title, setWindowRect } from '../../../lib/commands/app';
+import { createMockDriver } from '../../fixtures/driver';
+import { Key } from '../../../lib/enums';
+
+vi.mock('../../../lib/winapi/user32', () => ({
+    getWindowAllHandlesForProcessIds: vi.fn().mockReturnValue([]),
+    trySetForegroundWindow: vi.fn().mockReturnValue(true),
+    keyDown: vi.fn(),
+    keyUp: vi.fn(),
+}));
+
+const ELEMENT_ID = '1.2.3.4.5';
+
+describe('back', () => {
+    beforeEach(() => vi.clearAllMocks());
+
+    it('sends Alt+Left when a window is active', async () => {
+        const { keyDown, keyUp } = await import('../../../lib/winapi/user32');
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue(ELEMENT_ID);
+
+        await back.call(driver);
+
+        expect(keyDown).toHaveBeenNthCalledWith(1, Key.ALT);
+        expect(keyDown).toHaveBeenNthCalledWith(2, Key.LEFT);
+        expect(keyUp).toHaveBeenNthCalledWith(1, Key.LEFT);
+        expect(keyUp).toHaveBeenNthCalledWith(2, Key.ALT);
+    });
+
+    it('throws NoSuchWindowError when no active window', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue('');
+
+        await expect(back.call(driver)).rejects.toThrow('No active window found');
+    });
+
+    it('performs exactly one PS call (window check) before sending keys', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue(ELEMENT_ID);
+
+        await back.call(driver);
+
+        expect(driver.sendPowerShellCommand).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe('forward', () => {
+    beforeEach(() => vi.clearAllMocks());
+
+    it('sends Alt+Right when a window is active', async () => {
+        const { keyDown, keyUp } = await import('../../../lib/winapi/user32');
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue(ELEMENT_ID);
+
+        await forward.call(driver);
+
+        expect(keyDown).toHaveBeenNthCalledWith(1, Key.ALT);
+        expect(keyDown).toHaveBeenNthCalledWith(2, Key.RIGHT);
+        expect(keyUp).toHaveBeenNthCalledWith(1, Key.RIGHT);
+        expect(keyUp).toHaveBeenNthCalledWith(2, Key.ALT);
+    });
+
+    it('throws NoSuchWindowError when no active window', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue('');
+
+        await expect(forward.call(driver)).rejects.toThrow('No active window found');
+    });
+});
+
+describe('title (getTitle)', () => {
+    beforeEach(() => vi.clearAllMocks());
+
+    it('returns the window title from the Name property', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand
+            .mockResolvedValueOnce(ELEMENT_ID)       // window check
+            .mockResolvedValueOnce('Untitled - Notepad'); // Name property
+
+        const result = await title.call(driver);
+
+        expect(result).toBe('Untitled - Notepad');
+        expect(driver.sendPowerShellCommand).toHaveBeenCalledTimes(2);
+    });
+
+    it('returns an empty string when the window has no title', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand
+            .mockResolvedValueOnce(ELEMENT_ID)
+            .mockResolvedValueOnce('');
+
+        const result = await title.call(driver);
+
+        expect(result).toBe('');
+    });
+
+    it('throws NoSuchWindowError when no active window', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue('');
+
+        await expect(title.call(driver)).rejects.toThrow('No active window found');
+    });
+});
+
+describe('setWindowRect', () => {
+    beforeEach(() => vi.clearAllMocks());
+
+    const MOCK_RECT = { x: 100, y: 100, width: 800, height: 600 };
+
+    function createDriverWithRect(windowRect = MOCK_RECT) {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue(ELEMENT_ID);
+        driver.getWindowRect = vi.fn().mockResolvedValue(windowRect);
+        return driver;
+    }
+
+    it('calls Move and Resize when all four values are provided', async () => {
+        const driver = createDriverWithRect();
+
+        const result = await setWindowRect.call(driver, 100, 100, 800, 600);
+
+        // PS calls: window check + Move + Resize = 3
+        expect(driver.sendPowerShellCommand).toHaveBeenCalledTimes(3);
+        expect(driver.getWindowRect).toHaveBeenCalledTimes(1);
+        expect(result).toEqual(MOCK_RECT);
+    });
+
+    it('calls only Move when width and height are null', async () => {
+        const driver = createDriverWithRect();
+
+        await setWindowRect.call(driver, 50, 75, null, null);
+
+        // PS calls: window check + Move = 2
+        expect(driver.sendPowerShellCommand).toHaveBeenCalledTimes(2);
+    });
+
+    it('calls only Resize when x and y are null', async () => {
+        const driver = createDriverWithRect();
+
+        await setWindowRect.call(driver, null, null, 1024, 768);
+
+        // PS calls: window check + Resize = 2
+        expect(driver.sendPowerShellCommand).toHaveBeenCalledTimes(2);
+    });
+
+    it('skips Move and Resize when all arguments are null', async () => {
+        const driver = createDriverWithRect();
+
+        await setWindowRect.call(driver, null, null, null, null);
+
+        // PS calls: window check only = 1
+        expect(driver.sendPowerShellCommand).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns the new window rect from getWindowRect', async () => {
+        const expectedRect = { x: 200, y: 300, width: 1024, height: 768 };
+        const driver = createDriverWithRect(expectedRect);
+
+        const result = await setWindowRect.call(driver, 200, 300, 1024, 768);
+
+        expect(result).toEqual(expectedRect);
+    });
+
+    it('throws InvalidArgumentError for negative width', async () => {
+        const driver = createDriverWithRect();
+
+        await expect(setWindowRect.call(driver, 0, 0, -1, 600)).rejects.toThrow('width must be a non-negative integer');
+    });
+
+    it('throws InvalidArgumentError for negative height', async () => {
+        const driver = createDriverWithRect();
+
+        await expect(setWindowRect.call(driver, 0, 0, 800, -1)).rejects.toThrow('height must be a non-negative integer');
+    });
+
+    it('throws NoSuchWindowError when no active window', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValue('');
+        driver.getWindowRect = vi.fn();
+
+        await expect(setWindowRect.call(driver, 0, 0, 800, 600)).rejects.toThrow('No active window found');
+    });
+
+    it('the Move PS command contains TransformPattern and Move', async () => {
+        const driver = createDriverWithRect();
+
+        await setWindowRect.call(driver, 10, 20, null, null);
+
+        const moveCmdCall = driver.sendPowerShellCommand.mock.calls[1][0] as string;
+        const decoded = moveCmdCall.replace(/FromBase64String\('([^']+)'\)/g, (_, b64) =>
+            Buffer.from(b64, 'base64').toString('utf8')
+        );
+        expect(decoded).toContain('TransformPattern');
+        expect(decoded).toContain('Move');
+    });
+
+    it('the Resize PS command contains TransformPattern and Resize', async () => {
+        const driver = createDriverWithRect();
+
+        await setWindowRect.call(driver, null, null, 800, 600);
+
+        const resizeCmdCall = driver.sendPowerShellCommand.mock.calls[1][0] as string;
+        const decoded = resizeCmdCall.replace(/FromBase64String\('([^']+)'\)/g, (_, b64) =>
+            Buffer.from(b64, 'base64').toString('utf8')
+        );
+        expect(decoded).toContain('TransformPattern');
+        expect(decoded).toContain('Resize');
+    });
+});