Session

Note

It is not recommended to customize this section unless you are debugging native code or contributing to the native iOS/Android code of Detox.

The session section tells Detox how to set up its web socket server and client. They are used to forward the JSON-serialized expectations and element interactions to the native implementation of Detox side-loaded with the app.

Location

You can define the session config section in two ways: globally and locally (per a configuration):

.detoxrc.js

/** @type {Detox.DetoxConfig} */
module.exports = {
  session: {
    /* global section */
  },
  devices: { /* … */ },
  apps: { /* … */ },
  configurations: {
    'ios.sim.debug': {
      device: 'iphone',
      app: 'ios.debug',
      session: {
        /* local (per-configuration) section */
      },
    },
  },
};

Properties

There is one important thing to note when you’ll be defining a session config, e.g.:

session.server [string]

Default: ws://localhost:{randomPort}.

{
  "session": {
    "server": "ws://localhost:8099"
  }
}

When you define a URL for server, it automatically sets session.autoStart to false (mainly due to backward compatibility reasons), so make sure to override it back if you didn’t intend that.

session.sessionId [string]

Default: a random UUID, e.g. 7731871e-2f07-46bb-acbc-cb0eb6a0ace7.

Since the Detox server is a single entity, but there can be multiple test workers running multiple devices and apps, it needs to understand which connection belongs to which app.

Detox forwards sessionId to the app as a launch argument, so the app immediately knows where to connect to.

caution

Defining an explicit sessionId means you cannot use multiple workers, since the specified session will become busy for any test worker next to the first one to occupy it.

{
  "session": {
    "server": "ws://localhost:8099",
    "sessionId": "YourProjectSessionId"
  }
}

session.autoStart [boolean]

Default: true for undefined session.server, and false for defined.

Controls whether Detox web socket server will be starting automatically. If false, it is assumed that you will be running it independently via detox run-server CLI command.

   "session": {
+    "autoStart": true,
     "server": "ws://localhost:8099",
     "sessionId": "YourProjectSessionId"

session.debugSynchronization [number]

Default: 10000.

Tells Detox how long (in milliseconds) to wait for the app to become idle until it starts querying it for more details.

{
  "session": {
    "debugSynchronization": 20000
  }
}

Detox will be printing the list of busy idling resources every time an action takes more than the specified period, e.g.:

15:13:07.309 detox[17005] i The app is busy with the following tasks:
• There are 10 work items pending on the dispatch queue: "Main Queue (<OS_dispatch_queue_main: com.apple.main-thread>)".
• UI elements are busy:
  - Layers pending animations: 96.
  - Layers needs layout: 173.
  - View needs layout: 74.
  - View needs display: 98.
  - Layers needs display: 90.
• Run loop "Main Run Loop" is awake.

To disable this behavior (i.e. querying the app periodically), set the value to 0.

Seeing logs like these usually indicates certain issues in your application, as mentioned in the Troubleshooting Guide.

For the most detailed information, refer to the DetoxSync (iOS) Status Documentation.