fix(commands): match closeApp and launchApp implementation with appium windows driver

yuri-schwab · yuri-schwab · commit 073c566edb35 · 2026-03-06T14:54:26.000-03:00
diff --git a/lib/commands/app.ts b/lib/commands/app.ts
@@ -130,6 +130,23 @@ export async function setWindow(this: NovaWindowsDriver, nameOrHandle: string):
     throw new errors.NoSuchWindowError(`No window was found with name or handle '${nameOrHandle}'.`);
 }
 
+export async function closeApp(this: NovaWindowsDriver): Promise<void> {
+    const result = await this.sendPowerShellCommand(AutomationElement.automationRoot.buildCommand());
+    const elementId = result.split('\n').map((id) => id.trim()).filter(Boolean)[0];
+    if (!elementId) {
+        throw new errors.NoSuchWindowError('No active app window is found for this session.');
+    }
+    await this.sendPowerShellCommand(new FoundAutomationElement(elementId).buildCloseCommand());
+    await this.sendPowerShellCommand(/* ps1 */ `$rootElement = $null`);
+}
+
+export async function launchApp(this: NovaWindowsDriver): Promise<void> {
+    if (!this.caps.app || ['root', 'none'].includes(this.caps.app.toLowerCase())) {
+        throw new errors.InvalidArgumentError('No app capability is set for this session.');
+    }
+    await this.changeRootElement(this.caps.app);
+}
+
 export async function changeRootElement(this: NovaWindowsDriver, path: string): Promise<void>
 export async function changeRootElement(this: NovaWindowsDriver, nativeWindowHandle: number): Promise<void>
 export async function changeRootElement(this: NovaWindowsDriver, pathOrNativeWindowHandle: string | number): Promise<void> {
diff --git a/lib/commands/extension.ts b/lib/commands/extension.ts
@@ -1,15 +1,14 @@
 import { W3C_ELEMENT_KEY, errors } from '@appium/base-driver';
 import { Element, Rect } from '@appium/types';
 import { tmpdir } from 'node:os';
-import { join, normalize } from 'node:path';
+import { join } from 'node:path';
 import { POWER_SHELL_FEATURE } from '../constants';
 import { NovaWindowsDriver } from '../driver';
 import { ClickType, Enum, Key } from '../enums';
 import {
     AutomationElement,
     AutomationElementMode,
     FoundAutomationElement,
-    PSInt32,
     PSInt32Array,
     Property,
     PropertyCondition,
@@ -52,8 +51,8 @@ const EXTENSION_COMMANDS = Object.freeze({
     minimize: 'patternMinimize',
     restore: 'patternRestore',
     close: 'patternClose',
-    closeApp: 'closeApp',
-    launchApp: 'launchApp',
+    closeApp: 'windowsCloseApp',
+    launchApp: 'windowsLaunchApp',
     keys: 'executeKeys',
     click: 'executeClick',
     hover: 'executeHover',
@@ -256,69 +255,12 @@ export async function patternClose(this: NovaWindowsDriver, element: Element): P
     await this.sendPowerShellCommand(new FoundAutomationElement(element[W3C_ELEMENT_KEY]).buildCloseCommand());
 }
 
-export async function closeApp(this: NovaWindowsDriver, args: {
-    processId?: number,
-    processName?: string,
-    windowHandle?: string | number,
-}): Promise<void> {
-    const { processId, processName, windowHandle } = args ?? {};
-    const provided = [processId, processName, windowHandle].filter((v) => v != null).length;
-
-    if (provided !== 1) {
-        throw new errors.InvalidArgumentError(
-            'Exactly one of processId, processName, or windowHandle must be provided.'
-        );
-    }
-
-    if (processId != null) {
-        await this.sendPowerShellCommand(`Stop-Process -Id ${processId}`);
-        return;
-    }
-
-    if (processName != null) {
-        await this.sendPowerShellCommand(`Stop-Process -Name '${processName}'`);
-        return;
-    }
-
-    if (windowHandle != null) {
-        const handle = typeof windowHandle === 'string' ? parseInt(windowHandle, 16) : windowHandle;
-        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()
-        );
-        if (!elementId?.trim()) {
-            throw new errors.NoSuchWindowError(`No window found with handle ${windowHandle}`);
-        }
-        const processId = await this.sendPowerShellCommand(
-            new FoundAutomationElement(elementId.trim()).buildGetPropertyCommand(Property.PROCESS_ID)
-        );
-        if (!processId?.trim()) {
-            throw new errors.UnknownError(`Could not get process ID for window handle ${windowHandle}`);
-        }
-        await this.sendPowerShellCommand(`Stop-Process -Id ${processId.trim()}`);
-    }
+export async function windowsCloseApp(this: NovaWindowsDriver): Promise<void> {
+    return await this.closeApp();
 }
 
-export async function launchApp(this: NovaWindowsDriver, args: {
-    app: string,
-    appArguments?: string,
-}): Promise<void> {
-    if (!args || typeof args !== 'object' || !args.app) {
-        throw new errors.InvalidArgumentError("'app' must be provided.");
-    }
-
-    const { app, appArguments } = args;
-    if (app.includes('!') && app.includes('_') && !(app.includes('/') || app.includes('\\'))) {
-        this.log.debug('Detected app path to be in the UWP format.');
-        await this.sendPowerShellCommand(/* ps1 */ `Start-Process 'explorer.exe' 'shell:AppsFolder\\${app}'${appArguments ? ` -ArgumentList '${appArguments}'` : ''}`);
-    } else {
-        this.log.debug('Detected app path to be in the classic format.');
-        const normalizedPath = normalize(app);
-        await this.sendPowerShellCommand(/* ps1 */ `Start-Process '${normalizedPath}'${appArguments ? ` -ArgumentList '${appArguments}'` : ''}`);
-    }
-    await sleep(1500); // Wait for the app to start
+export async function windowsLaunchApp(this: NovaWindowsDriver): Promise<void> {
+    return await this.launchApp();
 }
 
 export async function focusElement(this: NovaWindowsDriver, element: Element): Promise<void> {
diff --git a/test/commands/app/closeApp.test.ts b/test/commands/app/closeApp.test.ts
@@ -0,0 +1,38 @@
+/**
+ * Unit tests for the W3C closeApp command (session-scoped).
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { closeApp } from '../../../lib/commands/app';
+import { createMockDriver } from '../../fixtures/driver';
+
+describe('closeApp (W3C)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it('closes the session app window via UI Automation close', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand
+            .mockResolvedValueOnce('element-123') // automationRoot.buildCommand()
+            .mockResolvedValueOnce(undefined) // buildCloseCommand()
+            .mockResolvedValueOnce(undefined); // $rootElement = $null
+
+        await closeApp.call(driver);
+
+        expect(driver.sendPowerShellCommand).toHaveBeenCalledTimes(3);
+    });
+
+    it('throws NoSuchWindowError when no root element exists', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValueOnce(''); // empty = window already gone
+
+        await expect(closeApp.call(driver)).rejects.toThrow('No active app window');
+    });
+
+    it('throws NoSuchWindowError when root element returns only whitespace', async () => {
+        const driver = createMockDriver() as any;
+        driver.sendPowerShellCommand.mockResolvedValueOnce('  \n  \n  ');
+
+        await expect(closeApp.call(driver)).rejects.toThrow('No active app window');
+    });
+});
diff --git a/test/commands/app/launchApp.test.ts b/test/commands/app/launchApp.test.ts
@@ -0,0 +1,54 @@
+/**
+ * Unit tests for the W3C launchApp command (session-scoped).
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { launchApp } from '../../../lib/commands/app';
+import { createMockDriver } from '../../fixtures/driver';
+
+describe('launchApp (W3C)', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it('re-launches the session app via changeRootElement', async () => {
+        const driver = createMockDriver() as any;
+        driver.caps = { app: 'C:\\Program Files\\notepad.exe' };
+        driver.changeRootElement = vi.fn().mockResolvedValue(undefined);
+
+        await launchApp.call(driver);
+
+        expect(driver.changeRootElement).toHaveBeenCalledWith('C:\\Program Files\\notepad.exe');
+        expect(driver.changeRootElement).toHaveBeenCalledTimes(1);
+    });
+
+    it('re-launches a UWP app via changeRootElement', async () => {
+        const driver = createMockDriver() as any;
+        driver.caps = { app: 'Microsoft.WindowsCalculator_8wekyb3d8bbwe!App' };
+        driver.changeRootElement = vi.fn().mockResolvedValue(undefined);
+
+        await launchApp.call(driver);
+
+        expect(driver.changeRootElement).toHaveBeenCalledWith('Microsoft.WindowsCalculator_8wekyb3d8bbwe!App');
+    });
+
+    it('throws InvalidArgumentError when app capability is not set', async () => {
+        const driver = createMockDriver() as any;
+        driver.caps = {};
+
+        await expect(launchApp.call(driver)).rejects.toThrow('No app capability is set');
+    });
+
+    it('throws InvalidArgumentError when app is "root"', async () => {
+        const driver = createMockDriver() as any;
+        driver.caps = { app: 'root' };
+
+        await expect(launchApp.call(driver)).rejects.toThrow('No app capability is set');
+    });
+
+    it('throws InvalidArgumentError when app is "none"', async () => {
+        const driver = createMockDriver() as any;
+        driver.caps = { app: 'none' };
+
+        await expect(launchApp.call(driver)).rejects.toThrow('No app capability is set');
+    });
+});
diff --git a/test/commands/extension/closeApp.test.ts b/test/commands/extension/closeApp.test.ts
diff --git a/test/commands/extension/execute.test.ts b/test/commands/extension/execute.test.ts
@@ -6,24 +6,24 @@ import * as extension from '../../../lib/commands/extension';
 import { createMockDriver, MOCK_ELEMENT } from '../../fixtures/driver';
 
 describe('execute (command router)', () => {
-    let driver: ReturnType<typeof createMockDriver> & Record<string, any>;
+    let driver: any;
 
     beforeEach(() => {
         vi.clearAllMocks();
         driver = createMockDriver() as any;
         Object.assign(driver, extension);
     });
 
-    it('routes windows:launchApp to launchApp with args', async () => {
-        await extension.execute.call(driver, 'windows: launchApp', [{ app: 'notepad.exe' }]);
-        expect(driver.sendPowerShellCommand).toHaveBeenCalledWith(
-            expect.stringContaining("Start-Process 'notepad.exe'")
-        );
+    it('routes windows:launchApp to windowsLaunchApp', async () => {
+        driver.launchApp = vi.fn().mockResolvedValue(undefined);
+        await extension.execute.call(driver, 'windows: launchApp', []);
+        expect(driver.launchApp).toHaveBeenCalledOnce();
     });
 
-    it('routes windows:closeApp to closeApp with args', async () => {
-        await extension.execute.call(driver, 'windows: closeApp', [{ processId: 12345 }]);
-        expect(driver.sendPowerShellCommand).toHaveBeenCalledWith('Stop-Process -Id 12345');
+    it('routes windows:closeApp to windowsCloseApp', async () => {
+        driver.closeApp = vi.fn().mockResolvedValue(undefined);
+        await extension.execute.call(driver, 'windows: closeApp', []);
+        expect(driver.closeApp).toHaveBeenCalledOnce();
     });
 
     it('routes windows:deleteFile to deleteFile with args', async () => {
diff --git a/test/commands/extension/launchApp.test.ts b/test/commands/extension/launchApp.test.ts
