react-native-windows/packages/@react-native-windows/automation

@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 or later to manipulate and inspect your application via Windows UI Automation. 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:

{
  "devDependencies": {
    "@react-native-windows/automation": "<version>",
  }
}

Next, edit your Jest configuration to use @react-native-windows/automation as your test environment. Add the following to your jest.config.js or jest.config.ts file:

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:

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.

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 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.

import {dumpVisualTree} from '@react-native-windows/automation-commands';

test('Widget', async () => {
  const dump = await dumpVisualTree('widget-test-id');
  expect(dump).toMatchSnapshot();
});