Merge pull request #12 from verisoft-ai/fix/window-handle-access

Fix/window handle access

Author: y-schwab

README.md

@@ -49,6 +49,7 @@ prerun | An object containing either `script` or `command` key. The value of eac
 postrun | An object containing either `script` or `command` key. The value of each key must be a valid PowerShell script or command to be executed after WinAppDriver session is stopped. See [Power Shell commands execution](#power-shell-commands-execution) for more details.
 isolatedScriptExecution | Whether PowerShell scripts are executed in an isolated session. Default is `false`.
 appEnvironment | Optional object of custom environment variables to inject into the PowerShell session. The variables are only available for the lifetime of the session and do not affect the system environment. Example: `{"MY_VAR": "hello", "API_URL": "http://localhost:3000"}`.
+returnAllWindowHandles | When `true`, `getWindowHandles()` returns all top-level windows on the desktop (UIA root children) instead of only the windows belonging to the launched app. Useful for switching to arbitrary system windows. Default is `false`.
 
 Please note that more capabilities will be added as the development of this driver progresses. Since it is still in its early stages, some features may be missing or subject to change. If you need a specific capability or encounter any issues, please feel free to open an issue.
 

lib/commands/app.ts

@@ -91,6 +91,11 @@ export async function getWindowHandle(this: NovaWindowsDriver): Promise<string>
 }
 
 export async function getWindowHandles(this: NovaWindowsDriver): Promise<string[]> {
+    if (this.appProcessIds.length > 0 && !this.caps.returnAllWindowHandles) {
+        const handles = getWindowAllHandlesForProcessIds(this.appProcessIds);
+        return handles.map((h) => `0x${h.toString(16).padStart(8, '0')}`);
+    }
+
     const result = await this.sendPowerShellCommand(AutomationElement.rootElement.findAll(TreeScope.CHILDREN, new TrueCondition()).buildCommand());
     const elIds = result.split('\n').map((x) => x.trim()).filter(Boolean);
     const nativeWindowHandles: string[] = [];
@@ -163,6 +168,11 @@ export async function changeRootElement(this: NovaWindowsDriver, pathOrNativeWin
         if (elementId.trim() !== '') {
             await this.sendPowerShellCommand(/* ps1 */ `$rootElement = ${new FoundAutomationElement(elementId).buildCommand()}`);
             trySetForegroundWindow(nativeWindowHandle);
+            const pidResult = await this.sendPowerShellCommand(`$rootElement.Current.ProcessId`);
+            const pid = Number(pidResult.trim());
+            if (!isNaN(pid) && pid > 0) {
+                this.appProcessIds = [pid];
+            }
             return;
         }
 
@@ -177,7 +187,12 @@ export async function changeRootElement(this: NovaWindowsDriver, pathOrNativeWin
         const result = await this.sendPowerShellCommand(/* ps1 */ `(Get-Process -Name 'ApplicationFrameHost').Id`);
         const processIds = result.split('\n').map((pid) => pid.trim()).filter(Boolean).map(Number);
         this.log.debug(`Process IDs of ApplicationFrameHost processes (${processIds.length}): ` + processIds.join(', '));
+        this.appProcessIds = processIds;
         await this.attachToApplicationWindow(processIds);
+        const attachedPid = Number((await this.sendPowerShellCommand(`$rootElement.Current.ProcessId`)).trim());
+        if (!isNaN(attachedPid) && attachedPid > 0) {
+            this.appProcessIds = [attachedPid];
+        }
     } else {
         this.log.debug('Detected app path to be in the classic format.');
         const normalizedPath = normalize(path);
@@ -188,7 +203,12 @@ export async function changeRootElement(this: NovaWindowsDriver, pathOrNativeWin
         const result = await this.sendPowerShellCommand(/* ps1 */ `(Get-Process -Name '${processName}' | Sort-Object StartTime -Descending).Id`);
         const processIds = result.split('\n').map((pid) => pid.trim()).filter(Boolean).map(Number);
         this.log.debug(`Process IDs of '${processName}' processes: ` + processIds.join(', '));
+        this.appProcessIds = processIds;
         await this.attachToApplicationWindow(processIds);
+        const attachedPid = Number((await this.sendPowerShellCommand(`$rootElement.Current.ProcessId`)).trim());
+        if (!isNaN(attachedPid) && attachedPid > 0) {
+            this.appProcessIds = [attachedPid];
+        }
     }
 }
 

lib/constraints.ts

@@ -45,6 +45,9 @@ export const UI_AUTOMATION_DRIVER_CONSTRAINTS = {
     'ms:forcequit': {
         isBoolean: true,
     },
+    returnAllWindowHandles: {
+        isBoolean: true,
+    },
 } as const satisfies Constraints;
 
 export default UI_AUTOMATION_DRIVER_CONSTRAINTS;

lib/driver.ts

@@ -60,6 +60,7 @@ export class NovaWindowsDriver extends BaseDriver<NovaWindowsDriverConstraints,
     powerShell?: ChildProcessWithoutNullStreams;
     powerShellStdOut: string = '';
     powerShellStdErr: string = '';
+    appProcessIds: number[] = [];
     keyboardState: KeyboardState = {
         pressed: new Set(),
         alt: false,

test/e2e/window.e2e.ts

@@ -1,19 +1,23 @@
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import type { Browser } from 'webdriverio';
-import { createCalculatorSession, createRootSession, quitSession } from './helpers/session.js';
+import { closeAllTestApps, createCalculatorSession, createRootSession, quitSession } from './helpers/session.js';
 
 describe('Window and app management commands', () => {
     let calc: Browser;
+    let calcAllHandles: Browser;
     let root: Browser;
 
     beforeAll(async () => {
         calc = await createCalculatorSession();
+        calcAllHandles = await createCalculatorSession({ 'appium:returnAllWindowHandles': true });
         root = await createRootSession();
     });
 
     afterAll(async () => {
         await quitSession(calc);
+        await quitSession(calcAllHandles);
         await quitSession(root);
+        closeAllTestApps();
     });
 
     describe('getWindowHandle', () => {
@@ -30,13 +34,39 @@ describe('Window and app management commands', () => {
     });
 
     describe('getWindowHandles', () => {
-        it('returns an array from the Root session', async () => {
-            const handles = await root.getWindowHandles();
-            expect(Array.isArray(handles)).toBe(true);
+        it('(app session, default) returns only the app windows — not all desktop windows', async () => {
+            const appHandles = await calc.getWindowHandles();
+            expect(appHandles.length).toBeGreaterThanOrEqual(1);
+        });
+
+        it('(app session, default) includes the current window handle', async () => {
+            const current = await calc.getWindowHandle();
+            const handles = await calc.getWindowHandles();
+            expect(handles).toContain(current);
+        });
+
+        it('(app session, default) all returned handles match the 0x hex format', async () => {
+            const handles = await calc.getWindowHandles();
+            for (const h of handles) {
+                expect(h).toMatch(/^0x[0-9a-fA-F]{8}$/);
+            }
         });
 
-        it('returns at least one window handle from the desktop', async () => {
+        it('(returnAllWindowHandles=true) returns all desktop windows, same count as root session', async () => {
+            const appAllHandles = await calcAllHandles.getWindowHandles();
+            const rootHandles = await root.getWindowHandles();
+            expect(appAllHandles.length).toBe(rootHandles.length);
+        });
+
+        it('(returnAllWindowHandles=true) includes the current app window handle', async () => {
+            const current = await calc.getWindowHandle();
+            const appAllHandles = await calcAllHandles.getWindowHandles();
+            expect(appAllHandles).toContain(current);
+        });
+
+        it('(root session) returns an array of at least one window handle', async () => {
             const handles = await root.getWindowHandles();
+            expect(Array.isArray(handles)).toBe(true);
             expect(handles.length).toBeGreaterThanOrEqual(1);
         });
     });

test/fixtures/driver.ts

@@ -8,6 +8,8 @@ export interface MockDriver {
     sendPowerShellCommand: ReturnType<typeof vi.fn>;
     log: { debug: ReturnType<typeof vi.fn>; info?: ReturnType<typeof vi.fn> };
     assertFeatureEnabled: ReturnType<typeof vi.fn>;
+    appProcessIds: number[];
+    caps: Record<string, unknown>;
 }
 
 export function createMockDriver(overrides?: Partial<MockDriver>): MockDriver {
@@ -18,6 +20,8 @@ export function createMockDriver(overrides?: Partial<MockDriver>): MockDriver {
         sendPowerShellCommand,
         log,
         assertFeatureEnabled,
+        appProcessIds: [],
+        caps: {},
         ...overrides,
     };
     return driver;