Skip to content

Latest commit

 

History

History
229 lines (146 loc) · 7.23 KB

Guide.Contributing.md

File metadata and controls

229 lines (146 loc) · 7.23 KB
id slug title sidebar_label
contributing
contributing
Contributing
Contributing

Contributing

This guide is about contributing to our codebase.

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

Environment

Install Homebrew

If you haven’t yet - install brew.

Install Node.js v12.x or newer

There’s more than one way to install Node.js:

The best way is to use nvm, but the simplest way is to use Homebrew:

brew install node

Install npm

Either install npm or check that you have it installed, using their official guide.

NOTE: For Detox, please use the latest npm version 6.x.x (i.e not version 7.0.0 or newer).

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

iOS

For iOS, you must install Xcode and related tools. Refer to our Setting Up an iOS Environment guide.

You must also have xcpretty installed:

gem install xcpretty

Android

For Android, you need to have Java and the Android SDK properly set up. Refer to our Setting Up an Android Development & Testing Environment guide.

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.

0. (React Native ≤ 0.55.x) Fixing Compilation Issues in RN Sources

Detox Android test project uses React Native sources instead of the precompiled AAR. The test project uses React Native 0.51 and 0.53, both have issues with compilation (fixed in 0.55). In order to fix this issue, from inside detox/test run:

mv node_modules/react-native/ReactAndroid/release.gradle node_modules/react-native/ReactAndroid/release.gradle.bak
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/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 and examples/demo-react-native-jest: Demonstrate usage of Detox in React-Native app projects, with mocha.js and Jest as the hosting test-runner frameworks, respectively.
  • 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>.