feat(capability): Add capabilities windowSwitchRetries and windowSwitchInterval

Non-negative number of retries and timeout between retries expected asarguments

Author: y-schwab

README.md

@@ -50,6 +50,9 @@ postrun | An object containing either `script` or `command` key. The value of ea
 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`.
+ms:waitForAppLaunch | Time in seconds to wait for the app window to appear after launch. Default is `0` (falls back to 10 000 ms internal timeout).
+ms:windowSwitchRetries | Maximum number of retry attempts in `setWindow()` when the target window is not yet visible. Must be a non-negative integer. Default is `20`.
+ms:windowSwitchInterval | Sleep duration in milliseconds between each retry in `setWindow()`. Must be a non-negative integer. Default is `500`.
 
 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

@@ -110,7 +110,9 @@ export async function getWindowHandles(this: NovaWindowsDriver): Promise<string[
 
 export async function setWindow(this: NovaWindowsDriver, nameOrHandle: string): Promise<void> {
     const handle = Number(nameOrHandle);
-    for (let i = 1; i <= 20; i++) { // TODO: make a setting for the number of retries or timeout
+    const maxRetries = this.caps['ms:windowSwitchRetries'] ?? 20;
+    const sleepInterval = this.caps['ms:windowSwitchInterval'] ?? SLEEP_INTERVAL_MS;
+    for (let i = 1; i <= maxRetries; i++) {
         if (!isNaN(handle)) {
             const condition = new PropertyCondition(Property.NATIVE_WINDOW_HANDLE, new PSInt32(handle));
             const elementId = await this.sendPowerShellCommand(AutomationElement.rootElement.findFirst(TreeScope.CHILDREN_OR_SELF, condition).buildCommand());
@@ -133,8 +135,8 @@ export async function setWindow(this: NovaWindowsDriver, nameOrHandle: string):
             return;
         }
 
-        this.log.info(`Failed to locate window with name '${name}'. Sleeping for ${SLEEP_INTERVAL_MS} milliseconds and retrying... (${i}/20)`); // TODO: make a setting for the number of retries or timeout
-        await sleep(SLEEP_INTERVAL_MS); // TODO: make a setting for the sleep timeout
+        this.log.info(`Failed to locate window with name '${name}'. Sleeping for ${sleepInterval} milliseconds and retrying... (${i}/${maxRetries})`);
+        await sleep(sleepInterval);
     }
 
     throw new errors.NoSuchWindowError(`No window was found with name or handle '${nameOrHandle}'.`);

lib/constraints.ts

@@ -48,6 +48,12 @@ export const UI_AUTOMATION_DRIVER_CONSTRAINTS = {
     returnAllWindowHandles: {
         isBoolean: true,
     },
+    'ms:windowSwitchRetries': {
+        isNumber: true,
+    },
+    'ms:windowSwitchInterval': {
+        isNumber: true,
+    },
 } as const satisfies Constraints;
 
 export default UI_AUTOMATION_DRIVER_CONSTRAINTS;

lib/driver.ts

@@ -20,7 +20,8 @@ import {
     convertStringToCondition,
 } from './powershell';
 import {
-    assertSupportedEasingFunction
+    assertIntegerCap,
+    assertSupportedEasingFunction,
 } from './util';
 import { setDpiAwareness } from './winapi/user32';
 import { xpathToElIdOrIds } from './xpath';
@@ -187,6 +188,12 @@ export class NovaWindowsDriver extends BaseDriver<NovaWindowsDriverConstraints,
                     );
                 }
             }
+            if (caps['ms:windowSwitchRetries'] !== undefined) {
+                assertIntegerCap('ms:windowSwitchRetries', caps['ms:windowSwitchRetries'], 0);
+            }
+            if (caps['ms:windowSwitchInterval'] !== undefined) {
+                assertIntegerCap('ms:windowSwitchInterval', caps['ms:windowSwitchInterval'], 0);
+            }
             if (this.caps.shouldCloseApp === undefined) {
                 this.caps.shouldCloseApp = true; // set default value
             }

lib/util.ts

@@ -26,6 +26,14 @@ export function assertSupportedEasingFunction(value: string) {
     }
 }
 
+export function assertIntegerCap(capName: string, value: number, min: number): void {
+    if (!Number.isInteger(value) || value < min) {
+        throw new errors.InvalidArgumentError(
+            `Invalid capability '${capName}': must be an integer >= ${min} (got ${value}).`
+        );
+    }
+}
+
 export function sleep(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, Math.max(ms, 0)));
 }

test/commands/app/app.test.ts

@@ -125,9 +125,23 @@ describe('setWindow', () => {
 
     it('throws NoSuchWindowError when window is not found after retries', async () => {
         const driver = createMockDriver() as any;
+        driver.caps['ms:windowSwitchRetries'] = 1;
+        driver.caps['ms:windowSwitchInterval'] = 0;
         // All calls return empty (window not found)
         driver.sendPowerShellCommand.mockResolvedValue('');
 
         await expect(setWindow.call(driver, 'NonExistentWindow')).rejects.toThrow('No window was found');
-    }, 10000);
+    });
+
+    it('respects ms:windowSwitchRetries cap', async () => {
+        const driver2 = createMockDriver() as any;
+        driver2.caps['ms:windowSwitchRetries'] = 2;
+        driver2.caps['ms:windowSwitchInterval'] = 0;
+        driver2.sendPowerShellCommand.mockResolvedValue('');
+
+        // Use a numeric handle string so both the handle search and name search run per iteration (2 PS calls each)
+        await expect(setWindow.call(driver2, '99999')).rejects.toThrow('No window was found');
+        // 2 retries × 2 PS commands (handle search + name search) = 4 calls
+        expect(driver2.sendPowerShellCommand.mock.calls.length).toBe(4);
+    });
 });

test/util.test.ts

@@ -2,7 +2,34 @@
  * Unit tests for lib/util.ts
  */
 import { describe, it, expect } from 'vitest';
-import { assertSupportedEasingFunction, $ } from '../lib/util';
+import { assertIntegerCap, assertSupportedEasingFunction, $ } from '../lib/util';
+
+describe('assertIntegerCap', () => {
+    it('accepts value equal to min', () => {
+        expect(() => assertIntegerCap('x', 0, 0)).not.toThrow();
+        expect(() => assertIntegerCap('x', 1, 1)).not.toThrow();
+    });
+
+    it('accepts value above min', () => {
+        expect(() => assertIntegerCap('x', 5, 1)).not.toThrow();
+        expect(() => assertIntegerCap('x', 100, 0)).not.toThrow();
+    });
+
+    it('throws for value below min', () => {
+        expect(() => assertIntegerCap('ms:windowSwitchRetries', 0, 1)).toThrow('must be an integer >= 1');
+        expect(() => assertIntegerCap('ms:windowSwitchInterval', -1, 0)).toThrow('must be an integer >= 0');
+    });
+
+    it('throws for floats', () => {
+        expect(() => assertIntegerCap('x', 1.5, 1)).toThrow('must be an integer');
+        expect(() => assertIntegerCap('x', 0.1, 0)).toThrow('must be an integer');
+    });
+
+    it('includes cap name and received value in error message', () => {
+        expect(() => assertIntegerCap('ms:windowSwitchRetries', -3, 1)).toThrow("'ms:windowSwitchRetries'");
+        expect(() => assertIntegerCap('ms:windowSwitchRetries', -3, 1)).toThrow('got -3');
+    });
+});
 
 describe('assertSupportedEasingFunction', () => {
     it.each(['linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out'])(