Detox/docs/config/session.mdx

import Location from './partials/_location.mdx';

# Session

:::info Note

It is not recommended to customize this section unless [you are debugging native code](../introduction/debugging.mdx)
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

<Location sectionName="session" />

## 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}`.

```json
{
  "session": {
// highlight-next-line
    "server": "ws://localhost:8099"
  }
}
```

When you define a URL for `server`, it automatically sets [`session.autoStart`](#sessionautostart-boolean) 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.

```json
{
  "session": {
    "server": "ws://localhost:8099",
// highlight-next-line
    "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/run-server.md) CLI command.

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

### `session.debugSynchronization` \[number]

**Enabled by default**, with the value of `10_000`ms.

Tells Detox how long (in milliseconds) to wait for the app to become idle until it starts querying it for more details in order to print out automated-synchronization debugging logs.

```json
{
  "session": {
    "debugSynchronization": 5000
  }
}
```

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

```plain text
09:41:00.941 detox[1337] 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.
```

<sup>(These are logs generated by Detox for iOS; Detox for Android generates different yet equivalent ones)</sup>

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 explained in the [Troubleshooting Guide](../troubleshooting/synchronization.md).

For extended, more detailed information on iOS, refer to the `DetoxSync` project's [Status Documentation](https://github.com/wix-incubator/DetoxSync/blob/master/StatusDocumentation.md).

### `session.ignoreUnexpectedMessages` \[boolean]

Default: `false`.

Controls whether Detox should throw an error or log a warning when receiving unexpected WebSocket messages that don't match any registered handler or in-flight promise.

When set to `true`, unexpected messages will be logged as warnings instead of throwing a `DetoxRuntimeError`. This is particularly useful for applications with complex view hierarchies, such as React Native apps with WebViews, where legitimate messages might be received in unexpected contexts (e.g., messages from WebViews after switching back to native context).

```json
{
  "session": {
    "ignoreUnexpectedMessages": true
  }
}
```

:::tip

This option can also be controlled via the environment variable `DETOX_IGNORE_UNEXPECTED_WS_MESSAGES=true`.

:::