diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 4e7a00cf27d051..2e6900e2782db6 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -146,6 +146,10 @@ npm install -g react-native-cli The easiest way to install Xcode is via the [Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12). Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app. +You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown. + +![Xcode Command Line Tools](img/XcodeCommandLineTools.png) + ### Android Development Environment @@ -158,20 +162,13 @@ Setting up your development environment can be somewhat tedious if you're new to -> Android Studio requires the [Java SE Development Kit(JDK)](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html), version 8. You can type `javac -version` in a terminal to see what version you have, if any. - -``` -$ javac -version -javac 1.8.0_111 -``` - -> The version string `1.8.x_xxx` corresponds to JDK 8. +> Android Studio requires a recent version of the [Java SE Development Kit (JDK)](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). #### 2. Install the AVD and HAXM -Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked: +Android Virtual Devices allow you to run Android apps on your computer without the need for an actual Android phone or tablet. Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked: - `Android SDK` - `Android SDK Platform` @@ -186,7 +183,7 @@ Then, click "Next" to install all of these components. #### 2. Install the AVD and configure VM acceleration -Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked: +Android Virtual Devices allow you to run Android apps on your computer without the need for an actual Android phone or tablet. Choose `Custom` installation when running Android Studio for the first time. Make sure the boxes next to all of the following are checked: - `Android SDK` - `Android SDK Platform` @@ -206,10 +203,11 @@ Select the "SDK Platforms" tab from within the SDK Manager, then check the box n - `Google APIs` - `Android SDK Platform 23` -- `Intel x86 Atom System Image` - `Intel x86 Atom_64 System Image` - `Google APIs Intel x86 Atom_64 System Image` +![Android SDK Manager](img/AndroidSDKManager.png) + Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build Tools" entry, then make sure that `Android SDK Build-Tools 23.0.1` is selected. Finally, click "Apply" to download and install the Android SDK and related build tools. @@ -222,7 +220,7 @@ The React Native command line interface requires the `ANDROID_HOME` environment -Add the following lines to your `~/.bashrc` (or equivalent) config file: +Add the following lines to your `~/.profile` (or equivalent) config file: ``` export ANDROID_HOME=${HOME}/Library/Android/sdk @@ -230,11 +228,13 @@ export PATH=${PATH}:${ANDROID_HOME}/tools export PATH=${PATH}:${ANDROID_HOME}/platform-tools ``` +Type `source ~/.profile` to load the config into your current shell. + > Please make sure you export the correct path for `ANDROID_HOME`. If you installed the Android SDK using Homebrew, it would be located at `/usr/local/opt/android-sdk`. -Add the following lines to your `~/.bashrc` (or equivalent) config file: +Add the following lines to your `~/.profile` (or equivalent) config file: ``` export ANDROID_HOME=${HOME}/Android/Sdk @@ -242,6 +242,8 @@ export PATH=${PATH}:${ANDROID_HOME}/tools export PATH=${PATH}:${ANDROID_HOME}/platform-tools ``` +Type `source ~/.profile` to load the config into your current shell. + > Please make sure you export the correct path for `ANDROID_HOME` if you did not install the Android SDK using Android Studio. @@ -276,9 +278,15 @@ You can see the list of available AVDs by opening the "AVD Manager" from within android avd ``` -Once in the "AVD Manager", select your AVD and click "Start...". +Once in the "AVD Manager", select your AVD and click "Edit...". Choose "Android 6.0 - API Level 23" under Device, and "Intel Atom (x86_64)" under CPU/ABI. Click OK, then select your new AVD and click "Start...", and finally, "Launch". -> Android Studio should have set up an Android Virtual Device for you during installation, but it is very common to run into an issue where Android Studio fails to install the AVD. You may follow the [Android Studio User Guide](https://developer.android.com/studio/run/managing-avds.html) to create a new AVD manually if needed. +![Android AVD Configuration](img/AndroidAVDConfiguration.png) + +> It is very common to run into an issue where Android Studio fails to create a default AVD. You may follow the [Android Studio User Guide](https://developer.android.com/studio/run/managing-avds.html) to create a new AVD manually if needed. + +### Using a real device + +If you have a physical Android device, you can use it for development in place of an AVD. Plug it in to your computer using a USB cable and [enable USB debugging](https://developer.android.com/training/basics/firstapp/running-app.html) before proceeding to the next step. @@ -296,6 +304,8 @@ react-native run-ios You should see your new app running in the iOS Simulator shortly. +![AwesomeProject on iOS](img/iOSSuccess.png) + `react-native run-ios` is just one way to run your app. You can also run it directly from within Xcode or [Nuclide](https://nuclide.io/). @@ -308,7 +318,9 @@ cd AwesomeProject react-native run-android ``` -If everything is set up correctly, you should see your new app running in your AVD shortly. +If everything is set up correctly, you should see your new app running in your Android emulator shortly. + +![AwesomeProject on Android](img/AndroidSuccess.png) `react-native run-android` is just one way to run your app - you can also run it directly from within Android Studio or [Nuclide](https://nuclide.io/). @@ -348,7 +360,7 @@ cd AwesomeProject react-native start ``` -Open a new command prompt and run `react-native run-android` inside the same folder to launch the app on your AVD. +Open a new command prompt and run `react-native run-android` inside the same folder to launch the app on your Android emulator. ``` react-native run-android @@ -370,11 +382,7 @@ react-native run-android If everything is set up correctly, you should see your new app running in your Android emulator shortly. - - -> If you're targeting API level 23, the app might crash on first launch with an error smilar to `Unable to add window android.view.ViewRootImpl$W@c51fa6 -- permission denied for this window type`. To fix this, you need to go to `System settings > Apps > Configure apps > Draw over other apps` and grant the permission for the app. - -NOTE: Many React Native modules haven't been tested on Marshmallow and might break. Please thoroughly test the app if you target API level 23 and file a bug report if you find that something is broken. +![AwesomeProject on Android](img/AndroidSuccess.png) diff --git a/docs/Testing.md b/docs/Testing.md index b503c522017b60..77433b1c98d96b 100644 --- a/docs/Testing.md +++ b/docs/Testing.md @@ -8,15 +8,17 @@ next: running-on-device previous: debugging --- -## Running Tests and Contributing - This document is about running tests on React Native itself. If you're interested in testing a React Native app, check out the [React Native Tutorial](http://facebook.github.io/jest/docs/tutorial-react-native.html) on the Jest website. -The React Native repo has several tests you can run to verify you haven't caused a regression with your PR. These tests are run with the [Travis](http://docs.travis-ci.com/) and [CircleCI](https://circleci.com/) continuous integration systems, which will automatically annotate pull requests with the test results. +## Running Tests and Contributing + +The React Native repo has several tests you can run to verify you haven't caused a regression with your PR. These tests are run with the [Travis](https://travis-ci.org/facebook/react-native/builds) and [CircleCI](https://circleci.com/gh/facebook/react-native) continuous integration systems, which will automatically annotate pull requests with the test results. Whenever you are fixing a bug or adding new functionality to React Native, you should add a test that covers it. Depending on the change you're making, there are different types of tests that may be appropriate. -## Jest Tests +## JavaScript Tests + +### Jest Jest tests are JavaScript-only tests run on the command line with node. You can run the existing React Native jest tests with: @@ -27,9 +29,25 @@ It's a good idea to add a Jest test when you are working on a change that only m The tests themselves live in the `__tests__` directories of the files they test. See [`TouchableHighlight-test.js`](https://github.com/facebook/react-native/blob/master/Libraries/Components/Touchable/__tests__/TouchableHighlight-test.js) for a basic example. -## Android Unit Tests +### Flow + +You should also make sure your code passes [Flow](https://flowtype.org/) tests. These can be run using: + + $ cd react-native + $ npm run flow + +## Android + +### Unit Tests + +The Android unit tests do not run in an emulator. They just use a normal Java installation. The default macOS Java install is insufficient, you may need to install [Java 8 (JDK8)](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). You can type `javac -version` in a terminal to see what version you have: -The Android unit tests do not run in an emulator. They just use a normal Java installation. You do need to install Java 8. In particular, the default OS X Java install is insufficient. +``` +$ javac -version +javac 1.8.0_111 +``` + +The version string `1.8.x_xxx` corresponds to JDK 8. You also need to install the [Buck build tool](https://buckbuild.com/setup/install.html). @@ -40,7 +58,7 @@ To run the Android unit tests: It's a good idea to add an Android unit test whenever you are working on code that can be tested by Java code alone. The Android unit tests live under [`ReactAndroid/src/tests`](https://github.com/facebook/react-native/tree/master/ReactAndroid/src/test/java/com/facebook/react), so you can browse through that directory for good examples of tests. -## Android Integration Tests +### Integration Tests To run the integration tests, you need to install the Android NDK. See [Prerequisites](docs/android-building-from-source.html#prerequisites). @@ -60,16 +78,48 @@ Once you have an emulator running, to run the integration tests: The integration tests should only take a few minutes to run on a modern developer machine. -It's a good idea to add an Android integration test whenever you are working on code that needs both JavaScript and Java to be tested in conjunction. The Android integration tests live under [`ReactAndroid/src/androidTest`](https://github.com/facebook/react-native/tree/master/ReactAndroid/src/androidTest/java/com/facebook/react/tests), so you can browse through that directory for good examples of tests. +It's a good idea to add an Android integration test whenever you are working on code that needs both JavaScript and Java to be tested in conjunction. The Android integration tests live under [`ReactAndroid/src/androidTest`](https://github.com/facebook/react-native/tree/master/ReactAndroid/src/androidTest/java/com/facebook/react/tests), so you can browse through that directory for good examples of tests. + +## iOS + +### Integration Tests -## iOS Integration Tests +React Native provides facilities to make it easier to test integrated components that require both native and JS components to communicate across the bridge. The two main components are `RCTTestRunner` and `RCTTestModule`. `RCTTestRunner` sets up the ReactNative environment and provides facilities to run the tests as `XCTestCase`s in Xcode (`runTest:module` is the simplest method). `RCTTestModule` is exported to JS as `NativeModules.TestModule`. -React Native provides facilities to make it easier to test integrated components that require both native and JS components to communicate across the bridge. The two main components are `RCTTestRunner` and `RCTTestModule`. `RCTTestRunner` sets up the ReactNative environment and provides facilities to run the tests as `XCTestCase`s in Xcode (`runTest:module` is the simplest method). `RCTTestModule` is exported to JS as `NativeModules.TestModule`. The tests themselves are written in JS, and must call `TestModule.markTestCompleted()` when they are done, otherwise the test will timeout and fail. Test failures are primarily indicated by throwing a JS exception. It is also possible to test error conditions with `runTest:module:initialProps:expectErrorRegex:` or `runTest:module:initialProps:expectErrorBlock:` which will expect an error to be thrown and verify the error matches the provided criteria. See [`IntegrationTestHarnessTest.js`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestHarnessTest.js), [`UIExplorerIntegrationTests.m`](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/UIExplorerIntegrationTests/UIExplorerIntegrationTests.m), and [IntegrationTestsApp.js](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestsApp.js) for example usage and integration points. +The tests themselves are written in JS, and must call `TestModule.markTestCompleted()` when they are done, otherwise the test will timeout and fail. Test failures are primarily indicated by throwing a JS exception. It is also possible to test error conditions with `runTest:module:initialProps:expectErrorRegex:` or `runTest:module:initialProps:expectErrorBlock:` which will expect an error to be thrown and verify the error matches the provided criteria. -You can run integration tests locally with cmd+U in the IntegrationTest and UIExplorer apps in Xcode. +See the following for example usage and integration points: -## iOS Screenshot/Snapshot Tests +- [`IntegrationTestHarnessTest.js`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestHarnessTest.js) +- [`UIExplorerIntegrationTests.m`](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/UIExplorerIntegrationTests/UIExplorerIntegrationTests.m) +- [`IntegrationTestsApp.js`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestsApp.js) + +You can run integration tests locally with cmd+U in the IntegrationTest and UIExplorer apps in Xcode, or by running the following in the command line on macOS: + + $ cd react-native + $ ./scripts/objc-test-ios.sh + +> Your Xcode install will come with a variety of Simulators running the latest OS. You may need to manually create a new Simulator to match what the `XCODE_DESTINATION` param in the test script. + +### Screenshot/Snapshot Tests A common type of integration test is the snapshot test. These tests render a component, and verify snapshots of the screen against reference images using `TestModule.verifySnapshot()`, using the [`FBSnapshotTestCase`](https://github.com/facebook/ios-snapshot-test-case) library behind the scenes. Reference images are recorded by setting `recordMode = YES` on the `RCTTestRunner`, then running the tests. Snapshots will differ slightly between 32 and 64 bit, and various OS versions, so it's recommended that you enforce tests are run with the correct configuration. It's also highly recommended that all network data be mocked out, along with other potentially troublesome dependencies. See [`SimpleSnapshotTest`](https://github.com/facebook/react-native/blob/master/IntegrationTests/SimpleSnapshotTest.js) for a basic example. If you make a change that affects a snapshot test in a PR, such as adding a new example case to one of the examples that is snapshotted, you'll need to re-record the snapshot reference image. To do this, simply change to `_runner.recordMode = YES;` in [UIExplorer/UIExplorerSnapshotTests.m](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/UIExplorerIntegrationTests/UIExplorerSnapshotTests.m#L42), re-run the failing tests, then flip record back to `NO` and submit/update your PR and wait to see if the Travis build passes. + +## End-to-end tests + +Finally, make sure end-to-end tests run successfully by executing the following script: + + $ cd react-native + $ ./scripts/test-manual-e2e.sh + +## Website + +The React Native website is hosted on GitHub pages and is automatically generated from Markdown sources as well as comments in the JavaScript source files. It's always a good idea to check that the website is generated properly whenever you edit the docs. + + $ cd website + $ npm install + $ npm start + +Then open http://localhost:8079/react-native/index.html in your browser. diff --git a/website/src/react-native/img/AndroidAVDConfiguration.png b/website/src/react-native/img/AndroidAVDConfiguration.png new file mode 100644 index 00000000000000..ef5e3e8b25cad5 Binary files /dev/null and b/website/src/react-native/img/AndroidAVDConfiguration.png differ diff --git a/website/src/react-native/img/AndroidSDKManager.png b/website/src/react-native/img/AndroidSDKManager.png new file mode 100644 index 00000000000000..eca03a0bfb6dea Binary files /dev/null and b/website/src/react-native/img/AndroidSDKManager.png differ diff --git a/website/src/react-native/img/AndroidSuccess.png b/website/src/react-native/img/AndroidSuccess.png new file mode 100644 index 00000000000000..bd10f089756efd Binary files /dev/null and b/website/src/react-native/img/AndroidSuccess.png differ diff --git a/website/src/react-native/img/XcodeCommandLineTools.png b/website/src/react-native/img/XcodeCommandLineTools.png new file mode 100644 index 00000000000000..e19d3a9f79452c Binary files /dev/null and b/website/src/react-native/img/XcodeCommandLineTools.png differ diff --git a/website/src/react-native/img/iOSSuccess.png b/website/src/react-native/img/iOSSuccess.png new file mode 100644 index 00000000000000..457824f4ee5028 Binary files /dev/null and b/website/src/react-native/img/iOSSuccess.png differ