|
| 1 | +# RNTester E2E folder |
| 2 | + |
| 3 | +In this folder we have a the setup for running E2E testing in RNTester via the usage of [Appium](https://appium.io/) and [WebDriverIO](https://webdriver.io/) and [Jest](https://jestjs.io/). |
| 4 | + |
| 5 | +- [Setting up locally](#setting-up-locally) |
| 6 | + - [(one-off) Setting up Appium](#one-off-setting-up-appium) |
| 7 | + - [Building RNTester app](#building-rntester-app) |
| 8 | + - [Building for iOS](#building-for-ios) |
| 9 | + - [Building for Android](#building-for-android) |
| 10 | + - [Setting up the RNTester E2E folder](#setting-up-the-rntester-e2e-folder) |
| 11 | +- [Testing the RNTester app E2E](#testing-the-rntester-app-e2e) |
| 12 | +- [Adding new tests (and project structure)](#adding-new-tests-and-project-structure) |
| 13 | + |
| 14 | +## Setting up locally |
| 15 | + |
| 16 | +### (one-off) Setting up Appium |
| 17 | + |
| 18 | +The first step you need to do is to ensure to install the tooling: |
| 19 | + |
| 20 | +```bash |
| 21 | + |
| 22 | +appium driver install uiautomator2 |
| 23 | +appium driver install xcuitest |
| 24 | +``` |
| 25 | + |
| 26 | +> More details about drivers in Appium [here](https://appium.github.io/appium/docs/en/2.0/guides/managing-exts/) and [here](https://appium.github.io/appium/docs/en/2.0/quickstart/uiauto2-driver/) |
| 27 | +
|
| 28 | +You should not need to run install commands for drivers separately more than once, even if you bump the dep in package.json. |
| 29 | + |
| 30 | +### Building RNTester app |
| 31 | + |
| 32 | +Building manually *.app* and *.apk* is required to run automation tests on local environment. |
| 33 | + |
| 34 | +0. *(optional)* If you previously built RNTester, you may need to clean up build files and Pods: |
| 35 | + |
| 36 | + ```bash |
| 37 | + yarn test-e2e-local-clean && yarn install |
| 38 | + ``` |
| 39 | + |
| 40 | +1. Step 1: install packages for the repository, then navigate in the rn-tester folder |
| 41 | + |
| 42 | + ```bash |
| 43 | + cd react-native |
| 44 | + yarn install |
| 45 | + cd packages/rn-tester |
| 46 | + ``` |
| 47 | + |
| 48 | +Now, depending on the platform, there are some specific steps |
| 49 | + |
| 50 | +#### Building for iOS |
| 51 | + |
| 52 | +0. Make sure you have Bundler `gem install bundler` - we use it ensure installing the right version of CocoaPods locally. |
| 53 | +1. Install Bundler and CocoaPods dependencies: `bundle install` then `bundle exec pod install` or `yarn setup-ios-hermes` for RNTester with Hermes. In order to use JSC instead of Hermes engine, run: `USE_HERMES=0 bundle exec pod install` or `setup-ios-jsc` instead. |
| 54 | +2. You can build app with React Native CLI or manually with Xcode: |
| 55 | + 1. To build with React Native CLI: |
| 56 | + 1. Run `npx react-native build-ios --mode Debug --scheme RNTester --buildFolder /path/to/build-folder`, replace `/path/to/build-folder` with the real path. |
| 57 | + 2. Copy the built app using `mv` - `mv /path/to/build-folder/Build/Products/Debug-iphonesimulator/RNTester.app ~/react-native/packages/rn-tester-e2e/apps` or manually. |
| 58 | + 2. To build with Xcode, open the generated `RNTester.xcworkspace` and build. |
| 59 | + 1. Find the **RNTester.app** in `~/Library/Developer/Xcode/DerivedData/RNTesterPods-{id}/Build/Products/Debug-iphonesimulator` |
| 60 | + 2. Copy the app to the following directory `~/react-native/packages/rn-tester-e2e/apps`. |
| 61 | +3. Change its name to: `rn-tester.app` |
| 62 | + |
| 63 | +#### Building for Android |
| 64 | + |
| 65 | +0. You'll need to have all the [prerequisites](https://reactnative.dev/contributing/how-to-build-from-source#prerequisites) (SDK, NDK) for Building React Native installed. |
| 66 | +1. Start an Android emulator. |
| 67 | +2. Build the app via |
| 68 | +
|
| 69 | + ```bash |
| 70 | + # In order to not use Hermes engine, run `yarn install-android-jsc` instead. |
| 71 | + yarn install-android-hermes |
| 72 | + yarn start |
| 73 | + ``` |
| 74 | +
|
| 75 | + *Note: Building for the first time can take a while.* |
| 76 | +
|
| 77 | +3. Find the **app-*-debug.apk** in `~/react-native/packages/rn-tester/android/app/build/outputs/apk/hermes/debug` |
| 78 | +4. Copy the app `app-*-debug.apk` to the following directory `~/react-native/packages/rn-tester-e2e/apps` |
| 79 | +5. Change its name to: `rn-tester.apk` |
| 80 | +
|
| 81 | +### Setting up the RNTester E2E folder |
| 82 | +
|
| 83 | +In `react-native/packages/rn-tester-e2e` open the following file |
| 84 | +
|
| 85 | +```bash |
| 86 | +/react-native/packages/rn-tester-e2e/e2e-config.js |
| 87 | +``` |
| 88 | +
|
| 89 | +And modify lines L24->L39 to reflect your local setup configuration (ex. `platformVersion`, `deviceName`). Make sure to **not** commit this change if you send a PR to add tests. |
| 90 | +
|
| 91 | +## Testing the RNTester app E2E |
| 92 | +
|
| 93 | +After you have done all the above correctly, and you have the Android/iOS apps in the `rn-tester-e2e/apps` folder, in a dedicated terminal window, run: |
| 94 | +
|
| 95 | +```bash |
| 96 | +appium --base-path /wd/hub |
| 97 | +``` |
| 98 | +
|
| 99 | +This will start the Appium server - you will need this to keep running. |
| 100 | +
|
| 101 | +Then open a second terminal window and start the Metro terminal from the `packages/rn-tester` folder, via `yarn start --reset-cache`. This terminal window also needs to keep running. |
| 102 | +
|
| 103 | +Now, make sure that the iOS simulator/the Android emulator is up and running. |
| 104 | +
|
| 105 | +Finally, you can open a third terminal window and run: |
| 106 | +
|
| 107 | +```bash |
| 108 | +yarn test-android-e2e # for android |
| 109 | +yarn test-ios-e2e # for ios |
| 110 | +``` |
| 111 | +
|
| 112 | +Now you should see the RNTester app being open, and the defined test being run. |
| 113 | +
|
| 114 | +## Adding new tests (and project structure) |
| 115 | +
|
| 116 | +This project has 2 main folders: |
| 117 | +
|
| 118 | +- `apps`, where, as you have seen above, the iOS/Android RNTester apps need to be put so that appium will pick them and install in the emulator/simulator consistently. |
| 119 | +
|
| 120 | +- `tests`, where the tests and referencing files all live. The substructure is as follows: |
| 121 | + - `screens` -> in this folder, you will find `*.screen.js` files, where each file represents a navigation screen for RNTester. So there are 3 root ones (`apis`, `bookmarks`, `components`) and then for subscreens, there's a folder with the same name - currently, that's only `components` that contains `buttonComponent.screen.js`. The content of these files is what was earlier mentioned as "references": they provide an easy way to define all elements present in said screen, so that they can be used for tests. |
| 122 | + - `specs` -> this folder follows a similar 1:1 mapping to the RNTester screens, but for the tests: for each screen (or subscreen) there's a dedicated `*.test.js` file (such as `buttonComponentScreen.test.js`). Ideally, in this file the Jest tests are standard, leveraging the `*.screen.js` counterpart for the details of defining how Appium/WDIO can reach those elements on screen. |
| 123 | + |
| 124 | +When adding a new test, please ensure that you follow this pattern and add the relevant test in the right screen file / screen test file. Use the files mentioned above as examples. |
0 commit comments