[Mobile] Appium 2 Migration

README.md

@@ -8,26 +8,28 @@ This is the mobile version of [Gutenberg](https://github.com/WordPress/gutenberg
 
 For a developer experience closer to the one the project maintainers currently have, make sure you have the following tools installed:
 
-* git
-* [nvm](https://github.com/creationix/nvm)
-* Node.js and npm (use nvm to install them)
-* [Android Studio](https://developer.android.com/studio/) to be able to compile the Android version of the app
-* [Xcode](https://developer.apple.com/xcode/) to be able to compile the iOS app
-* CocoaPods (`sudo gem install cocoapods`) needed to fetch React and third-party dependencies.
-* [Carthage](https://github.com/Carthage/Carthage#installing-carthage) for Appium to be able run iOS UI tests
+-   git
+-   [nvm](https://github.com/creationix/nvm)
+-   Node.js and npm (use nvm to install them)
+-   [Android Studio](https://developer.android.com/studio/) to be able to compile the Android version of the app
+-   [Xcode](https://developer.apple.com/xcode/) to be able to compile the iOS app
+-   CocoaPods (`sudo gem install cocoapods`) needed to fetch React and third-party dependencies.
+-   [Carthage](https://github.com/Carthage/Carthage#installing-carthage) for Appium to be able run iOS UI tests
 
 Depending on your setup, there may be a few configurations needed in Android Studio and Xcode. Please refer to [React Native's documentation](https://reactnative.dev/docs/environment-setup) for the latest requirements for each development environment.
 
 Note that the OS platform used by the maintainers is macOS but the tools and setup should be usable in other platforms too.
 
 ### Clone the project
 
-* Clone the project and submodules:
+-   Clone the project and submodules:
+
 ```
 git clone --recurse-submodules https://github.com/wordpress-mobile/gutenberg-mobile.git
 ```
 
-* Or if you already have the project cloned, initialize and update the submodules:
+-   Or if you already have the project cloned, initialize and update the submodules:
+
 ```
 git submodule init
 git submodule update
@@ -120,42 +122,24 @@ Then, open `chrome://inspect` in Chrome to attach the debugger (look into the "R
 
 This project is set up to use [jest](https://facebook.github.io/jest/) for tests. You can configure whatever testing strategy you like, but jest works out of the box. Create test files in directories called `__tests__` or with the `.test.js` extension to have the files loaded by jest. See an example test [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/react-native-editor/src/test/api-fetch-setup.test.js). The [jest documentation](https://facebook.github.io/jest/docs/en/getting-started.html) is also a wonderful resource, as is the [React Native testing tutorial](https://facebook.github.io/jest/docs/en/tutorial-react-native.html).
 
-## UI Tests
-
-This repository uses Appium to run UI tests. The tests live in `__device-tests__` and are written using Appium to run tests against simulators and real devices. To run these you'll need to check off a few things:
-
-### Set up
-
-* When running the tests, you'll need to ensure the Metro bundler (`npm run start`) is not running.
-* [Appium CLI](https://appium.io/docs/en/about-appium/getting-started/) installed and available globally. We also recommend using [appium-doctor](https://github.com/appium/appium-doctor) to ensure all of Appium's dependencies are good to go. You don't have to worry about starting the server yourself, the tests handle starting the server on port 4723, just be sure that the port is free or feel free to change the port number in the test file.
-* For iOS a simulator should automatically launch but for Android you'll need to have an emulator fired up and running. The emulators must match the devices in Gutenberg's [caps.js](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/__device-tests__/helpers/caps.js) file.
-  * iOS: __iPhone 13, iOS 15.4__
-  * Android: __Google Pixel 3 XL GoogleAPI Emulator, Android 11__ _(Note: when creating the Pixel 3 XL emulator, ensure that "Enable Device Frame" is unchecked on the Verify Configuration screen.)_
-
-
-  <img width="512" alt="Device Tests" src="https://github.com/wordpress-mobile/gutenberg-mobile/assets/643285/19c223cc-96d6-4c5a-98f1-a463bb98e927">
-
-
+## End-to-End Tests
 
-### Running the tests
+This repository extends the end-to-end (E2E) tests found in the Gutenberg for Mobile Apps (GMA) [project repository](https://github.com/WordPress/gutenberg). The majority of E2E tests should reside in the GMA repository. However, experimental tests or non-core-related tests should be placed in the `gutenberg-mobile` repository.
 
-Then, to run the UI tests on iOS:
+Reviewing the GMA E2E test [documentation](https://github.com/WordPress/gutenberg/tree/trunk/packages/react-native-editor/__device-tests__#readme) is the best approach for understanding the test environment and how to set up your computer to run tests. Much of the information and approaches outlined there also apply to the tests found in this repository. The only difference being that this repository includes its own matching npm scripts to run the test, e.g. `npm run test:e2e:ios:local`.
 
-`npm run test:e2e:ios:local`
+After reviewing the GMA E2E test documentation, the following examples showcase running the E2E tests found in this repository using the repositories scripts.
 
-and for Android:
+```shell
+# Setup the E2E environment
+npm run core test:e2e:setup
 
-`npm run test:e2e:android:local`
+# Run a single test file on iOS
+npm run test:e2e:ios:local -- -- [email protected]
 
-**Note:** Make sure you've run the above commands at least once, so the demo app binaries are built before running individual tests below.
-
-To run a single test instead of the entire suite, use `npm run device-tests:local`. Here's an example that runs only `gutenberg-editor-paragraph.test`:
-
-`TEST_RN_PLATFORM=ios npm run device-tests:local gutenberg-editor-paragraph.test`
-
-Note: You might experience problems that seem to be related to the tests starting the Appium server, e.g. errors that say `Connection Refused`, `Connection Reset` or `The requested environment is not available`. If so, you can manually start the Appium server via `npm run native appium:start`, and (optionally) comment out related code in the `beforeAll` and `afterAll` block.
-
-For a more detailed outline of the UI tests and how to get started writing one, please visit the [UI Test documentation](https://github.com/WordPress/gutenberg/blob/HEAD/packages/react-native-editor/__device-tests__/README.md) and our [contributing guide](https://github.com/WordPress/gutenberg/blob/HEAD/packages/react-native-editor/__device-tests__/CONTRIBUTING.md).
+# Enable watch mode on Android
+npm run test:e2e:android:local -- --watch
+```
 
 ## Static analysis and code style
 
@@ -172,13 +156,15 @@ You might want to use Visual Studio Code as an editor. The project includes the
 ## Internationalization (i18n)
 
 The support for i18n in the project is provided by three main areas for the different plugins included in Gutenberg Mobile:
+
 1. Translations files download
 2. Locale setup
 3. Localization strings file generation
 
 ### Main areas
 
 #### Translation files download
+
 A translation file is basically a JSON object that contains key-value items with the translation for each individual string. This content is fetched from [translate.wordpress.org](https://translate.wordpress.org/) that holds translations for WordPress and a list of different plugins like Gutenberg.
 
 These files are cached under the folder located at `src/i18n-cache/<PLUGIN_NAME>`, and can be optimized depending on the command used for fetching them. Additionally, an index file (`index.js`) is generated that acts as the entry point to import and get translations for each plugin.
@@ -190,7 +176,9 @@ By default, when installing dependencies, un-optimized translations will be down
 For the optimized versions, similarly, we have the `i18n:update` NPM command that can be used for this purpose. This command is also automatically run when generating the bundle via `npm run bundle`, this way we guarantee that a new version of the bundle contains up-to-date translations. On the other hand, it's important to mention that this command also generates the localization strings files described in a later section.
 
 #### Locale setup
+
 This is done upon the [editor initialization](https://github.com/wordpress-mobile/gutenberg-mobile/blob/develop/src/index.js), an array containing the following items related to each plugin is passed:
+
 ```
 [
   {
@@ -202,24 +190,29 @@ This is done upon the [editor initialization](https://github.com/wordpress-mobil
 ```
 
 #### Localization strings file generation
+
 Some of the strings referenced in the editor are only used in the native version, these strings are not included in the translations fetched from [translate.wordpress.org](https://translate.wordpress.org/), however, they are part of the WordPress app translations. For this reason, we generate the following localization strings files, which contain these types of string, for each platform, and that are bundled and incorporated in the translation pipeline of the app.
-- [`bundle/android/strings.xml`](https://github.com/wordpress-mobile/gutenberg-mobile/blob/develop/bundle/android/strings.xml)
-- [`bundle/ios/GutenbergNativeTranslations.swift`](https://github.com/wordpress-mobile/gutenberg-mobile/blob/develop/bundle/ios/GutenbergNativeTranslations.swift)
+
+-   [`bundle/android/strings.xml`](https://github.com/wordpress-mobile/gutenberg-mobile/blob/develop/bundle/android/strings.xml)
+-   [`bundle/ios/GutenbergNativeTranslations.swift`](https://github.com/wordpress-mobile/gutenberg-mobile/blob/develop/bundle/ios/GutenbergNativeTranslations.swift)
 
 These files are generated via the `i18n:update` NPM command, and like translations, they are also produced when generating the bundle.
 
 ### NPM commands
-- `npm run i18n:update`: Downloads optimized translations and generate localization strings files for all plugins. **NOTE:** This command is attached to `bundle` NPM command via `prebundle:js`, so it will be automatically executed when generating a bundle.
-- `npm run i18n:check-cache`: Downloads un-optimized translations for plugins that don't have a cache folder. **NOTE:** This command is attached to dependency installation via `postinstall`, so it will be automatically executed when installing dependencies.
+
+-   `npm run i18n:update`: Downloads optimized translations and generate localization strings files for all plugins. **NOTE:** This command is attached to `bundle` NPM command via `prebundle:js`, so it will be automatically executed when generating a bundle.
+-   `npm run i18n:check-cache`: Downloads un-optimized translations for plugins that don't have a cache folder. **NOTE:** This command is attached to dependency installation via `postinstall`, so it will be automatically executed when installing dependencies.
 
 ### How to add a new plugin
+
 1. Identify the i18n domain, which usually matches the plugin's name (i.e. `jetpack`).
 2. Identify the GlotPress project slug (i.e. `wp-plugins/jetpack` for URL `https://translate.wordpress.org/projects/wp-plugins/jetpack/`)
 3. Identify the path to the plugin's source code (i.e. `./jetpack/projects/plugins/jetpack/extensions`).
 4. Append the plugin's name, GlotPress project slug, and plugin's source code to the arguments of `i18n:update` and `i18n:update:test` NPM commands.
 5. Append the plugin's name and GlotPress project slug to the arguments of `i18n:check-cache` NPM command.
 
-*Example:*
+_Example:_
+
 ```
 "scripts": {
   ...
@@ -231,7 +224,8 @@ These files are generated via the `i18n:update` NPM command, and like translatio
 ```
 
 6. Add the i18n domain of the plugin and the callback for getting translation to the [editor initialization](https://github.com/wordpress-mobile/gutenberg-mobile/blob/develop/src/index.js).
-*Example:*
+   _Example:_
+
 ```
 import { getTranslation as getJetpackTranslation } from './i18n-translations/jetpack';
 ...
@@ -248,20 +242,22 @@ const pluginTranslations = [
 7. (Optional) In some cases, it's needed to build the source code in order to extract the used strings. Consider adding a command in [`bin/i18n-update.sh`](https://github.com/wordpress-mobile/gutenberg-mobile/blob/develop/bin/i18n-update.sh) file for this purpose (e.g. `./bin/run-jetpack-command.sh "-C projects/packages/videopress build"` to build VideoPress package)
 
 ### Caveats
-- Strings that are only used in the native version, and reference a [context](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#disambiguation-by-context), won't be included in the localization strings files hence, they won't be translated. This is a limitation in the format of the localization strings files.
-- Localization strings files don’t support domains, so the strings extracted from plugins that are only used in the native version, will be unified in the same file, which might involve string conflicts.
+
+-   Strings that are only used in the native version, and reference a [context](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#disambiguation-by-context), won't be included in the localization strings files hence, they won't be translated. This is a limitation in the format of the localization strings files.
+-   Localization strings files don’t support domains, so the strings extracted from plugins that are only used in the native version, will be unified in the same file, which might involve string conflicts.
 
 ### Troubleshooting
 
 #### A string is missing the translation
+
 This can be produced by several causes, check the following steps in order to identify the source:
-- Verify that the string uses the `__` i18n function or similar ([reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/i18n/README.md)).
-- Check for warnings in the output when running `i18n:update` NPM command, especially the following ones:
-  - Parsing files issues (i.e. `Debug (make-pot): Could not parse file <FILE>`)
-  - Missing strings in translation files (i.e. `WARNING: The following strings are missing from translations:`)
-- If the string is only used in the native version, the translation won't be available until the a new version of the app is cut and its translations are requested. Check if the string is included in the localization strings files, if not, verify the output of `i18n:update` NPM command and look for warnings that reference the string.
+
+-   Verify that the string uses the `__` i18n function or similar ([reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/i18n/README.md)).
+-   Check for warnings in the output when running `i18n:update` NPM command, especially the following ones:
+    -   Parsing files issues (i.e. `Debug (make-pot): Could not parse file <FILE>`)
+    -   Missing strings in translation files (i.e. `WARNING: The following strings are missing from translations:`)
+-   If the string is only used in the native version, the translation won't be available until the a new version of the app is cut and its translations are requested. Check if the string is included in the localization strings files, if not, verify the output of `i18n:update` NPM command and look for warnings that reference the string.
 
 ## License
 
 Gutenberg Mobile is an Open Source project covered by the [GNU General Public License version 2](LICENSE).
-