Skip to main content
Version: 20.x

How to Debug

Detox Tests​

If you need to walk through your Detox tests step by step, add a debugger statement inside your test to mark a starting point, e.g.:

e2e/starter.test.js
 describe('Example', () => {
   beforeAll(async () => {
     await device.launchApp();
+    debugger;
   });

Now run Detox with that specific test and --inspect-brk flag, e.g.:

detox test --inspect-brk -c android.emu.debug e2e/starter.test.js

Assuming you're using Jest, you'll see something like:

DETOX_CONFIGURATION="android.emu.debug" node --inspect-brk ./node_modules/.bin/jest --config e2e/jest.config.js --runInBand e2e/starter.test.js
Debugger listening on ws://127.0.0.1:9229/3dedd03b-8896-4ab8-a0a8-1b647abb9c98
For help, see: https://nodejs.org/en/docs/inspector
info

To learn more about debugging with --inspect-brk, refer to Debugging — Getting Started on the official Node.js website. This tutorial suggests using Google Chrome for debugging, but you can also use an IDE to connect to the debugger.

Open Google Chrome and go to chrome://inspect tab, where you'll see ./node_modules/.bin/jest as a remote target waiting until you click inspect to attach to it.

Happy debugging!

JavaScript application code​

Use debug configurations of your app that rely on React Native Packager running on port 8081 (or another):

  • ios.sim.debug
  • android.emu.debug

For the rest of details, please refer to React Native – Debugging.

Native application code​

Setting Detox up as a compiling dependency​

Note

This step is optional. It is intended for investigating weird crashes or when contributing to Detox itself.

  1. Go to node_modules/detox and extract Detox-ios-src.tbz

    extracted detox-ios-src directory

  2. Drag Detox-ios-src/Detox.xcodeproj into your Xcode project

    Detox inside Xcode project

  3. Go to your project settings → General and add Detox.framework to Frameworks, Libraries, and Embedded Content (make sure Embed & Sign is selected under Embed)

    embed Detox

caution

Apps should not be submitted to the App Store with the Detox framework linked. Follow this guide only to debug Detox issues in your project. Once finished, make sure to remove Detox.framework from your project.

Add a "manual" configuration to your Detox config​

{
  "devices": {
    "simulator": {
      "type": "ios.simulator",
      "device": {
        "type": "<e.g., iPhone 12 Pro>"
      }
    }
  },
  "apps": {
    "ios.debug": {
      "type": "ios.app",
      "binaryPath": "<path to your app binary built before>"
    }
  },
  "configurations": {
    "ios.manual": {
      "device": "simulator",
      "app": "ios.debug",
      "behavior": {
        "launchApp": "manual"
      }
    }
  }
}

While the behavior section is a mandatory thing to include, there are a few more optional parameters to disable various side effects and make life easier when debugging:

 {
   …
   "configurations": {
     "<your configuration>": {
       …
       "behavior": {
         "launchApp": "manual"
       },
+      "session": {
+        "autoStart": true,
+        "debugSynchronization": 0,
+        "server": "ws://localhost:8099",
+        "sessionId": "test"
+      },
+      "testRunner": {
+        "args": {
+          "testTimeout": 999999
+        }
+      }
+      "artifacts": false
     },
   }
 }

  • Using a preconfigured session with an autostarting server removes the legwork of copying and pasting values to the instrumentation runner launch arguments dialog every time before any launch from the IDE. Otherwise, by default when the session object omitted, server and sessionId are randomly generated for every new test session.

  • The debugSynchronization: 0 override matters only if you have a global session config with debugSynchronization set to a positive integer value. Otherwise, it is not needed. The point is to disable regular app polling requests during debugging, since that only can hinder the debugging.

  • If you are using Jest as a test runner, you might want to prolong the test timeout via forwarding --testTimeout 999999 to it.

  • Setting artifacts: false override also matters only if you have a global artifacts config. The motivation is to disable irrelevant taxing activities on the device such as capturing logs screenshots, videos and so on. If your investigation addresses a specific artifact plugin glitch on the native side, then just disable all the non-relevant plugins. See Configuration > Artifacts document for the reference.

Run a specific test​

Usually, you would want to focus on a specific test suite to save time, e.g.:

detox test -c ios.manual e2e/someSuite.test.js
caution

Don't use multiple workers, e.g. -w, --maxWorkers for Jest, if you set session.sessionId to a constant value.

Afterwards, you should see your test suite starting as usual until it reaches the app launch, where Detox stops instead and prompts you to launch the app from the IDE:

18:26:07.024 detox[45214] i Waiting for you to manually launch your app in Xcode.
Make sure to pass the launch arguments listed below:
  -detoxServer ws://localhost:8099
  -detoxSessionId com.wix.detox-example

Press any key to continue...

You’ll need to run your app with the said arguments from Xcode:

Xcode - Edit Schema - Arguments tab

Before you launch the app, make sure to put breakpoints at the points of interest, e.g.:

put a breakpoint in the native code

Launch the app with the debugger attached:

launching the app

The moment you see the app is idle, go back to the Terminal where Detox is running and press any key. If you wish to terminate the process for some reason, use Ctrl+C. In a couple of seconds you are expected to see a confirmation from Detox, e.g.:

Found the app (com.wix.detox-example) with process ID = 16854. Proceeding...

Now the entire test will run as usual until it sends an action to the app, which gets trapped in your breakpoint.

Happy debugging!

Troubleshooting​

There are no known issues at the moment. Check out Android tab if you need some.