Skip to main content
Version: Next

Contributing

This guide is about contributing to our codebase.

We don’t have any special guidelines - just some setup walk-through!

Environment​

First, complete our Getting Started guide.

Install the monorepo management tool, lerna​

npm install lerna@3.x.x --global

For all the internal projects (detox, detox-cli, demos, test) lerna will create symbolic links in node_modules instead of npm copying the content of the projects. This way, any change you do on any code is there immediately. There is no need to update node modules or copy files between projects.

Install common React Native dependencies​

React-Native CLI:

npm install react-native-cli --global

Watchman:

brew install watchman

xcpretty​

You must also have xcpretty installed:

gem install xcpretty

Detox​

Clone Detox and Submodules​

git clone git@github.com:wix/Detox.git
cd detox
git submodule update --init --recursive

(this makes sure all git submodule dependencies have been properly checked out)

Installing and Linking Internal Projects​

lerna bootstrap

Building and Testing​

Automatically​

scripts/ci.ios.sh and scripts/ci.android.sh are the scripts Detox runs in CI, they will run lerna bootstrap, unit tests, and E2E tests. Make sure these scripts pass before submitting a PR, this is exactly what Detox is going to run in CI.

Manually​

The following steps can be run manually in order to build / test the various components of Detox.

1. Unit Tests and Lint​
lerna run test

Detox JS code is 100% test covered and is set to break the build if coverage gets below, so make sure you run unit tests (lerna run test) locally before pushing.

Alternatively, to run only the JS tests, run the following from the detox/detox directory:

npm run unit

or

npm run unit:watch

After running the tests, Jest will create a coverage report you can examine:

cd detox
open coverage/lcov-report/index.html
2. Running Detox E2E Coverage Tests​

Detox has a suite of end-to-end tests to test its own API while developing (and for regression); We maintain a special application that is "tested" against Detox’s API, but essentially, it’s the API that is tested, not the app.

To run the tests, you must first build the native code and then run based on your target of choice (Android / iOS):

  • iOS:

    cd detox/test
    npm run build:ios
    npm run e2e:ios

  • Android:

    cd detox/test
    npm run build:android
    npm run e2e:android

FYI Android test project includes two flavors:

  • fromBin - (standard use case) utilizes the precompiled .aar from node_modules just like a standard RN project.
  • fromSource - compiles the project with RN sources from node_modules, this is useful when developing and debugging Espresso idle resource. Here are the prerequisites to compiling React Native from source.

Each build can be triggered separately by running its Gradle assembling task (under detox/test/android/):

./gradlew assembleFromSourceDebug

or:

./gradlew assembleFromBinDebug

To run from Android Studio, React Native’s react.gradle script may require node to be in path. On MacOS, environment variables can be exported to desktop applications by adding the following to your .bashrc/.zshrc:

launchctl setenv PATH $PATH
3. Android Native Unit-Tests​

Under detox/:

npm run unit:android-release
Note

Due to limitations with Robolectric, this currently does not work with JDK 17. Best to use Java 11, as explained in the Android environment setup guide.

Detox - Example Projects​

This is in fact a monorepo that also sports some example projects (for usage reference), alongside the main test project:

  • examples/demo-react-native-jest: Demonstrate usage of Detox in a React Native app project.
  • examples/demo-native-ios: Demonstrates usage of Detox in a pure-native iOS app.
  • examples/demo-native-android (broken): Demonstrates usage of Detox in a pure-native Android app.
  • examples/demo-pure-native-android: Demonstrates usage of the pure Detox-Native project
  • more...

In order to run E2E tests associated with any of these projects, refer to the project-specific READMEs.

Detox Documentation Website​

The documentation website is built using Docusaurus.

To run the website locally, run the following commands:

cd website
npm install
npm start

Updating the Website​

To update a specific page, edit the corresponding markdown file in docs/. To add a new page, create a new markdown file in docs/ and add a link to it in website/sidebars.json.

Website Deployment​

While changes to the website are published automatically on every commit to master under the Next version, tagging and locking docs to a specific version is done automatically on every Detox release.

In case you want to update the docs for a specific version, you can change the related files and code under website/versioned_docs/version-<version>/ and website/versioned_sidebars/version-<version>-sidebars.json.

Update Old Versions​

To update a specific version with the latest changes:

  1. Remove the version from versions.json.
  2. Run npm run docusaurus docs:version <version>.
Inspect Documentation Style Changes​

This demo page serves as a visual representation of the styling and formatting of our documentation. If you are changing the stylesheets, check with it to prevent undesirable visual regressions.