2523: Update documentation for e2e tests (#2601)

* 2523: Update documentation for e2e tests

* 2523: Improve wording

docs/e2e-tests.md

@@ -70,19 +70,7 @@ yarn workspace e2e test:web --spec regexp
 
 ### Local Testing
 
-For you first have to build and install the app with the E2E build configuration and start the packager:
-
-```
-yarn workspace e2e prepare:native:android
-yarn workspace e2e prepare:native:start
-```
-
-It is recommended to start the app once manually to avoid timeouts during local testing. After you have the app
-installed and running you can execute the native E2E-tests with
-
-```
-yarn workspace e2e test:native
-```
+Check the documents [here](../native/docs/e2e-testing.md).
 
 #### Selectors
 
@@ -92,7 +80,7 @@ Therefore, you should use the accessibility identifier for this.
 Add the accessibility-id to a React component using `testID('Example-Component')`. You can query this component
 with `$('~Example-Component')` in your test.
 
-For more complex queries you should add/use a custom [Selector](../e2e-tests/native/test/Selector.ts)
+For more complex queries you should add/use a custom [Selector](../e2e-tests/native/test/helpers/Selector.ts)
 using [predicate strings](https://github.com/facebookarchive/WebDriverAgent/wiki/Predicate-Queries-Construction-Rules)
 for iOS and [UiSelectors](https://developer.android.com/reference/androidx/test/uiautomator/UiSelector) for Android.
 

e2e-tests/native/wdio-ios.conf.ts

@@ -4,18 +4,17 @@ import { config as defaultConfig } from './wdio.conf.js'
 
 const iosCapabilities: Capabilities.DesiredCapabilities = {
   platformName: 'iOS',
-  // http://appium.io/docs/en/writing-running-appium/caps/
-  'appium:deviceName': 'iPhone 13 Pro Max',
-  'appium:platformVersion': '15.2',
+  // http://appium.io/docs/en/2.1/guides/caps/
+  'appium:deviceName': 'iPhone 14',
+  'appium:platformVersion': '16.4',
   'appium:orientation': 'PORTRAIT',
   'appium:automationName': 'XCUITest',
   'appium:language': 'EN',
   /* how to get BUILD_DIR:
-  XCode: Product -> "show build folder in finder" -> drag item in terminal window
-  Command line (native/ios): xcodebuild -scheme integreat-e2e -workspace Integreat.xcworkspace ONLY_ACTIVE_ARCH=NO -sdk iphonesimulator -configuration Debug -showBuildSettings | grep -m 1 "BUILT_PRODUCTS_DIR" | grep -oEi "\/.*"
-  Example BUILD_DIR= '/Users/afischer/Library/Developer/Xcode/DerivedData/Integreat-enomkojtzvcuyvfzikuktexfnnki/Build/Products/Debug-iphonesimulator',
+  XCode: Product -> "Copy Build Folder Path"
+  Example BUILD_DIR= '/Users/afischer/Library/Developer/Xcode/DerivedData/Integreat-enomkojtzvcuyvfzikuktexfnnki/Build',
   */
-  'appium:app': `${process.env.BUILD_DIR}/Integreat.app`,
+  'appium:app': `${process.env.BUILD_DIR}/Products/Debug-iphonesimulator/Integreat.app`,
   'appium:newCommandTimeout': 240,
 }
 

e2e-tests/package.json

@@ -22,10 +22,11 @@
     "@wdio/cli": "^8.3.2",
     "@wdio/globals": "8.2.3",
     "@wdio/jasmine-framework": "^8.3.2",
-    "@wdio/spec-reporter": "^8.3.0",
     "@wdio/local-runner": "^8.3.2",
     "@wdio/selenium-standalone-service": "^8.3.2",
+    "@wdio/spec-reporter": "^8.3.0",
     "@wdio/types": "^8.3.0",
+    "appium": "^2.2.1",
     "webdriverio": "^8.3.2"
   },
   "workspaces": {

native/docs/e2e-testing.md

@@ -1,57 +1,44 @@
 # End to End Tests
 
 We are using Jest and Appium to run the tests.
-The `e2e-tests/config/configs.js` contains the urls to the Appium servers and the capability definitions. A set of
-capabilities is like a requirement of devices you want to test against (e.g. Android 9/iOS 11)
-. [Here](https://www.browserstack.com/app-automate/capabilities) is a good definition of capabilities and which caps you
-can set.
+The file `e2e-tests/native/capabilities.ts` contains the capability definitions. A set of capabilities is like a
+requirement of devices you want to test against (e.g. Android 9/iOS 11).
+[Here](https://www.browserstack.com/app-automate/capabilities) is a good definition of capabilities and which
+properties you can set.
 
-## Setup
+## Running the tests locally
 
-To run the tests locally you first need to setup an Appium server. You
-can [read here](https://github.com/appium/appium/blob/master/docs/en/about-appium/getting-started.md) how to do this.
-Start `appium` and an emulator/simulator.
+### Android
 
-### Building the app for e2e tests
+1. Start an emulator (only the emulator, don't need to manually start the app)
+2. Start the app: `yarn prepare:native:start`
+3. Install the apk on the emulator: `yarn prepare:native:android`
+4. Start the tests: `yarn test:native`
 
-To build for e2e tests, use the [corresponding build config](../../build-configs/integreat-e2e).
+### iOS
 
-### Using appium-desktop
+1. Create an emulator with the settings from `wdio-ios.conf.ts`; if necessary, install the driver
 
-[Appium Desktop](https://github.com/appium/appium-desktop) allows you to inspect the tree of the app.
+   1.1. If the driver isn't available anymore, update the settings in the config file to a more recent one, ideally the
+   ones from `e2e-tests/native/capabilities.ts`.
 
-Getting started:
+2. Start the app: `yarn prepare:native:start`
+3. Find your build file folder: Product > Copy Build Folder Path
+4. Add the BUILD_DIR to your environment. In zshell you do this via `BUILD_DIR=your/copied/build/folder/path; export BUILD_DIR` but your command line might differ.
+5. Run tests via `yarn test:native:ios`
 
-- Download and start Appium
-- Start Server
-- Click `search icon`
-- Add to `Desired Capabilities`:
+### Using Appium Inspector
 
-```
-{
-  "app": "<your-path-to>/integreat-app/native/android/app/build/outputs/apk/debug/app-debug.apk",
-  "platformName": "Android"
-  }
-```
-
-- Click `start session`
-- Now you can open a page in the emulator and inspect it
-
-### Running tests locally
+When writing tests, it may be helpful to use the (Appium Inspector)[https://github.com/appium/appium-inspector] to
+inspect the tree of the app.
 
-To run tests locally do: `E2E_CONFIG=local_android yarn test:e2e`
-
-#### iOS
-
-- start the simulator in XCode with the capabilities from `wdio-ios.conf.ts`
-- adjust the `BUILD_DIR` (Find instructions in `wdio-ios.conf.ts` )
-- run `yarn prepare:native:start`
-- run this command to start the tests
-
-```
-BUILD_DIR='<your build dir>'
-yarn test:native:ios`
-```
+1. Download Appium Inspector from the releases
+2. Start an Appium server by running `appium` in command your line. Note the URLs your command line prints for
+   accessing the server.
+3. Fill one of those URLs into the host field. If you want to get to a specific route, fill in the path as well.
+4. Fill in keys and values of desired capabilities: deviceName, platformVersion, automationName, platformName. You
+   can find examples of those in the two files named `wdio.conf.ts` or `wdio-ios.conf.ts`.
+5. Click on "Start Session".
 
 ### Running tests on browserstack
 
@@ -68,7 +55,7 @@ curl -u "user:key" \
 -F "data={\"custom_id\": \"MyApp\"}"
 ```
 
-From now on the upload will be called `MyApp`. By re-uploading you are overriding the file.
+From now on the upload will be called `MyApp`. By re-uploading you are overwriting the file.
 
 #### Running the tests
 
@@ -87,6 +74,24 @@ with this you can run jest with `--maxWorkers=15`.
 
 - [BrowserStack API](https://www.browserstack.com/app-automate/rest-api)
 
+## Troubleshooting
+
+### Missing env variable ANDROID_HOME
+
+If you get complaints about missing env variable ANDROID_HOME, add it to the shell environment. In zshell, you to this
+via `ANDROID_HOME=~/Library/Android/sdk; export ANDROID_HOME` but your terminal might differ.
+
+### Lots of timeouts
+
+If you get lots of timeouts, start the app manually once on the emulator you want to use.
+
+### Can't open Appium Inspector because Apple can't check for malicious software
+
+If you get a nasty-looking error when trying to open Appium Inspector on a Mac that says that Apple can't check it
+for malicious software and to contact the developer, try opening it by going to its location in Finder, right-clicking
+it > Open, you now get that error again. Click the error away and right-click again, then Open, you should now have a
+different warning that lets you open the app.
+
 # Webdriver
 
 The API spec of wd can be found [here](https://github.com/admc/wd/blob/master/doc/api.md) and general