diff --git a/.circleci/DockerTests.md b/.circleci/DockerTests.md index 0c9812d47e..c65e72640e 100644 --- a/.circleci/DockerTests.md +++ b/.circleci/DockerTests.md @@ -1,72 +1,34 @@ -# Dockerfile Tests +# Docker Test Environment -This is a high-level overview of the test configuration using Docker. It explains how to run the tests locally. +This is a high-level overview of the test configuration using Docker. +It explains how to run the tests locally. ## Docker Installation It is required to have Docker running on your machine in order to build and run the tests in the Dockerfiles. See for more information on how to install. -## Convenience Yarn Run Scripts +## Convenience Scripts We have added a number of default run scripts to the `package.json` file to simplify building and running your tests. -`yarn run docker-setup-android` - Pulls down the base android docker image used for running the tests +### Configuring Docker Images -`yarn run docker-build-android` - Builds the docker image used to run the tests +The following two scripts need to be run first before you can move on to testing: -`yarn run test-android-run-unit` - Runs all the unit tests that have been built in the latest reactnativeci/android docker image (note: you need to run test-android-build before executing this if the image does not exist it will fail) +- `yarn run docker-setup-android`: Pulls down the React Native Community Android image that serves as a base image when building the actual test image. -`yarn run test-android-run-instrumentation` - Runs all the instrumentation tests that have been built in the latest reactnativeci/android docker image. If the image does not exist, run `test-android-build` before. You can also pass additional flags to filter which tests instrumentation tests are run. Ex: `yarn run test-android-run-instrumentation -- --filter=TestIdTestCase` to only run the TestIdTestCase instrumentation test. See below for more information -on the instrumentation test flags. +- `yarn run docker-build-android`: Builds a test image with the latest dependencies and React Native library code, including a compiled Android test app. -`yarn run test-android-run-e2e` - Runs all the end to end tests that have been built in the latest reactnativeci/android docker image (note: you need to run test-android-build before executing this if the image does not exist it will fail) +### Running Tests -`yarn run test-android-unit` - Builds and runs the Android unit tests. +Once the test image has been built, it can be used to run our Android tests. -`yarn run test-android-instrumentation` - Builds and runs the Android instrumentation tests. +- `yarn run test-android-run-unit` runs the unit tests, as defined in `scripts/run-android-docker-unit-tests.sh`. +- `yarn run test-android-run-e2e` runs the end to end tests, as defined in `scripts/run-ci-e2e-tests.sh`. +- `yarn run test-android-run-instrumentation` runs the instrumentation tests, as defined in `scripts/run-android-docker-instrumentation-tests.sh`. -`yarn run test-android-e2e` - Builds and runs the Android end to end tests. - -## Detailed Android Setup - -There are two Dockerfiles for use with the Android codebase. - -The `Dockerfile.android-base` contains all the necessary prerequisites required to run the React Android tests. It is -separated out into a separate Dockerfile because these are dependencies that rarely change and also because it is quite -a beastly image since it contains all the Android dependencies for running Android and the emulators (~9GB). - -The good news is you should rarely have to build or pull down the base image! All iterative code updates happen as -part of the `Dockerfile.android` image build. - -So step one... - -`docker pull reactnativecommunity/react-native-android:latest` - -This will take quite some time depending on your connection and you need to ensure you have ~10GB of free disk space. - -Once this is done, you can run tests locally by executing two simple commands: - -1. `docker build -t reactnativeci/android -f ./.circleci/Dockerfiles/Dockerfile.android .` -2. `docker run --cap-add=SYS_ADMIN -it reactnativeci/android bash .circleci/Dockerfiles/scripts/run-android-docker-unit-tests.sh` - -> Note: `--cap-add=SYS_ADMIN` flag is required for the `.circleci/Dockerfiles/scripts/run-android-docker-unit-tests.sh` and -`.circleci/Dockerfiles/scripts/run-android-docker-instrumentation-tests.sh` in order to allow the remounting of `/dev/shm` as writeable -so the `buck` build system may write temporary output to that location - -Every time you make any modifications to the codebase, you should re-run the `docker build ...` command in order for your -updates to be included in your local docker image. - -The following shell scripts have been provided for android testing: - -`.circleci/Dockerfiles/scripts/run-android-docker-unit-tests.sh` - Runs the standard android unit tests - -`.circleci/Dockerfiles/scripts/run-android-docker-instrumentation-tests.sh` - Runs the Android instrumentation tests on the emulator. *Note* that these -tests take quite some time to run so there are various flags you can pass in order to filter which tests are run (see below) - -`.circleci/Dockerfiles/scripts/run-ci-e2e-tests.sh` - Runs the android end to end tests - -#### .circleci/Dockerfiles/scripts/run-android-docker-instrumentation-tests.sh +#### Instrumentation Tests The instrumentation test script accepts the following flags in order to customize the execution of the tests: @@ -79,5 +41,41 @@ The instrumentation test script accepts the following flags in order to customiz `--retries` - Number of times to retry a failed test before declaring a failure (Defaults to 2) For example, if locally you only wanted to run the InitialPropsTestCase, you could do the following: +`yarn run test-android-run-instrumentation -- --filter="InitialPropsTestCase"` -`docker run --cap-add=SYS_ADMIN -it reactnativeci/android bash .circleci/Dockerfiles/scripts/run-android-docker-instrumentation-tests.sh --filter="InitialPropsTestCase"` +## Detailed Android Setup + +There are two Dockerfiles for use with the Android codebase. +The base image used to build `reactnativecommunity/react-native-android` is located in the https://github.com/react-native-community/docker-android GitHub repository. +It contains all the necessary prerequisites required to run the React Android tests. +It is separated out into a separate Dockerfile because these are dependencies that rarely change and also because it is quite a beastly image since it contains all the Android dependencies for running Android and the emulators (~9GB). + +The good news is you should rarely have to build or pull down the base image! +All iterative code updates happen as part of the `Dockerfile.android` image build. + +Lets break it down... + +First, you'll need to pull the base image. +You can use `docker pull` to grab the latest version of the `reactnativecommunity/react-native-android` base image. +This is what you get when you run `yarn run docker-setup-android`. + +This will take quite some time depending on your connection and you need to ensure you have ~10GB of free disk space. + +Once you have downloaded the base image, the test image can be built using `docker build -t reactnativeci/android -f ./.circleci/Dockerfiles/Dockerfile.android .`. This is what `yarn run docker-build-android` does. Note that the `-t` flag is how you tell Docker what to name this image locally. You can then use `docker run -t reactnativeci/android` to run this image. + +Now that you've built the test image, you can run unit tests using what you've learned so far: + +```bash +docker run --cap-add=SYS_ADMIN -it reactnativeci/android bash .circleci/Dockerfiles/scripts/run-android-docker-unit-tests.sh +``` + +> Note: `--cap-add=SYS_ADMIN` flag is required for the `.circleci/Dockerfiles/scripts/run-android-docker-unit-tests.sh` and `.circleci/Dockerfiles/scripts/run-android-docker-instrumentation-tests.sh` in order to allow the remounting of `/dev/shm` as writeable so the `buck` build system may write temporary output to that location. + +Every time you make any modifications to the codebase, including changes to the test scripts inside `.circleci/Dockerfiles/scripts`, you should re-run the `docker build ...` command in order for your updates to be included in your local docker test image. + +For rapid iteration, it's useful to keep in mind that Docker can pass along arbitrary commands to an image. +For example, you can alternatively use Gradle in this manner: + +```bash +docker run --cap-add=SYS_ADMIN -it reactnativeci/android ./gradlew RNTester:android:app:assembleRelease +``` diff --git a/.circleci/Dockerfiles/Dockerfile.android b/.circleci/Dockerfiles/Dockerfile.android index 28a923710d..4b3a95d8a8 100644 --- a/.circleci/Dockerfiles/Dockerfile.android +++ b/.circleci/Dockerfiles/Dockerfile.android @@ -2,41 +2,43 @@ # # This source code is licensed under the MIT license found in the # LICENSE file in the root directory of this source tree. - -# React Native Android Unit Tests # -# This image builds upon the React Native Base Android Development Environment -# image. Ideally, this image would be rebuilt with any new commit to the master -# branch. Doing so will catch issues such as BUCK failing to fetch dependencies -# or run tests, as well as unit test failures. -FROM react-native-community/react-native +# This image builds upon the React Native Community Android image: +# https://github.com/react-native-community/docker-android +# +# The base image is expected to remain relatively stable, and only +# needs to be updated when major dependencies such as the Android +# SDK or NDK are updated. +# +# In this Android Test image, we download the latest dependencies +# and build a Android application that can be used to run the +# tests specified in the scripts/ directory. +# +FROM reactnativecommunity/react-native-android -LABEL Description="This image prepares and runs React Native's Android tests." +LABEL Description="React Native Android Test Image" LABEL maintainer="Héctor Ramos " # set default environment variables ENV GRADLE_OPTS="-Dorg.gradle.daemon=false -Dorg.gradle.jvmargs=\"-Xmx512m -XX:+HeapDumpOnOutOfMemoryError\"" ENV JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF8" -# add ReactAndroid directory ADD .buckconfig /app/.buckconfig ADD .buckjavaargs /app/.buckjavaargs +ADD tools /app/tools ADD ReactAndroid /app/ReactAndroid ADD ReactCommon /app/ReactCommon -ADD ReactNative /app/ReactNative +ADD React /app/React ADD keystores /app/keystores -# set workdir WORKDIR /app -# run buck fetches RUN buck fetch ReactAndroid/src/test/java/com/facebook/react/modules RUN buck fetch ReactAndroid/src/main/java/com/facebook/react RUN buck fetch ReactAndroid/src/main/java/com/facebook/react/shell RUN buck fetch ReactAndroid/src/test/... RUN buck fetch ReactAndroid/src/androidTest/... -# build app RUN buck build ReactAndroid/src/main/java/com/facebook/react RUN buck build ReactAndroid/src/main/java/com/facebook/react/shell @@ -46,22 +48,10 @@ ADD settings.gradle /app/settings.gradle ADD build.gradle /app/build.gradle ADD react.gradle /app/react.gradle -# run gradle downloads RUN ./gradlew :ReactAndroid:downloadBoost :ReactAndroid:downloadDoubleConversion :ReactAndroid:downloadFolly :ReactAndroid:downloadGlog :ReactAndroid:downloadJSC -# compile native libs with Gradle script, we need bridge for unit and integration tests RUN ./gradlew :ReactAndroid:packageReactNdkLibsForBuck -Pjobs=1 -# add all react-native code ADD . /app -WORKDIR /app -# build node dependencies -RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - -RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list -RUN apt-get install apt-transport-https -RUN apt-get update -RUN apt-get install yarn RUN yarn - -WORKDIR /app