Storybook Detox Test Runner

This project enables you to test your Storybook for React Native stories using Detox.

How it works

The test runner injects itself into your Detox tests by overridding the Jest configuration. Before the tests run it generates a Jest test file for each of your Storybook story files. Each test uses Storybook's websockets to render the appropriate story, it then runs your story's play function, which may use the Detox API.

Getting started

1. Install storybook-detox-test-runner

1yarn add -D storybook-detox-test-runner

2. Ensure that Storybook, running on your app, has websockets enabled

1// .storybook/index.js
2...
3const StorybookUIRoot = view.getStorybookUI({
4  enableWebsockets: true
5})
6...

[!NOTE] This is different to the websockets property of withStorybook in metro.config.js

Do not enable the websockets property.

3. Install Detox

• Follow Detox's environment setup and project setup

• Remove the testRunner section from the Detox configuration and extend storybook-detox-test-runner

1// .detoxrc.js
2/** @type {Detox.DetoxConfig} */
3module.exports = {
4  extends: 'storybook-detox-test-runner',
5  configurations: {
6    ...

• If you use a flag to toggle Storybook, ensure it's enabled during the build, for example:

1// .detoxrc.js
2  ...
3  "app": {
4    "type": "android.apk",
5    "build": "cd android && STORYBOOK=true ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release",
6    "binaryPath": "android/app/build/outputs/apk/release/app-release.apk"
7  }
8  ...

4. Add .storybook/.detox-tests to your .gitignore

The test runner generates tests in your Storybook config directory, these don't need to be committed to source control.

[!NOTE] This assumes your Storybook config directory is .storybook

If you use a different directory, declare the environment variable STORYBOOK_CONFIG_DIR when running the tests.

1STORYBOOK_CONFIG_DIR=custom-dir yarn detox test

5. Build your test app with yarn detox build

Writing a test

Give your story a play function, access Detox functions like element and by from the detox argument to find and interact with elements.

1// counter.stories.tsx
2import { type Meta } from '@storybook/react-native'
3import type { DetoxStoryObj } from 'storybook-detox-test-runner/types'
4import Counter from 'src/components/counter'
5
6export default {
7  component: Counter
8} satisfies Meta<typeof Counter>
9
10export const WhenIClickOnTheCounterThenTheNumberGoesUp: DetoxStoryObj<typeof Counter> = {
11  play: async ({ detox: { by, element, waitFor } }) => {
12    // Wait for initial render.
13    await waitFor(element(by.text(/Count up/))).toBeVisible().withTimeout(1000)
14
15    // When
16    await element(by.text(/Count up/)).tap()
17    await element(by.text(/Count up/)).tap()
18    await element(by.text(/Count up/)).tap()
19    await element(by.text(/Count up/)).tap()
20    await element(by.text(/Count up/)).tap()
21
22    // Then
23    await waitFor(element(by.text(/5/))).toBeVisible()
24  }
25}

Running the test

Run Detox as normal with yarn detox test

Per-test configuration

You can trigger advanced behaviour for individual tests by adding a detox property to the story.

1// counter.stories.tsx
2...
3
4export const WhenIClickOnTheCounterThenTheNumberGoesUp: DetoxStoryObj<typeof Counter> = {
5  detox: {
6    onlyOnOperatingSystems: ['ios'] // Only run the test on iOS.
7    launch: { // Arguments passed to Detox's `device.launchApp`.
8      permissions: {
9        location: 'inuse'
10      }
11    }
12  },
13  play: async ({ detox }) => {
14    ...
15  }
16}