appium-novawindows2-driver 0.1.1

package/examples/C#/CalculatorTest/CalculatorTest/ScenarioStandardInvoke.cs

@@ -0,0 +1,121 @@
+// Based on the original WinAppDriver Calculator test by Microsoft, licensed under the MIT License.
+
+using OpenQA.Selenium;
+using OpenQA.Selenium.Appium;
+
+namespace CalculatorTest;
+
+public class ScenarioStandardInvoke : CalculatorSession
+{
+    private static AppiumElement _header;
+    private static AppiumElement _calculatorResult;
+
+    [Test]
+    public void Addition()
+    {
+        // Find the buttons by their names and click them in sequence to perform 1 + 7 = 8
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name("One")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name("Plus")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name("Seven")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name("Equals")));
+        Assert.That(GetCalculatorResultText(), Is.EqualTo("8"));
+    }
+
+    [Test]
+    public void Division()
+    {
+        // Find the buttons by their accessibility ids and click them in sequence to perform 88 / 11 = 8
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.AccessibilityId("num8Button")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.AccessibilityId("num8Button")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.AccessibilityId("divideButton")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.AccessibilityId("num1Button")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.AccessibilityId("num1Button")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.AccessibilityId("equalButton")));
+        Assert.That(GetCalculatorResultText(), Is.EqualTo("8"));
+    }
+
+    [Test]
+    public void Multiplication()
+    {
+        // Find the buttons by their names using XPath and click them in sequence to perform 9 x 9 = 81
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@Name='Nine']")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@Name='Multiply by']")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@Name='Nine']")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@Name='Equals']")));
+        Assert.That(GetCalculatorResultText(), Is.EqualTo("81"));
+    }
+
+    [Test]
+    public void Subtraction()
+    {
+        // Find the buttons by their accessibility ids using XPath and click them in sequence to perform 9 - 1 = 8
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@AutomationId=\"num9Button\"]")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@AutomationId=\"minusButton\"]")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@AutomationId=\"num1Button\"]")));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(By.XPath("//Button[@AutomationId=\"equalButton\"]")));
+        Assert.That(GetCalculatorResultText(), Is.EqualTo("8"));
+    }
+
+    [TestCase("One",   "Plus",      "Seven", "8")]
+    [TestCase("Nine",  "Minus",     "One",   "8")]
+    [TestCase("Eight", "Divide by", "Eight", "1")]
+    public void Templatized(string input1, string operation, string input2, string expectedResult)
+    {
+        // Run sequence of button presses specified above and validate the results
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name(input1)));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name(operation)));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name(input2)));
+        Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.Name("Equals")));
+        Assert.That(GetCalculatorResultText(), Is.EqualTo(expectedResult));
+    }
+
+    [OneTimeSetUp]
+    public static void ClassInitialize()
+    {
+        // Create session to launch a Calculator window
+        Setup();
+
+        // Identify calculator mode by locating the header
+        try
+        {
+            _header = Session.FindElement(MobileBy.AccessibilityId("Header"));
+        }
+        catch
+        {
+            _header = Session.FindElement(MobileBy.AccessibilityId("ContentPresenter"));
+        }
+
+        // Ensure that calculator is in standard mode
+        if (!_header.Text.Equals("Standard", StringComparison.OrdinalIgnoreCase))
+        {
+            Session.ExecuteScript("windows: invoke", Session.FindElement(MobileBy.AccessibilityId("TogglePaneButton")));
+            Thread.Sleep(TimeSpan.FromSeconds(1));
+            var splitViewPane = Session.FindElement(MobileBy.ClassName("SplitViewPane"));
+            Session.ExecuteScript("windows: invoke", splitViewPane.FindElement(MobileBy.Name("Standard Calculator")));
+            Thread.Sleep(TimeSpan.FromSeconds(1));
+            Assert.That(_header.Text.Equals("Standard", StringComparison.OrdinalIgnoreCase), Is.True);
+        }
+
+        // Locate the calculatorResult element
+        _calculatorResult = Session.FindElement(MobileBy.AccessibilityId("CalculatorResults"));
+        Assert.That(_calculatorResult, Is.Not.Null);
+    }
+
+    [OneTimeTearDown]
+    public static void ClassCleanup()
+    {
+        TearDown();
+    }
+
+    [SetUp]
+    public void Clear()
+    {
+        Session.ExecuteScript("windows: invoke", Session?.FindElement(MobileBy.Name("Clear")));
+        Assert.That(GetCalculatorResultText(), Is.EqualTo("0"));
+    }
+
+    private static string GetCalculatorResultText()
+    {
+        return _calculatorResult.Text.Replace("Display is", string.Empty).Trim();
+    }
+}

package/examples/C#/CalculatorTest/CalculatorTest.sln

@@ -0,0 +1,16 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CalculatorTest", "CalculatorTest\CalculatorTest.csproj", "{AAB0751F-0906-4FE2-8725-BF90D7AC9F9D}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{AAB0751F-0906-4FE2-8725-BF90D7AC9F9D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{AAB0751F-0906-4FE2-8725-BF90D7AC9F9D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{AAB0751F-0906-4FE2-8725-BF90D7AC9F9D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{AAB0751F-0906-4FE2-8725-BF90D7AC9F9D}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+EndGlobal

package/lib/commands/actions.ts

@@ -0,0 +1,229 @@
+import {
+    ActionSequence,
+    KeyAction,
+    KeyActionSequence,
+    NullActionSequence,
+    PointerActionSequence,
+    PointerMoveAction,
+    Rect,
+    ScrollAction,
+    WheelActionSequence,
+} from '@appium/types';
+
+import { W3C_ELEMENT_KEY, errors } from '@appium/base-driver';
+import { NovaWindowsDriver } from '../driver';
+import { keyDown, keyUp, mouseMoveRelative, mouseMoveAbsolute, mouseDown, mouseUp, mouseScroll } from '../winapi/user32';
+import { sleep } from '../util';
+import { AutomationElement, FoundAutomationElement } from '../powershell';
+import { Key } from '../enums';
+
+export async function performActions(this: NovaWindowsDriver, actionSequences: ActionSequence[]): Promise<void> {
+    for (const actionSequence of actionSequences) {
+        switch (actionSequence.type) {
+            case 'key':
+                await this.handleKeyActionSequence(actionSequence);
+                break;
+            case 'wheel':
+                await this.handleWheelActionSequence(actionSequence);
+                break;
+            case 'pointer':
+                await this.handlePointerActionSequence(actionSequence);
+                break;
+            case 'none':
+                await this.handleNullActionSequence(actionSequence);
+                break;
+            default:
+                throw new errors.InvalidArgumentError();
+        }
+    }
+};
+
+export async function handleKeyActionSequence(this: NovaWindowsDriver, actionSequence: KeyActionSequence): Promise<void> {
+    const actions = actionSequence.actions;
+    for (const action of actions) {
+        await this.handleKeyAction(action);
+    }
+}
+
+export async function handlePointerActionSequence(this: NovaWindowsDriver, actionSequence: PointerActionSequence): Promise<void> {
+    switch (actionSequence.parameters?.pointerType) {
+        case 'touch':
+        case 'pen':
+            throw new errors.NotImplementedError(`Pointer type ${actionSequence.parameters?.pointerType} not implemented yet.`);
+        case 'mouse':
+        default:
+            await this.handleMousePointerActionSequence(actionSequence);
+    }
+}
+
+export async function handleMousePointerActionSequence(this: NovaWindowsDriver, actionSequence: PointerActionSequence): Promise<void> {
+    const actions = actionSequence.actions;
+    for (const action of actions) {
+        switch (action.type) {
+            case 'pointerMove':
+                await this.handleMouseMoveAction(action);
+                break;
+            case 'pointerDown':
+                mouseDown(action.button);
+                break;
+            case 'pointerUp':
+                mouseUp(action.button);
+                break;
+            case 'pause':
+                if (action.duration) {
+                    await sleep(action.duration);
+                }
+                break;
+            default:
+                throw new errors.InvalidArgumentError();
+        }
+    }
+}
+
+export async function handleWheelActionSequence(this: NovaWindowsDriver, actionSequence: WheelActionSequence): Promise<void> {
+    const actions = actionSequence.actions;
+    for (const action of actions) {
+        switch (action.type) {
+            case 'scroll':
+                await this.handleMouseMoveAction(action);
+                mouseScroll(action.deltaX, action.deltaY);
+                break;
+            case 'pause':
+                if (action.duration) {
+                    await sleep(action.duration);
+                }
+                break;
+            default:
+                throw new errors.InvalidArgumentError();
+        }
+    }
+}
+
+export async function handleNullActionSequence(this: NovaWindowsDriver, actionSequence: NullActionSequence): Promise<void> {
+    const actions = actionSequence.actions;
+    for (const action of actions) {
+        if (action.duration) {
+            await sleep(action.duration);
+        }
+    }
+}
+
+export async function handleMouseMoveAction(this: NovaWindowsDriver, action: PointerMoveAction | ScrollAction): Promise<void> {
+    const easingFunction = this.caps.smoothPointerMove;
+    switch (action.origin) {
+        case 'pointer':
+            await mouseMoveRelative(action.x, action.y, action.duration, easingFunction);
+            break;
+        case 'viewport': {
+            const rootRectJson = await this.sendPowerShellCommand(AutomationElement.automationRoot.buildGetElementRectCommand());
+            const rootRect = JSON.parse(rootRectJson.replaceAll(/(?:infinity)/gi, 0x7FFFFFFF.toString())) as Rect;
+            await mouseMoveAbsolute(action.x + rootRect.x, action.y + rootRect.y, action.duration, easingFunction);
+            break;
+        }
+        default:
+            if (action.origin?.[W3C_ELEMENT_KEY]) {
+                const element = new FoundAutomationElement(action.origin[W3C_ELEMENT_KEY]);
+                const rectJson = await this.sendPowerShellCommand(element.buildGetElementRectCommand());
+                let rect = JSON.parse(rectJson.replaceAll(/(?:infinity)/gi, 0x7FFFFFFF.toString())) as Rect;
+
+                if (Object.values(rect).some((x) => x === 0x7FFFFFFF)) {
+                    await this.sendPowerShellCommand(element.buildScrollIntoViewCommand());
+                    rect = JSON.parse(rectJson.replaceAll(/(?:infinity)/gi, 0x7FFFFFFF.toString())) as Rect;
+                }
+
+                await mouseMoveAbsolute(action.x === 0 ? rect.x + rect.width / 2 : action.x, action.y === 0 ? rect.y + rect.height / 2 : action.y, action.duration, easingFunction);
+                break;
+            }
+
+            throw new errors.InvalidArgumentError();
+    }
+}
+
+export async function handleKeyAction(this: NovaWindowsDriver, action: KeyAction): Promise<void> {
+    if (action.type === 'pause') {
+        if (action.duration) {
+            await sleep(action.duration);
+        }
+        return;
+    }
+
+    switch (action.value) {
+        case Key.SHIFT:
+        case Key.R_SHIFT:
+            if (action.type === 'keyDown') {
+                keyDown(action.value);
+                this.keyboardState.shift = true;
+                return;
+            }
+
+            keyUp(Key.SHIFT);
+            keyUp(Key.R_SHIFT);
+            this.keyboardState.shift = false;
+            return;
+        case Key.CONTROL:
+        case Key.R_CONTROL:
+            if (action.type === 'keyDown') {
+                keyDown(action.value);
+                this.keyboardState.ctrl = true;
+                return;
+            }
+
+            keyUp(Key.CONTROL);
+            keyUp(Key.R_CONTROL);
+            this.keyboardState.ctrl = false;
+            return;
+        case Key.META:
+        case Key.R_META:
+            if (action.type === 'keyDown') {
+                keyDown(action.value);
+                this.keyboardState.meta = true;
+                return;
+            }
+
+            keyUp(Key.META);
+            keyUp(Key.R_META);
+            this.keyboardState.meta = false;
+            return;
+        case Key.ALT:
+        case Key.R_ALT:
+            if (action.type === 'keyDown') {
+                keyDown(action.value);
+                this.keyboardState.alt = true;
+                return;
+            }
+
+            keyUp(Key.ALT);
+            keyUp(Key.R_ALT);
+            this.keyboardState.alt = false;
+            return;
+        case Key.NULL:
+            if (action.type === 'keyDown') {
+                if (this.keyboardState.shift) {
+                    await this.handleKeyAction({ type: 'keyUp', value: Key.SHIFT });
+                }
+                if (this.keyboardState.ctrl) {
+                    await this.handleKeyAction({ type: 'keyUp', value: Key.CONTROL });
+                }
+                if (this.keyboardState.meta) {
+                    await this.handleKeyAction({ type: 'keyUp', value: Key.META });
+                }
+                if (this.keyboardState.alt) {
+                    await this.handleKeyAction({ type: 'keyUp', value: Key.ALT });
+                }
+                for (const key in Array.of(this.keyboardState.pressed)) {
+                    keyUp(key);
+                    this.keyboardState.pressed.delete(key);
+                }
+            }
+            return;
+        default:
+            if (action.type === 'keyDown') {
+                keyDown(action.value);
+                this.keyboardState.pressed.add(action.value);
+            }
+            else {
+                keyUp(action.value);
+                this.keyboardState.pressed.delete(action.value);
+            }
+    }
+}

package/lib/commands/app.ts

@@ -0,0 +1,227 @@
+import { normalize } from 'node:path';
+import { Element, Rect } from '@appium/types';
+import { NovaWindowsDriver } from '../driver';
+import {
+    AutomationElement,
+    FoundAutomationElement,
+    PSInt32,
+    PSString,
+    Property,
+    PropertyCondition,
+    TreeScope,
+    TrueCondition,
+    pwsh$,
+    pwsh,
+} from '../powershell';
+import { sleep } from '../util';
+import { errors, W3C_ELEMENT_KEY } from '@appium/base-driver';
+import {
+    getWindowAllHandlesForProcessIds,
+    trySetForegroundWindow,
+} from '../winapi/user32';
+
+const GET_PAGE_SOURCE_COMMAND = pwsh$ /* ps1 */ `
+    $el = ${0}
+
+    if ($el -eq $null) {
+        $dummy = [xml]'<DummyRoot></DummyRoot>'
+        return $dummy.OuterXml
+    }
+
+    Get-PageSource $el |
+    ForEach-Object { $_.OuterXml }
+`;
+
+const GET_SCREENSHOT_COMMAND = pwsh /* ps1 */ `
+    if ($rootElement -eq $null) {
+        $bitmap = New-Object Drawing.Bitmap 1,1
+        $stream = New-Object IO.MemoryStream
+        $bitmap.Save($stream, [Drawing.Imaging.ImageFormat]::Png)
+        $bitmap.Dispose()
+        return [Convert]::ToBase64String($stream.ToArray())
+    }
+
+    $rect = $rootElement.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 getPageSource(this: NovaWindowsDriver): Promise<string> {
+    return await this.sendPowerShellCommand(GET_PAGE_SOURCE_COMMAND.format(AutomationElement.automationRoot));
+}
+
+export async function getScreenshot(this: NovaWindowsDriver): Promise<string> {
+    const automationRootId = await this.sendPowerShellCommand(AutomationElement.automationRoot.buildCommand());
+
+    if (this.caps.app && this.caps.app.toLowerCase() !== 'root') {
+        try {
+            await this.focusElement({
+                [W3C_ELEMENT_KEY]: automationRootId.trim(),
+            } satisfies Element);
+        } catch {
+            // noop
+        }
+    }
+
+    return await this.sendPowerShellCommand(GET_SCREENSHOT_COMMAND);
+}
+
+export async function getWindowRect(this: NovaWindowsDriver): Promise<Rect> {
+    const result = await this.sendPowerShellCommand(AutomationElement.automationRoot.buildGetElementRectCommand());
+    return JSON.parse(result.replaceAll(/(?:infinity)/gi, 0x7FFFFFFF.toString()));
+}
+
+export async function getWindowHandle(this: NovaWindowsDriver): Promise<string> {
+    const nativeWindowHandle = await this.sendPowerShellCommand(AutomationElement.automationRoot.buildGetPropertyCommand(Property.NATIVE_WINDOW_HANDLE));
+    return `0x${Number(nativeWindowHandle).toString(16).padStart(8, '0')}`;
+}
+
+export async function getWindowHandles(this: NovaWindowsDriver): Promise<string[]> {
+    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[] = [];
+
+    for (const elId of elIds) {
+        const nativeWindowHandle = await this.sendPowerShellCommand(new FoundAutomationElement(elId).buildGetPropertyCommand(Property.NATIVE_WINDOW_HANDLE));
+        nativeWindowHandles.push(`0x${Number(nativeWindowHandle).toString(16).padStart(8, '0')}`);
+    }
+
+    return nativeWindowHandles;
+}
+
+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
+        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());
+
+            if (elementId.trim() !== '') {
+                await this.sendPowerShellCommand(/* ps1 */ `$rootElement = ${new FoundAutomationElement(elementId).buildCommand()}`);
+                trySetForegroundWindow(handle);
+                return;
+            }
+        }
+
+        const name = nameOrHandle;
+        const condition = new PropertyCondition(Property.NAME, new PSString(name));
+        const elementId = await this.sendPowerShellCommand(AutomationElement.rootElement.findFirst(TreeScope.CHILDREN, condition).buildCommand());
+
+        if (elementId.trim() !== '') {
+            this.log.info(`Found window with name '${name}'. Setting it as the root element.`);
+            await this.sendPowerShellCommand(/* ps1 */ `$rootElement = ${new FoundAutomationElement(elementId).buildCommand()}`);
+            trySetForegroundWindow(handle);
+            return;
+        }
+
+        this.log.info(`Failed to locate window with name '${name}'. Sleeping for 500 milliseconds and retrying... (${i}/20)`); // TODO: make a setting for the number of retries or timeout
+        await sleep(500); // TODO: make a setting for the sleep timeout
+    }
+
+    throw new errors.NoSuchWindowError(`No window was found with name or handle '${nameOrHandle}'.`);
+}
+
+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> {
+    if (typeof pathOrNativeWindowHandle === 'number') {
+        const nativeWindowHandle = pathOrNativeWindowHandle;
+        const condition = new PropertyCondition(Property.NATIVE_WINDOW_HANDLE, new PSInt32(nativeWindowHandle));
+        const elementId = await this.sendPowerShellCommand(AutomationElement.rootElement.findFirst(TreeScope.CHILDREN_OR_SELF, condition).buildCommand());
+
+        if (elementId.trim() !== '') {
+            await this.sendPowerShellCommand(/* ps1 */ `$rootElement = ${new FoundAutomationElement(elementId).buildCommand()}`);
+            trySetForegroundWindow(nativeWindowHandle);
+            return;
+        }
+
+        throw new errors.UnknownError('Failed to locate top level window with that window handle.');
+    }
+
+
+    const path = pathOrNativeWindowHandle;
+    if (path.includes('!') && path.includes('_') && !(path.includes('/') || path.includes('\\'))) {
+        this.log.debug('Detected app path to be in the UWP format.');
+        await this.sendPowerShellCommand(/* ps1 */ `Start-Process 'explorer.exe' 'shell:AppsFolder\\${path}'${this.caps.appArguments ? ` -ArgumentList '${this.caps.appArguments}'` : ''}`);
+        await sleep(500); // TODO: make a setting for the initial wait time
+        for (let i = 1; i <= 20; i++) {
+            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.join(', '));
+            try {
+                await this.attachToApplicationWindow(processIds);
+                return;
+            } catch {
+                // noop
+            }
+
+            this.log.info(`Failed to locate window of the app. Sleeping for 500 milliseconds and retrying... (${i}/20)`); // TODO: make a setting for the number of retries or timeout
+            await sleep(500); // TODO: make a setting for the sleep timeout
+        }
+    } else {
+        this.log.debug('Detected app path to be in the classic format.');
+        const normalizedPath = normalize(path);
+        await this.sendPowerShellCommand(/* ps1 */ `Start-Process '${normalizedPath}'${this.caps.appArguments ? ` -ArgumentList '${this.caps.appArguments}'` : ''}`);
+        await sleep(500); // TODO: make a setting for the initial wait time
+        for (let i = 1; i <= 20; i++) {
+            try {
+                const breadcrumbs = normalizedPath.toLowerCase().split('\\').flatMap((x) => x.split('/'));
+                const executable = breadcrumbs[breadcrumbs.length - 1];
+                const processName = executable.endsWith('.exe') ? executable.slice(0, executable.length - 4) : executable;
+                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(', '));
+
+                await this.attachToApplicationWindow(processIds);
+                return;
+            } catch (err) {
+                if (err instanceof Error) {
+                    this.log.debug(`Received error:\n${err.message}`);
+                }
+            }
+
+            this.log.info(`Failed to locate window of the app. Sleeping for 500 milliseconds and retrying... (${i}/20)`); // TODO: make a setting for the number of retries or timeout
+            await sleep(500); // TODO: make a setting for the sleep timeout
+        }
+    }
+
+    throw new errors.UnknownError('Failed to locate window of the app.');
+}
+
+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(', ')}`);
+
+    if (nativeWindowHandles.length !== 0) {
+        let elementId = '';
+        for (let i = 1; i <= 20; i++) {
+            elementId = await this.sendPowerShellCommand(AutomationElement.rootElement.findFirst(TreeScope.CHILDREN, new PropertyCondition(Property.NATIVE_WINDOW_HANDLE, new PSInt32(nativeWindowHandles[0]))).buildCommand());
+            if (elementId) {
+                break;
+            }
+            this.log.info(`The window with handle 0x${nativeWindowHandles[0].toString(16).padStart(8, '0')} is not yet available in the UI Automation tree. Sleeping for 500 milliseconds and retrying... (${i}/20)`); // TODO: make a setting for the number of retries or timeout
+            await sleep(500); // TODO: make a setting for the sleep timeout
+        }
+
+        await this.sendPowerShellCommand(/* ps1 */ `$rootElement = ${new FoundAutomationElement(elementId).buildCommand()}`);
+        if ((await this.sendPowerShellCommand(/* ps1 */ `$null -ne $rootElement`)).toLowerCase() === 'true') {
+            const nativeWindowHandle = Number(await this.sendPowerShellCommand(AutomationElement.automationRoot.buildGetPropertyCommand(Property.NATIVE_WINDOW_HANDLE)));
+            if (!trySetForegroundWindow(nativeWindowHandle)) {
+                await this.focusElement({
+                    [W3C_ELEMENT_KEY]: elementId,
+                } satisfies Element);
+            };
+            return;
+        }
+    }
+}

package/lib/commands/device.ts

@@ -0,0 +1,41 @@
+import { NovaWindowsDriver } from '../driver';
+import { PSString, pwsh$ } from '../powershell';
+
+const GET_SYSTEM_TIME_COMMAND = pwsh$ /* ps1 */ `(Get-Date).ToString(${0})`;
+const ISO_8061_FORMAT = 'yyyy-MM-ddTHH:mm:sszzz';
+
+export async function getDeviceTime(this: NovaWindowsDriver, format?: string): Promise<string> {
+    format = format ? new PSString(format).toString() : `'${ISO_8061_FORMAT}'`;
+    return await this.sendPowerShellCommand(GET_SYSTEM_TIME_COMMAND.format(format));
+}
+
+// command: 'hideKeyboard'
+// payloadParams: { optional: ['strategy', 'key', 'keyCode', 'keyName'] }
+
+// command: 'isKeyboardShown'
+
+// command: 'pushFile'
+// payloadParams: { required: ['path', 'data'] }
+
+// command: 'pullFile'
+// payloadParams: { required: ['path'] }
+
+// command: 'pullFolder'
+// payloadParams: { required: ['path'] }
+
+// # APP MANAGEMENT
+
+// command: 'activateApp'
+// payloadParams: { required: [['appId'], ['bundleId']], optional: ['options'] }
+
+// command: 'removeApp'
+// payloadParams: { required: [['appId'], ['bundleId']], optional: ['options'] }
+
+//command: 'terminateApp'
+// payloadParams: { required: [['appId'], ['bundleId']], optional: ['options'] }
+
+// command: 'isAppInstalled'
+// payloadParams: { required: [['appId'], ['bundleId']] }
+
+// command: 'installApp'
+// payloadParams: { required: ['appPath'], optional: ['options'] }