Detox

@nativescript/detox

Easily add Detox end-to-end testing to your NativeScript apps!

apdbINz mWBBF26

iOS Demo

Android Demo

Table of Contents

  1. Installation

  2. Global Setup

  3. Project Setup

  4. Usage

  5. Running Tests

  6. Troubleshooting

Installation

npm install @nativescript/detox

Global Setup

The full setup requirements can be found here, but the minimal setup steps are as follows:

Install Detox command line tools (detox-cli)

npm install -g detox-cli

Install applesimutils (iOS)

brew tap wix/brew
brew install applesimutils

Project Setup

Install the Detox package to your NativeScript project

npm install detox --save-dev

Install Jest

npm install jest jest-cli jest-circus --save-dev --no-package-lock

Initialize Detox

detox init -r jest

If things go well, you should have this setup:

  • An e2e/ folder in your project root

  • An e2e/config.json file; example

  • An e2e/environment.js file; example

  • An e2e/firstTest.e2e.ts file with content similar to this.

There should also be a file called .detoxrc.json in your project root.

Configure Detox

Detox must be configued to know the location of the iOS and Android app binary as well as what emulator/simulator to use.

Open .detoxrc.json and make the following modifications under apps and devices.

  • binaryPath: Specify the location of the app binary (probably something like below).

    • iOS: platforms/ios/build/Debug-iphonesimulator/[APP_NAME].app

    • Android: platforms/android/app/build/outputs/apk/debug/app-debug.apk

  • build: Specify the build command for iOS and Android.

    • iOS: ns build ios --env.e2e

    • Android: ns build android --detox --env.e2e

  • devices:

    • iOS: "type": "iPhone 11"

    • Android: "avdName": "Pixel_4_API_30" (use emulator -list-avds to list Android emulators)

Here is a full example of a Detox configuration:

{
  "testRunner": "jest",
  "runnerConfig": "e2e/config.json",
  "skipLegacyWorkersInjection": true,
  "apps": {
    "ios": {
      "type": "ios.app",
      "binaryPath": "platforms/ios/build/Debug-iphonesimulator/[APP_NAME].app",
      "build": "ns build ios"
    },
    "android": {
      "type": "android.apk",
      "binaryPath": "platforms/android/app/build/outputs/apk/debug/app-debug.apk",
      "build": "ns build android --detox"
    }
  },
  "devices": {
    "simulator": {
      "type": "ios.simulator",
      "device": {
        "type": "iPhone 11 Pro"
      }
    },
    "emulator": {
      "type": "android.emulator",
      "device": {
        "avdName": "Pixel_4_API_30"
      }
    }
  },
  "configurations": {
    "ios": {
      "device": "simulator",
      "app": "ios"
    },
    "android": {
      "device": "emulator",
      "app": "android"
    }
  }
}

A default NativeScript Android project uses 17 as the minimum SDK, but Detox requires >=21. Remove or modify the minSdkVersion in your App_Resources/Android/app.gradle.

Allow Local Networking (iOS Only)

Depending on your setup, iOS may not be able to communicate with Detox off the bat. In that case, you need to add the following to your Info.plist file to allow for local networking requests.

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

Usage

Read through this tutorial written by Detox about writing your first test. Nearly all the things specified towards React Native apps also apply to NativeScript apps.

Get started by opening the default test scenario in e2e/firstTest.e2e.js.

describe('Example', () => {
  beforeEach(async () => {
    await device.reloadReactNative()
  })

  it('should have welcome screen', async () => {
    await expect(element(by.text('Sergio'))).toBeVisible()
  })
})

This example creates a testing scenario called Example and has a single test inside it called should have welcome screen.

Matchers

Detox uses matchers to find elements in your UI to interact with.

You can use NativeScript’s testID property to find your UI elements using Detox’s by.id() matcher.

Example:

<Button text="Tap Me!" testID="testButton" />
await element(by.id('testButton')).tap()

Actions

Once you find your UI element you can use an action on it such as tap() to simulate user interaction.

You should now be able to write tests to simulate user behavior and test for expected results.

Running Tests

Building

Build your app for testing using the following command:

detox build -c ios|android

Testing

Run your tests with the following command:

detox test -c ios|android

If using an Android emulator, Detox will disable animations when the tests are run. Animations will remain disabled after they are finished. This can be very annoying when you are actively developing. You can re-enable animations by running this helper script from your project’s directory ./node_modules/.bin/enable-animations.

To make this even easier, I would suggest adding these scripts to your package.json.

{
  "scripts": {
    "e2e:android:build": "detox build -c android",
    "e2e:android:test": "detox test -c android && ./node_modules/.bin/enable-animations",
    "e2e:ios:build": "detox build -c ios",
    "e2e:ios:test": "detox test -c ios"
  }
}

Now, to build and run tests, you would run:

Android:

npm run e2e:android:build
npm run e2e:android:test

iOS:

npm run e2e:ios:build
npm run e2e:ios:test

Troubleshooting

Detox requires a minimum SDK version of 21, so if you get the following error, change the minSdkVersion to 21 in App_Resources/Android/app.gradle.

Execution failed for task ':app:processDebugAndroidTestManifest'.
Manifest merger failed : uses-sdk:minSdkVersion 17 cannot be smaller than version 18 declared in library [com.wix:detox:17.6.1] /Users/user/.gradle/caches/transforms-2/files-2.1/91a3acd87d710d1913b266ac114d7001/jetified-detox-17.6.1/AndroidManifest.xml as the library might be using APIs not available in 17
        Suggestion: use a compatible library with a minSdk of at most 17,
                or increase this project's minSdk version to at least 21,
                or use tools:overrideLibrary="com.wix.detox" to force usage (may lead to runtime failures)

Command ./gradlew failed with exit code 1

Elements can not be found during test

In NativeScript <8.2, the testID property was not available. Instead, you were supposed to use the automationText property.

Add Resource ID (Android Only) In order to use the automationText property in NativeScript it must be enabled by adding a custom resource ID. Create a file called ids.xml in App_Resources/Android/src/main/res/values/ and add the following:

<?xml version="1.0" encoding="utf-8" ?>
<resources>
  <item type="id" name="nativescript_accessibility_id" />
</resources>

License

Apache License Version 2.0