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
- Yarn
- pnpm
npm install lerna@3.x.x --global
yarn global add lerna@3.x.x
pnpm add 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
- Yarn
- pnpm
npm install react-native-cli --global
yarn global add react-native-cli
pnpm add 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
- Yarn
- pnpm
npm run unit
yarn unit
pnpm run unit
or
- npm
- Yarn
- pnpm
npm run unit:watch
yarn unit:watch
pnpm 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:
- npm
- Yarn
- pnpm
cd detox/test
npm run build:ios
npm run e2e:ioscd detox/test
yarn build:ios
yarn e2e:ioscd detox/test
pnpm run build:ios
pnpm run e2e:iosAndroid:
- npm
- Yarn
- pnpm
cd detox/test
npm run build:android
npm run e2e:androidcd detox/test
yarn build:android
yarn e2e:androidcd detox/test
pnpm run build:android
pnpm run e2e:android
FYI Android test project includes two flavors:
fromBin
- (standard use case) utilizes the precompiled.aar
fromnode_modules
just like a standard RN project.fromSource
- compiles the project with RN sources fromnode_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/android
:
./gradlew testFullRelease
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:
- npm
- Yarn
- pnpm
cd website
npm install
npm start
cd website
yarn install
yarn start
cd website
pnpm install
pnpm 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:
- Remove the version from
versions.json
. - 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.