Skip to content

Commit

Permalink
Fix old references and dead links in react-native-editor documentation (
Browse files Browse the repository at this point in the history
  • Loading branch information
derekblank authored Apr 3, 2023
1 parent ac2d3fe commit a7e87a2
Show file tree
Hide file tree
Showing 3 changed files with 9 additions and 9 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Welcome! This is the Getting Started guide for the native mobile port of the blo
For a developer experience closer to the one the project maintainers current have, make sure you have the following tools installed:

- git
- [nvm](https://github.com/creationix/nvm)
- [nvm](https://github.com/nvm-sh/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
Expand Down Expand Up @@ -111,7 +111,7 @@ This project is set up to use [jest](https://facebook.github.io/jest/) for 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:

- When running the tests, you'll need to ensure the Metro bundler (`npm run native start`) is not running.
- [Appium CLI](https://github.com/appium/appium/blob/HEAD/docs/en/about-appium/getting-started.md) 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.
- [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 _with at least platform version 8.0_ fired up and running.

Then, to run the UI tests on iOS:
Expand All @@ -132,7 +132,7 @@ To run a single test instead of the entire suite, use `npm run native device-tes
npm run native test:e2e:android:local gutenberg-editor-paragraph.test.js
```

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`. For now, you can manually start the Appium server via [appium desktop](https://github.com/appium/appium-desktop) or the CLI, then change the port number in the tests while (optionally) commenting out related code in the `beforeAll` and `afterAll` block.
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`. For now, you can manually start the Appium server via [Appium Inspector](https://github.com/appium/appium-inspector/) or the CLI, then change the port number in the tests while (optionally) commenting 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](/packages/react-native-editor/__device-tests__/README.md) and our [contributing guide](/packages/react-native-editor/__device-tests__/CONTRIBUTING.md).

Expand Down
10 changes: 5 additions & 5 deletions packages/react-native-editor/__device-tests__/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,24 +21,24 @@ That first parameter in the block above is where you'd put a short description o

### Second, figure out how to find the elements

- The UI tests rely on locator strategies to identify elements... There's a number of locator strategies available to use and [this blog post](https://saucelabs.com/blog/advanced-locator-strategies) describes in a little more detail what a few of these are and how to use them. You'll need to start thinking about what locator strategy you'll need to use to find the elements you need if it isn't already available.
- The UI tests rely on locator strategies to identify elements... There's a number of locator strategies available to use and [this blog post](https://saucelabs.com/resources/blog/advanced-locator-strategies) describes in a little more detail what a few of these are and how to use them. You'll need to start thinking about what locator strategy you'll need to use to find the elements you need if it isn't already available.
- The preferred strategy is the accessibility identifier and in a lot of cases this might not be possible and you'll have to resort to other less robust alternatives such as XPath.

There's a few tools you have available to figure out what you need.

For Android, you can fire up the app and then within Android Studio select `Tools -> Layout Inspector` which will then open up a `.li` file which you can then use to inspect various areas of the app, here's a [screenshot](https://d.pr/free/i/anU50R) of what that looks like.
For Android, you can fire up the app and then within Android Studio select `Tools -> Layout Inspector` which will then open up a `.li` file which you can then use to inspect various areas of the app.

For iOS, you can also fire up and use the accessibility inspector, which is an app that should come available on your OSX machine. From there you can choose the process running your simulator and inspect various areas of the app.

Alternative for both of these platforms and for an interface to simulate the commands I'd recommend [Appium Desktop](https://github.com/appium/appium-desktop/releases/tag/v1.12.1). A great tool for inspecting the view hierarchy and interacting with elements on screen as your test would. Here's a [screenshot](https://d.pr/free/i/GziQ5Q) of what that would look like.
Alternative for both of these platforms and for an interface to simulate the commands I'd recommend [Appium Inspector](https://github.com/appium/appium-inspector/releases). A great tool for inspecting the view hierarchy and interacting with elements on screen as your test would.

Using one or a combination of these tools will make it much easier to identify what locator strategy you're going to use or which elements need accessibility identifiers to ease the search process without affecting VoiceOver features.

### Finally, once you've figured out how you're going to find the elements

- You'll write any functions needed to interact with the page in the `EditorPage` page object and then call those interactions within the test. The code you'll need to write to actually do the finding will use a combination of

- Appium's spec http://appium.io/docs/en/about-appium/intro/ which you can find examples of a variety of functions under the commands tab
- Appium's spec https://appium.io/docs/en/about-appium/intro/ which you can find examples of a variety of functions under the commands tab
- WebDriver I/O Appium protocols https://webdriver.io/docs/api/appium.html which provides examples and descriptions of what those look like.

It takes some getting use to but looking at the existing code should be helpful in identifying common commands that it'd help to be familiar with.
It takes some getting used to but looking at the existing code should be helpful in identifying common commands that it'd help to be familiar with.
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ const setupDriver = async () => {
try {
appiumProcess = await AppiumLocal.start( localAppiumPort );
} catch ( err ) {
// Ignore error here, Appium is probably already running (Appium desktop has its own server for instance)
// Ignore error here, Appium is probably already running (Appium Inspector has its own server for instance)
// eslint-disable-next-line no-console
await console.log(
'Could not start Appium server',
Expand Down

1 comment on commit a7e87a2

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Flaky tests detected in a7e87a2.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4596218826
📝 Reported issues:

Please sign in to comment.