@react-native-windows/automation 0.0.0-canary.1016

package/README.md

@@ -0,0 +1,154 @@
+# @react-native-windows/automation
+
+`@react-native-windows/automation` makes it easy to perform UI tests against
+your `react-native-windows` application using Jest. 
+
+**This package is a work in progress**
+
+## System Requirements
+
+`@react-native-windows/automation` relies on [WinAppDriver 1.2.1](https://github.com/microsoft/WinAppDriver/releases/tag/v1.2.1)
+or later to manipulate and inspect your application via [Windows UI Automation](https://docs.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-overview).
+This is already installed in common CI environments like GitHub Actions or
+Azure Pipelines hosted images.
+
+## Configuring Jest
+
+First, ensure that `@react-native-windows/automation` is included as a
+dependency in your package:
+
+```json
+{
+  "devDependencies": {
+    "@react-native-windows/automation": "<version>",
+  }
+}
+```
+
+Next, edit your [Jest configuration](https://jestjs.io/docs/configuration) to
+use `@react-native-windows/automation` as your test environment. Add the
+following to your `jest.config.js` or `jest.config.ts` file:
+
+```js
+module.exports = {
+...
+  // Set up the automation environment before running tests
+  testEnvironment: '@react-native-windows/automation',
+
+  // Only run a single test at a time
+  maxWorkers: 1,
+
+  // Set up @react-native-windows/automation specific options (see below)
+  testEnvironmentOptions: {
+    app: '<AppName>',
+  },
+};
+```
+
+## Environment Options
+
+`@react-native-windows/automation` is configured via the
+`testEnvironmentOptions` property in your Jest configuration. The following
+options are valid:
+
+```js
+testEnvironmentOptions: {
+  // Required: Your application to launch, as either an AppX package identity,
+  // or path to an .exe for an unpackaged application.
+  app: 'Microsoft.WindowsAlarms',
+
+  /**
+   * Optional: Arguments to be passed to your application when launched
+   */
+  appArguments: '--bundle testBundle.js';
+
+  // Optional: Explicit path to WinAppDriver. By default,
+  // `@react-native-windows/automation` tries to use
+  // "%PROGRAMFILES(X86)%\Windows Application Driver\WinAppDriver.exe"
+  winAppDriverBin: 'D:\\WinAppDriver.exe',
+
+  // Optional: Whether to break on app launch, before starting tests 
+  breakOnStart: false,
+
+  // Optional: Options to be passed to WebDriverIO
+  // See https://webdriver.io/docs/options/
+  webdriverOptions: {
+      // Port to use for WebDriver server (Default 4723)
+      port: 4444
+
+      // Level of logging verbosity: trace | debug | info | warn | error
+      logLevel: 'error',
+
+      // Default timeout for all waitFor* commands.
+      waitforTimeout: 60000,
+
+      // Default timeout in milliseconds for request
+      connectionRetryTimeout: 90000,
+
+      // Default request retries count
+      connectionRetryCount: 10,
+    },
+},
+```
+
+## Writing Tests
+
+`@react-native-windows/automation` exports an `app` member with functions to
+perform globally scoped WebDriver commands, such as locating an element or
+waiting for a condition. Several strategies are present to locate an element,
+with the reccomended being to use React Native's `testID` property.
+
+A located `AutomationElement` exposes methods to allow application interaction
+and introspection, such as clicking or typing.
+
+```js
+import {app} from '@react-native-windows/automation';
+
+beforeAll(async () => {
+  const appHeader = await app.findElementByTestID('app-header');
+
+  await app.waitUntil(async () => {
+    const headerText = await appHeader.getText();
+    return headerText.includes('Welcome');
+  }) 
+});
+
+test('Type abc', async () => {
+  const textInput = await app.findElementByTestID('textinput-field');
+  await textInput.setValue('abc');
+  expect(await textInput.getText()).toBe('abc');
+});
+```
+
+## Performing Additional Actions
+
+**WIP Not yet exposed**
+
+Sometimes it is useful to exmaine or manipulate the application in ways that
+are not exposed to Windows UI Automation. An additional package,
+`@react-native-windows/automation-channel` can be included in your application
+as a native module to allow writing custom commands performed by your
+application in-process. Some pre-built commands can be included using the
+`@react-native-windows/automation-commands` package.
+
+## Visual Comparison
+
+**WIP Not yet exposed**
+
+A common use-case of UI testing is to ensure your components look the way you
+expect. Tools like [enzyme](https://github.com/enzymejs/enzyme) allow
+inspecting your React component tree, but are oblivious to the native UI tree.
+
+`@react-native-windows/automation-commands` exposes a `dumpVisualTree` command
+which creates a JSON object corresponding to the XAML tree under a given
+testID. This can be used in conjunction with snapshot testing to validate
+native component logic stays consistent.
+
+```js
+import {dumpVisualTree} from '@react-native-windows/automation-commands';
+
+test('Widget', async () => {
+  const dump = await dumpVisualTree('widget-test-id');
+  expect(dump).toMatchSnapshot();
+});
+```

package/lib-commonjs/AutomationClient.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * @format
+ */
+/// <reference types="webdriverio/webdriverio-core" />
+/**
+ * Projection of a WebDriver Element, with functions corresponding to supported
+ * WinAppDriver APIs.
+ *
+ * See https://github.com/microsoft/WinAppDriver/blob/master/Docs/SupportedAPIs.md
+ */
+export type AutomationElement = Pick<WebdriverIO.Element, 'addValue' | 'clearValue' | 'click' | 'doubleClick' | 'findElements' | 'getAttribute' | 'getLocation' | 'getSize' | 'getText' | 'getValue' | 'isDisplayed' | 'isDisplayedInViewport' | 'isEnabled' | 'isEqual' | 'isSelected' | 'moveTo' | 'saveScreenshot' | 'sendKeys' | 'selectByVisibleText' | 'setValue' | 'touchAction' | 'waitForDisplayed' | 'waitForExist'>;
+/**
+ * A subset of WebDriver functionality that will work with Windows applications
+ */
+export declare const app: {
+    /**
+     * Find an element by testID property
+     */
+    findElementByTestID: (id: string) => Promise<AutomationElement>;
+    /**
+     * Find an element by Automation ID
+     *
+     * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.automationelement.automationelementinformation.automationid?view=net-6.0
+     */
+    findElementByAutomationID: (id: string) => Promise<AutomationElement>;
+    /**
+     * Finds an element by the name of its class name (e.g. ListViewItem)
+     *
+     * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.automationelement.automationelementinformation.classname?view=net-6.0
+     */
+    findElementByClassName: (className: string) => Promise<AutomationElement>;
+    /**
+     * Find element by ControlType (e.g. Button, CheckBox)
+     *
+     * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.controltype?view=net-6.0
+     */
+    findElementByControlType: (controlType: string) => Promise<AutomationElement>;
+    /**
+     * Find element by a WinAppDriver compatible XPath Selector (e.g. '//Button[@AutomationId=\"MoreButton\"]')
+     */
+    findElementByXPath: (xpath: string) => Promise<AutomationElement>;
+    /**
+     * Resizes app window outer size according to provided width and height.
+     */
+    setWindowSize: (width: number, height: number) => Promise<object | null>;
+    /**
+     * Change the position of the current focussed window.
+     */
+    setWindowPosition: (x: number, y: number) => Promise<WebDriver.ProtocolCommandResponse>;
+    /**
+     * Get the position of the current focussed window.
+     */
+    getWindowPosition: () => Promise<WebDriver.ProtocolCommandResponse>;
+    /**
+     * Returns app window size.
+     */
+    getWindowSize: () => Promise<WebDriver.RectReturn>;
+    /**
+     * Switch focus to a particular window.
+     */
+    switchWindow: (titleToMatch: string | RegExp) => Promise<void>;
+    /**
+     * This wait command is your universal weapon if you want to wait on something. It expects a condition
+     * and waits until that condition is fulfilled with a truthy value.
+     */
+    waitUntil: (condition: () => Promise<boolean>, options?: WebdriverIO.WaitUntilOptions) => Promise<boolean>;
+};

package/lib-commonjs/AutomationClient.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * @format
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.app = void 0;
+/**
+ * A subset of WebDriver functionality that will work with Windows applications
+ */
+exports.app = {
+    /**
+     * Find an element by testID property
+     */
+    findElementByTestID: (id) => $(`~${id}`),
+    /**
+     * Find an element by Automation ID
+     *
+     * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.automationelement.automationelementinformation.automationid?view=net-6.0
+     */
+    findElementByAutomationID: (id) => $(`~${id}`),
+    /**
+     * Finds an element by the name of its class name (e.g. ListViewItem)
+     *
+     * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.automationelement.automationelementinformation.classname?view=net-6.0
+     */
+    findElementByClassName: (className) => $(className),
+    /**
+     * Find element by ControlType (e.g. Button, CheckBox)
+     *
+     * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.controltype?view=net-6.0
+     */
+    findElementByControlType: (controlType) => $(`<${controlType} />`),
+    /**
+     * Find element by a WinAppDriver compatible XPath Selector (e.g. '//Button[@AutomationId=\"MoreButton\"]')
+     */
+    findElementByXPath: (xpath) => $(xpath),
+    /**
+     * Resizes app window outer size according to provided width and height.
+     */
+    setWindowSize: (width, height) => browser.setWindowSize(width, height),
+    /**
+     * Change the position of the current focussed window.
+     */
+    setWindowPosition: (x, y) => browser.setWindowPosition(x, y),
+    /**
+     * Get the position of the current focussed window.
+     */
+    getWindowPosition: () => browser.getWindowPosition(),
+    /**
+     * Returns app window size.
+     */
+    getWindowSize: () => browser.getWindowSize(),
+    /**
+     * Switch focus to a particular window.
+     */
+    switchWindow: (titleToMatch) => browser.switchWindow(titleToMatch),
+    /**
+     * This wait command is your universal weapon if you want to wait on something. It expects a condition
+     * and waits until that condition is fulfilled with a truthy value.
+     */
+    waitUntil: (condition, options) => browser.waitUntil(condition, options),
+};
+//# sourceMappingURL=AutomationClient.js.map

package/lib-commonjs/AutomationClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutomationClient.js","sourceRoot":"","sources":["../src/AutomationClient.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAqCH;;GAEG;AACU,QAAA,GAAG,GAAG;IACjB;;OAEG;IACH,mBAAmB,EAAE,CAAC,EAAU,EAA8B,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAE5E;;;;OAIG;IACH,yBAAyB,EAAE,CAAC,EAAU,EAA8B,EAAE,CACpE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAEb;;;;OAIG;IACH,sBAAsB,EAAE,CAAC,SAAiB,EAA8B,EAAE,CACxE,CAAC,CAAC,SAAS,CAAC;IAEd;;;;OAIG;IACH,wBAAwB,EAAE,CAAC,WAAmB,EAA8B,EAAE,CAC5E,CAAC,CAAC,IAAI,WAAW,KAAK,CAAC;IAEzB;;OAEG;IACH,kBAAkB,EAAE,CAAC,KAAa,EAA8B,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAE3E;;OAEG;IACH,aAAa,EAAE,CAAC,KAAa,EAAE,MAAc,EAAE,EAAE,CAC/C,OAAO,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,iBAAiB,EAAE,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;IAE5E;;OAEG;IACH,iBAAiB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,iBAAiB,EAAE;IAEpD;;OAEG;IACH,aAAa,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE;IAE5C;;OAEG;IACH,YAAY,EAAE,CAAC,YAA6B,EAAE,EAAE,CAC9C,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC;IAEpC;;;OAGG;IACH,SAAS,EAAE,CACT,SAAiC,EACjC,OAAsC,EACtC,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC;CAC3C,CAAC","sourcesContent":["/**\n * Copyright (c) Microsoft Corporation.\n * Licensed under the MIT License.\n *\n * @format\n */\n\n/* global $:false, browser:false */\n\n/**\n * Projection of a WebDriver Element, with functions corresponding to supported\n * WinAppDriver APIs.\n *\n * See https://github.com/microsoft/WinAppDriver/blob/master/Docs/SupportedAPIs.md\n */\nexport type AutomationElement = Pick<\n  WebdriverIO.Element,\n  | 'addValue'\n  | 'clearValue'\n  | 'click'\n  | 'doubleClick'\n  | 'findElements'\n  | 'getAttribute'\n  | 'getLocation'\n  | 'getSize'\n  | 'getText'\n  | 'getValue'\n  | 'isDisplayed'\n  | 'isDisplayedInViewport'\n  | 'isEnabled'\n  | 'isEqual'\n  | 'isSelected'\n  | 'moveTo'\n  | 'saveScreenshot'\n  | 'sendKeys'\n  | 'selectByVisibleText'\n  | 'setValue'\n  | 'touchAction'\n  | 'waitForDisplayed'\n  | 'waitForExist'\n>;\n\n/**\n * A subset of WebDriver functionality that will work with Windows applications\n */\nexport const app = {\n  /**\n   * Find an element by testID property\n   */\n  findElementByTestID: (id: string): Promise<AutomationElement> => $(`~${id}`),\n\n  /**\n   * Find an element by Automation ID\n   *\n   * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.automationelement.automationelementinformation.automationid?view=net-6.0\n   */\n  findElementByAutomationID: (id: string): Promise<AutomationElement> =>\n    $(`~${id}`),\n\n  /**\n   * Finds an element by the name of its class name (e.g. ListViewItem)\n   *\n   * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.automationelement.automationelementinformation.classname?view=net-6.0\n   */\n  findElementByClassName: (className: string): Promise<AutomationElement> =>\n    $(className),\n\n  /**\n   * Find element by ControlType (e.g. Button, CheckBox)\n   *\n   * https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.controltype?view=net-6.0\n   */\n  findElementByControlType: (controlType: string): Promise<AutomationElement> =>\n    $(`<${controlType} />`),\n\n  /**\n   * Find element by a WinAppDriver compatible XPath Selector (e.g. '//Button[@AutomationId=\\\"MoreButton\\\"]')\n   */\n  findElementByXPath: (xpath: string): Promise<AutomationElement> => $(xpath),\n\n  /**\n   * Resizes app window outer size according to provided width and height.\n   */\n  setWindowSize: (width: number, height: number) =>\n    browser.setWindowSize(width, height),\n\n  /**\n   * Change the position of the current focussed window.\n   */\n  setWindowPosition: (x: number, y: number) => browser.setWindowPosition(x, y),\n\n  /**\n   * Get the position of the current focussed window.\n   */\n  getWindowPosition: () => browser.getWindowPosition(),\n\n  /**\n   * Returns app window size.\n   */\n  getWindowSize: () => browser.getWindowSize(),\n\n  /**\n   * Switch focus to a particular window.\n   */\n  switchWindow: (titleToMatch: string | RegExp) =>\n    browser.switchWindow(titleToMatch),\n\n  /**\n   * This wait command is your universal weapon if you want to wait on something. It expects a condition\n   * and waits until that condition is fulfilled with a truthy value.\n   */\n  waitUntil: (\n    condition: () => Promise<boolean>,\n    options?: WebdriverIO.WaitUntilOptions,\n  ) => browser.waitUntil(condition, options),\n};\n"]}

package/lib-commonjs/AutomationEnvironment.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * @format
+ */
+/// <reference types="webdriverio/webdriverio-core" />
+import NodeEnvironment from 'jest-environment-node';
+import { RemoteOptions } from 'webdriverio';
+import { JestEnvironmentConfig } from '@jest/environment';
+import type { EnvironmentContext } from '@jest/environment';
+export type EnvironmentOptions = {
+    /**
+     * The application to launch. Can be a path to an exe, or a package identity
+     * name (e.g. Microsoft.WindowsAlarms)
+     */
+    app?: string;
+    /**
+     * Instead of letting WinAppDriver launch and attach to the app directly,
+     * create a Root (Desktop) session and search for the app's window.
+     *
+     * Note: This is only really necessary to correctly attach to packaged
+     * WinAppSDK apps.
+     */
+    useRootSession?: boolean;
+    /**
+     * When using a Root (Desktop) session, still launch the test app during setup
+     * and close it during cleanup.
+     *
+     * Defaults to true when using `useRootSession` to mimic the expected test
+     * behavior, but can be disabled if you're trying to test an already
+     * running app instance.
+     */
+    rootLaunchApp?: boolean;
+    /**
+     * Arguments to be passed to your application when launched
+     */
+    appArguments?: string;
+    appWorkingDir?: string;
+    enableAutomationChannel?: boolean;
+    automationChannelPort?: number;
+    winAppDriverBin?: string;
+    breakOnStart?: boolean;
+    webdriverOptions?: RemoteOptions;
+};
+export default class AutomationEnvironment extends NodeEnvironment {
+    private readonly rootWebDriverOptions?;
+    private readonly webDriverOptions;
+    private readonly channelOptions;
+    private readonly winappdriverBin;
+    private readonly breakOnStart;
+    private readonly useRootSession;
+    private readonly rootLaunchApp;
+    private winAppDriverProcess;
+    private browser;
+    private automationClient;
+    constructor(config: JestEnvironmentConfig, context: EnvironmentContext);
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+}

package/lib-commonjs/AutomationEnvironment.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * @format
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chalk_1 = __importDefault(require("chalk"));
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("@react-native-windows/fs"));
+const path_1 = __importDefault(require("path"));
+const readline_sync_1 = __importDefault(require("readline-sync"));
+const jest_environment_node_1 = __importDefault(require("jest-environment-node"));
+const webdriverio = __importStar(require("webdriverio"));
+const automation_channel_1 = require("@react-native-windows/automation-channel");
+class AutomationEnvironment extends jest_environment_node_1.default {
+    constructor(config, context) {
+        var _a;
+        super(config, context);
+        const passedOptions = config.projectConfig.testEnvironmentOptions;
+        if (!passedOptions.app) {
+            throw new Error('"app" must be specified in testEnvironmentOptions');
+        }
+        this.winappdriverBin =
+            passedOptions.winAppDriverBin ||
+                path_1.default.join(process.env['PROGRAMFILES(X86)'], 'Windows Application Driver\\WinAppDriver.exe');
+        if (!fs_1.default.existsSync(this.winappdriverBin)) {
+            throw new Error(`Could not find WinAppDriver at searched location: "${this.winappdriverBin}"`);
+        }
+        const baseOptions = {
+            hostname: '127.0.0.1',
+            port: 4723,
+            // Level of logging verbosity: trace | debug | info | warn | error
+            logLevel: 'error',
+            // Default timeout for all waitFor* commands.
+            waitforTimeout: 30000,
+            // Default timeout in milliseconds for request
+            connectionRetryTimeout: 30000,
+            // Default request retries count
+            connectionRetryCount: 5,
+        };
+        this.useRootSession = !!passedOptions.useRootSession;
+        this.rootLaunchApp =
+            passedOptions.rootLaunchApp === undefined
+                ? this.useRootSession
+                : !!passedOptions.rootLaunchApp;
+        if (this.useRootSession) {
+            this.rootWebDriverOptions = Object.assign({}, baseOptions, {
+                capabilities: {
+                    app: 'Root',
+                    // @ts-ignore
+                    'ms:experimental-webdriver': true,
+                },
+            }, passedOptions.webdriverOptions);
+            this.webDriverOptions = Object.assign({}, baseOptions, {
+                capabilities: {
+                    // Save the name for now, we'll get the handle later
+                    appTopLevelWindow: passedOptions.app,
+                    // @ts-ignore
+                    'ms:experimental-webdriver': true,
+                },
+            }, passedOptions.webdriverOptions);
+        }
+        else {
+            this.webDriverOptions = Object.assign({}, baseOptions, {
+                capabilities: {
+                    app: resolveAppName(passedOptions.app),
+                    ...(passedOptions.appWorkingDir && {
+                        appWorkingDir: passedOptions.appWorkingDir,
+                    }),
+                    ...(passedOptions.appArguments && {
+                        appArguments: passedOptions.appArguments,
+                    }),
+                    // @ts-ignore
+                    'ms:experimental-webdriver': true,
+                },
+            }, passedOptions.webdriverOptions);
+        }
+        this.webDriverOptions.capabilities = Object.assign(this.webDriverOptions.capabilities, (_a = passedOptions.webdriverOptions) === null || _a === void 0 ? void 0 : _a.capabilities);
+        this.channelOptions = {
+            enable: passedOptions.enableAutomationChannel === true,
+            port: passedOptions.automationChannelPort || 8603,
+        };
+        this.breakOnStart = passedOptions.breakOnStart === true;
+    }
+    async setup() {
+        await super.setup();
+        this.winAppDriverProcess = await spawnWinAppDriver(this.winappdriverBin, this.webDriverOptions.port);
+        if (this.useRootSession) {
+            // Extract out the saved window name
+            const appName = this.webDriverOptions.capabilities
+                .appTopLevelWindow;
+            if (this.rootLaunchApp) {
+                const appPackageName = resolveAppName(appName);
+                (0, child_process_1.spawnSync)('cmd', [
+                    '/c',
+                    'start',
+                    `shell:AppsFolder\\${appPackageName}`,
+                ]);
+            }
+            // Set up the "Desktop" or Root session
+            const rootBrowser = await webdriverio.remote(this.rootWebDriverOptions);
+            // Get the list of windows
+            const allWindows = await rootBrowser.$$('//Window');
+            // Find our target window
+            let appWindow;
+            for (const window of allWindows) {
+                if ((await window.getAttribute('Name')) === appName) {
+                    appWindow = window;
+                    break;
+                }
+            }
+            if (!appWindow) {
+                throw new Error(`Unable to find window with Name === '${appName}'.`);
+            }
+            // Swap the the window handle for WinAppDriver
+            const appWindowHandle = parseInt(await appWindow.getAttribute('NativeWindowHandle'), 10);
+            this.webDriverOptions.capabilities.appTopLevelWindow =
+                '0x' + appWindowHandle.toString(16);
+            await rootBrowser.deleteSession();
+        }
+        this.browser = await webdriverio.remote(this.webDriverOptions);
+        if (this.breakOnStart) {
+            readline_sync_1.default.question(chalk_1.default.bold.yellow('Breaking before tests start\n') +
+                'Press Enter to resume...');
+        }
+        if (this.channelOptions.enable) {
+            this.automationClient = await (0, automation_channel_1.waitForConnection)({
+                port: this.channelOptions.port,
+            });
+            this.global.automationClient = this.automationClient;
+        }
+        this.global.remote = webdriverio.remote;
+        this.global.browser = this.browser;
+        this.global.$ = this.browser.$.bind(this.browser);
+        this.global.$$ = this.browser.$$.bind(this.browser);
+    }
+    async teardown() {
+        var _a;
+        if (this.automationClient) {
+            this.automationClient.close();
+        }
+        if (this.browser) {
+            if (this.rootLaunchApp) {
+                // We started the app, so let's close it too
+                await this.browser.closeWindow();
+            }
+            await this.browser.deleteSession();
+        }
+        (_a = this.winAppDriverProcess) === null || _a === void 0 ? void 0 : _a.kill('SIGINT');
+        await super.teardown();
+    }
+}
+exports.default = AutomationEnvironment;
+/**
+ * Starts a WinAppdriver process and resolves a promise with the process once
+ * it is ready to accept commands
+ *
+ * Inspired-by/stolen from https://github.com/licanhua/wdio-winappdriver-service
+ */
+async function spawnWinAppDriver(winappdriverBin, port) {
+    if (!fs_1.default.existsSync(winappdriverBin)) {
+        throw new Error(`Could not locate WinAppDriver binary at "${winappdriverBin}"`);
+    }
+    return new Promise((resolve, reject) => {
+        const process = (0, child_process_1.spawn)(winappdriverBin, [port.toString()], { stdio: 'pipe' });
+        process.stdout.on('data', data => {
+            const s = data.toString('utf16le');
+            if (s.includes('Press ENTER to exit.')) {
+                resolve(process);
+            }
+            else if (s.includes('Failed to initialize')) {
+                reject(new Error('Failed to start WinAppDriver: ' + s));
+            }
+        });
+        process.stderr.once('data', err => {
+            console.warn(err);
+        });
+        process.once('exit', exitCode => {
+            reject(new Error(`WinAppDriver CLI exited before timeout (exit code: ${exitCode})`));
+        });
+    });
+}
+/**
+ * Convert a package identity or path to exe to the form expected by a WinAppDriver capability
+ */
+function resolveAppName(appName) {
+    if (appName.endsWith('.exe')) {
+        return appName;
+    }
+    try {
+        const packageFamilyName = (0, child_process_1.spawnSync)('powershell', [
+            `(Get-AppxPackage -Name ${appName}).PackageFamilyName`,
+        ])
+            .stdout.toString()
+            .trim();
+        if (packageFamilyName.length === 0) {
+            // Rethrown below
+            throw new Error();
+        }
+        return `${packageFamilyName}!App`;
+    }
+    catch (_a) {
+        throw new Error(`Could not locate a package with identity "${appName}"`);
+    }
+}
+//# sourceMappingURL=AutomationEnvironment.js.map

package/lib-commonjs/AutomationEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutomationEnvironment.js","sourceRoot":"","sources":["../src/AutomationEnvironment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Copyright (c) Microsoft Corporation.\n * Licensed under the MIT License.\n *\n * @format\n */\n\nimport chalk from 'chalk';\nimport {spawnSync, spawn, ChildProcess} from 'child_process';\nimport fs from '@react-native-windows/fs';\nimport path from 'path';\nimport readlineSync from 'readline-sync';\n\nimport NodeEnvironment from 'jest-environment-node';\nimport * as webdriverio from 'webdriverio';\nimport {BrowserObject, RemoteOptions} from 'webdriverio';\nimport {JestEnvironmentConfig} from '@jest/environment';\nimport type {EnvironmentContext} from '@jest/environment';\nimport {\n  waitForConnection,\n  AutomationClient,\n} from '@react-native-windows/automation-channel';\n\nexport type EnvironmentOptions = {\n  /**\n   * The application to launch. Can be a path to an exe, or a package identity\n   * name (e.g. Microsoft.WindowsAlarms)\n   */\n  app?: string;\n\n  /**\n   * Instead of letting WinAppDriver launch and attach to the app directly,\n   * create a Root (Desktop) session and search for the app's window.\n   *\n   * Note: This is only really necessary to correctly attach to packaged\n   * WinAppSDK apps.\n   */\n  useRootSession?: boolean;\n\n  /**\n   * When using a Root (Desktop) session, still launch the test app during setup\n   * and close it during cleanup.\n   *\n   * Defaults to true when using `useRootSession` to mimic the expected test\n   * behavior, but can be disabled if you're trying to test an already\n   * running app instance.\n   */\n  rootLaunchApp?: boolean;\n\n  /**\n   * Arguments to be passed to your application when launched\n   */\n  appArguments?: string;\n\n  appWorkingDir?: string;\n\n  enableAutomationChannel?: boolean;\n  automationChannelPort?: number;\n  winAppDriverBin?: string;\n  breakOnStart?: boolean;\n  webdriverOptions?: RemoteOptions;\n};\n\ntype AutomationChannelOptions = {\n  enable: boolean;\n  port: number;\n};\n\nexport default class AutomationEnvironment extends NodeEnvironment {\n  private readonly rootWebDriverOptions?: RemoteOptions;\n  private readonly webDriverOptions: RemoteOptions;\n  private readonly channelOptions: AutomationChannelOptions;\n  private readonly winappdriverBin: string;\n  private readonly breakOnStart: boolean;\n  private readonly useRootSession: boolean;\n  private readonly rootLaunchApp: boolean;\n  private winAppDriverProcess: ChildProcess | undefined;\n  private browser: BrowserObject | undefined;\n  private automationClient: AutomationClient | undefined;\n\n  constructor(config: JestEnvironmentConfig, context: EnvironmentContext) {\n    super(config, context);\n    const passedOptions: EnvironmentOptions =\n      config.projectConfig.testEnvironmentOptions;\n\n    if (!passedOptions.app) {\n      throw new Error('\"app\" must be specified in testEnvironmentOptions');\n    }\n\n    this.winappdriverBin =\n      passedOptions.winAppDriverBin ||\n      path.join(\n        process.env['PROGRAMFILES(X86)']!,\n        'Windows Application Driver\\\\WinAppDriver.exe',\n      );\n\n    if (!fs.existsSync(this.winappdriverBin)) {\n      throw new Error(\n        `Could not find WinAppDriver at searched location: \"${this.winappdriverBin}\"`,\n      );\n    }\n\n    const baseOptions: RemoteOptions = {\n      hostname: '127.0.0.1',\n      port: 4723,\n\n      // Level of logging verbosity: trace | debug | info | warn | error\n      logLevel: 'error',\n\n      // Default timeout for all waitFor* commands.\n      waitforTimeout: 30000,\n\n      // Default timeout in milliseconds for request\n      connectionRetryTimeout: 30000,\n\n      // Default request retries count\n      connectionRetryCount: 5,\n    };\n\n    this.useRootSession = !!passedOptions.useRootSession;\n    this.rootLaunchApp =\n      passedOptions.rootLaunchApp === undefined\n        ? this.useRootSession\n        : !!passedOptions.rootLaunchApp;\n\n    if (this.useRootSession) {\n      this.rootWebDriverOptions = Object.assign(\n        {},\n        baseOptions,\n        {\n          capabilities: {\n            app: 'Root',\n            // @ts-ignore\n            'ms:experimental-webdriver': true,\n          },\n        },\n        passedOptions.webdriverOptions,\n      );\n\n      this.webDriverOptions = Object.assign(\n        {},\n        baseOptions,\n        {\n          capabilities: {\n            // Save the name for now, we'll get the handle later\n            appTopLevelWindow: passedOptions.app,\n            // @ts-ignore\n            'ms:experimental-webdriver': true,\n          },\n        },\n        passedOptions.webdriverOptions,\n      );\n    } else {\n      this.webDriverOptions = Object.assign(\n        {},\n        baseOptions,\n        {\n          capabilities: {\n            app: resolveAppName(passedOptions.app),\n            ...(passedOptions.appWorkingDir && {\n              appWorkingDir: passedOptions.appWorkingDir,\n            }),\n            ...(passedOptions.appArguments && {\n              appArguments: passedOptions.appArguments,\n            }),\n\n            // @ts-ignore\n            'ms:experimental-webdriver': true,\n          },\n        },\n        passedOptions.webdriverOptions,\n      );\n    }\n\n    this.webDriverOptions.capabilities = Object.assign(\n      this.webDriverOptions.capabilities!,\n      passedOptions.webdriverOptions?.capabilities,\n    );\n\n    this.channelOptions = {\n      enable: passedOptions.enableAutomationChannel === true,\n      port: passedOptions.automationChannelPort || 8603,\n    };\n\n    this.breakOnStart = passedOptions.breakOnStart === true;\n  }\n\n  async setup() {\n    await super.setup();\n    this.winAppDriverProcess = await spawnWinAppDriver(\n      this.winappdriverBin,\n      this.webDriverOptions.port!,\n    );\n\n    if (this.useRootSession) {\n      // Extract out the saved window name\n      const appName = (this.webDriverOptions.capabilities! as any)\n        .appTopLevelWindow;\n\n      if (this.rootLaunchApp) {\n        const appPackageName = resolveAppName(appName);\n        spawnSync('cmd', [\n          '/c',\n          'start',\n          `shell:AppsFolder\\\\${appPackageName}`,\n        ]);\n      }\n\n      // Set up the \"Desktop\" or Root session\n      const rootBrowser = await webdriverio.remote(this.rootWebDriverOptions);\n\n      // Get the list of windows\n      const allWindows = await rootBrowser.$$('//Window');\n\n      // Find our target window\n      let appWindow: webdriverio.Element | undefined;\n      for (const window of allWindows) {\n        if ((await window.getAttribute('Name')) === appName) {\n          appWindow = window;\n          break;\n        }\n      }\n\n      if (!appWindow) {\n        throw new Error(`Unable to find window with Name === '${appName}'.`);\n      }\n\n      // Swap the the window handle for WinAppDriver\n      const appWindowHandle = parseInt(\n        await appWindow!.getAttribute('NativeWindowHandle'),\n        10,\n      );\n\n      (this.webDriverOptions.capabilities as any).appTopLevelWindow =\n        '0x' + appWindowHandle.toString(16);\n\n      await rootBrowser.deleteSession();\n    }\n\n    this.browser = await webdriverio.remote(this.webDriverOptions);\n\n    if (this.breakOnStart) {\n      readlineSync.question(\n        chalk.bold.yellow('Breaking before tests start\\n') +\n          'Press Enter to resume...',\n      );\n    }\n\n    if (this.channelOptions.enable) {\n      this.automationClient = await waitForConnection({\n        port: this.channelOptions.port,\n      });\n      this.global.automationClient = this.automationClient;\n    }\n\n    this.global.remote = webdriverio.remote;\n    this.global.browser = this.browser;\n    this.global.$ = this.browser.$.bind(this.browser);\n    this.global.$$ = this.browser.$$.bind(this.browser);\n  }\n\n  async teardown() {\n    if (this.automationClient) {\n      this.automationClient.close();\n    }\n\n    if (this.browser) {\n      if (this.rootLaunchApp) {\n        // We started the app, so let's close it too\n        await this.browser.closeWindow();\n      }\n      await this.browser.deleteSession();\n    }\n    this.winAppDriverProcess?.kill('SIGINT');\n    await super.teardown();\n  }\n}\n\n/**\n * Starts a WinAppdriver process and resolves a promise with the process once\n * it is ready to accept commands\n *\n * Inspired-by/stolen from https://github.com/licanhua/wdio-winappdriver-service\n */\nasync function spawnWinAppDriver(\n  winappdriverBin: string,\n  port: number,\n): Promise<ChildProcess> {\n  if (!fs.existsSync(winappdriverBin)) {\n    throw new Error(\n      `Could not locate WinAppDriver binary at \"${winappdriverBin}\"`,\n    );\n  }\n\n  return new Promise((resolve, reject) => {\n    const process = spawn(winappdriverBin, [port.toString()], {stdio: 'pipe'});\n\n    process.stdout.on('data', data => {\n      const s = data.toString('utf16le');\n      if (s.includes('Press ENTER to exit.')) {\n        resolve(process);\n      } else if (s.includes('Failed to initialize')) {\n        reject(new Error('Failed to start WinAppDriver: ' + s));\n      }\n    });\n\n    process.stderr.once('data', err => {\n      console.warn(err);\n    });\n\n    process.once('exit', exitCode => {\n      reject(\n        new Error(\n          `WinAppDriver CLI exited before timeout (exit code: ${exitCode})`,\n        ),\n      );\n    });\n  });\n}\n\n/**\n * Convert a package identity or path to exe to the form expected by a WinAppDriver capability\n */\nfunction resolveAppName(appName: string): string {\n  if (appName.endsWith('.exe')) {\n    return appName;\n  }\n\n  try {\n    const packageFamilyName = spawnSync('powershell', [\n      `(Get-AppxPackage -Name ${appName}).PackageFamilyName`,\n    ])\n      .stdout.toString()\n      .trim();\n\n    if (packageFamilyName.length === 0) {\n      // Rethrown below\n      throw new Error();\n    }\n\n    return `${packageFamilyName}!App`;\n  } catch {\n    throw new Error(`Could not locate a package with identity \"${appName}\"`);\n  }\n}\n"]}

package/lib-commonjs/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * @format
+ */
+import AutomationEnvironment from './AutomationEnvironment';
+import { app, AutomationElement } from './AutomationClient';
+export { app };
+export type { AutomationElement };
+export default AutomationEnvironment;

package/lib-commonjs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * @format
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.app = void 0;
+const AutomationEnvironment_1 = __importDefault(require("./AutomationEnvironment"));
+const AutomationClient_1 = require("./AutomationClient");
+Object.defineProperty(exports, "app", { enumerable: true, get: function () { return AutomationClient_1.app; } });
+exports.default = AutomationEnvironment_1.default;
+//# sourceMappingURL=index.js.map

package/lib-commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;AAEH,oFAA4D;AAC5D,yDAA0D;AAElD,oFAFA,sBAAG,OAEA;AAEX,kBAAe,+BAAqB,CAAC","sourcesContent":["/**\n * Copyright (c) Microsoft Corporation.\n * Licensed under the MIT License.\n *\n * @format\n */\n\nimport AutomationEnvironment from './AutomationEnvironment';\nimport {app, AutomationElement} from './AutomationClient';\n\nexport {app};\nexport type {AutomationElement}\nexport default AutomationEnvironment;\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@react-native-windows/automation",
+  "version": "0.0.0-canary.1016",
+  "description": "UI Automation Suite for React Native Windows Applications",
+  "main": "lib-commonjs/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/react-native-windows",
+    "directory": "packages/@react-native-windows/automation"
+  },
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "rnw-scripts build",
+    "clean": "rnw-scripts clean",
+    "lint": "rnw-scripts lint",
+    "lint:fix": "rnw-scripts lint:fix",
+    "watch": "rnw-scripts watch"
+  },
+  "dependencies": {
+    "@react-native-windows/automation-channel": "0.0.0-canary.1016",
+    "@react-native-windows/fs": "^0.0.0-canary.70",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
+    "chalk": "^4.1.2",
+    "readline-sync": "1.4.10",
+    "webdriverio": "^6.9.0"
+  },
+  "devDependencies": {
+    "@jest/create-cache-key-function": "^29.2.1",
+    "@jest/environment": "^29.3.0",
+    "@jest/types": "^29.2.1",
+    "@rnw-scripts/eslint-config": "1.2.38",
+    "@rnw-scripts/just-task": "2.3.58",
+    "@rnw-scripts/ts-config": "2.0.6",
+    "@types/jest": "^29.2.2",
+    "@types/node": "^22.14.0",
+    "@types/readline-sync": "^1.4.4",
+    "eslint": "^8.19.0",
+    "prettier": "2.8.8",
+    "typescript": "5.0.4"
+  },
+  "peerDependencies": {
+    "jest": ">=29.0.3",
+    "jest-environment-node": ">=29.2.2"
+  },
+  "files": [
+    "lib-commonjs",
+    "README.md"
+  ],
+  "beachball": {
+    "defaultNpmTag": "canary",
+    "disallowedChangeTypes": [
+      "major",
+      "minor",
+      "patch",
+      "premajor",
+      "preminor",
+      "prepatch"
+    ]
+  },
+  "promoteRelease": true,
+  "engines": {
+    "node": ">= 22"
+  }
+}