Detox

@nativescript/detox #

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

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 to have this set up:

• An e2e/ folder in your project root
• An e2e/jest.config.js file
• An e2e/starter.test.js file; example

There should also be a Detox configuration file called .detoxrc.js in your project root.

Configure Detox #

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

Open .detoxrc.js 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 14 Pro Max"
  • Android: "avdName": "Pixel_4_API_30" (use emulator -list-avds to list Android emulators)

Here is a full example of a Detox configuration:

/** @type {Detox.DetoxConfig} */
module.exports = {
  testRunner: {
    args: {
      $0: 'jest',
      config: 'e2e/jest.config.js'
    },
    jest: {
      setupTimeout: 120000
    }
  },
  apps: {
    'ios.debug': {
      type: 'ios.app',
      binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/YOUR_APP.app',
      build:
        'xcodebuild -workspace platforms/ios/YOUR_APP.xcworkspace -scheme YOUR_APP -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build'
    },
    'ios.release': {
      type: 'ios.app',
      binaryPath: 'ios/build/Build/Products/Release-iphonesimulator/YOUR_APP.app',
      build:
        'xcodebuild -workspace platforms/ios/YOUR_APP.xcworkspace -scheme YOUR_APP -configuration Release -sdk iphonesimulator -derivedDataPath ios/build'
    },
    'android.debug': {
      type: 'android.apk',
      binaryPath: 'platforms/android/app/build/outputs/apk/debug/app-debug.apk',
      build:
        'cd platforms/android ; ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug ; cd -',
      reversePorts: [8081]
    },
    'android.release': {
      type: 'android.apk',
      binaryPath: 'platforms/android/app/build/outputs/apk/release/app-release.apk',
      build:
        'cd platforms/android ; ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release ; cd -'
    }
  },
  devices: {
    simulator: {
      type: 'ios.simulator',
      device: {
        type: 'iPhone 14 Pro Max'
      }
    },
    attached: {
      type: 'android.attached',
      device: {
        adbName: '.*'
      }
    },
    emulator: {
      type: 'android.emulator',
      device: {
        avdName: 'Pixel_3a_API_30_x86'
      }
    }
  },
  configurations: {
    'ios.sim.debug': {
      device: 'simulator',
      app: 'ios.debug'
    },
    'ios.sim.release': {
      device: 'simulator',
      app: 'ios.release'
    },
    'android.att.debug': {
      device: 'attached',
      app: 'android.debug'
    },
    'android.att.release': {
      device: 'attached',
      app: 'android.release'
    },
    'android.emu.debug': {
      device: 'emulator',
      app: 'android.debug'
    },
    'android.emu.release': {
      device: 'emulator',
      app: 'android.release'
    }
  }
}

Allow Local Networking (iOS Only) #

Dependending 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 of 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 of it called should have welcome screen.

Matchers #

Detox uses [matchers]https://github.com/wix/Detox/blob/master/docs/api/matchers.md) 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 with the value for the -c flag being any of the properties of configuration object' in .detoxrc.js:

detox build -c ios.sim.debug|android.emu.debug

Testing #

Run your tests with the folling command:

detox test -c ios.sim.debug|android.emu.debug

NOTE: If using an Android emulator, Detox will disable animations when the tests are ran. 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": "android.att.debug",
    "e2e:android:build:debug": "ns clean; ns build android; detox build -c android.emu.debug",
    "e2e:android:debug:test": "detox test -c android.emu.debug && ./node_modules/.bin/enable-animations",
    "e2e:ios:build:debug": "detox build -c ios.sim.debug --env.e2e",
    "e2e:ios:test": "detox test -c ios.sim.debug"
  }
}

Now to build and run tests you would run:

Android:

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

iOS:

npm run e2e:ios:build:debug
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