chore: appium webdriver setup #926

cimigree · 2025-01-29T21:28:54Z

closes #908

Description of Choices Made

Driver:

Because we decided to use Browserstack and Appium, that lead naturally to the use of UIAutomator. That is what Browserstack uses with Appium. BrowserStack abstracts the driver implementation, and they implement UiAutomator with Appium automatically. In addition, UIAutomator can theoretically be used with our web app. Espresso is available through Browserstack, but it is its own entity, not the standard Appium implementation. We may want to test system-level features like GPS and Wi-Fi, which Espresso doesn’t handle well. I decided to go with the most supported, most fleshed out driver available on Browserstack.

Client:

Basically the same thing. I chose to use Webdriver IO because it is well-documented and actively maintained.
Great for multi-platform testing (mobile, web, and Electron). It has built-in integrations for BrowserStack and easier configuration for parallel test runs. It also has a large plugin ecosystem.

Test Framework:

I chose Mocha, a widely-used, flexible, and lightweight JavaScript test framework. It allows you to use any assertion library (e.g., Chai, Assert). It supports hooks like before, after, beforeEach, afterEach. It has simple syntax: describe and it. caveat... I am not sold on Mocha. Jasmine might be better and I am open to reconsidering.

Test Reporter:

I chose spec reporter. It provides quick and easy viewing of test results during local development and debugging with simple, human-readable output. It's pretty basic, imo ideal for getting started and debugging minimal test suites.

Testing

I wrote a simple test to check the first two screens and that you can get from the first screen to the second. It was not easy to figure out how to select text to test. I got my testing language from Browserstack's guidelines. But the same guidelines are available via WebdriverIO. It would be much much easier to look for text if we used accessibilityLabels on the text... Something to consider for the future?

Configuration file

I am really including the almost minimum that one can include in the configuration file. A lot more can be done with that, like testing on multiple devices, increasing number of instances, etc. Here's how the file can be adjusted from the docs: https://webdriver.io/docs/configurationfile/

Workflow

I built this based on previous work by Erik and Gregor -- Erik for signing into Expo and building using EAS. Gregor for building an apk. That increase to JavaHeapSpace (because I ran into out of memory errors when building) and work with caching and freeing up disc space (this makes the building of the apk at least 50% faster) comes from him. I wanted the test to not only fail in Github if the E2E tests failed, but I wanted an easy way for the PR maker to see why, since we only get 2 logins to Browserstack with our free account. In order to get that to work, each time someone makes a push, there is a file included summarizing the test results (this is where spec reporter comes in handy.

How to test

Push a new commit or open a PR to feat/appium-webdriver-setup.
GitHub Actions will automatically:
Build the APK using EAS.
Upload the APK to BrowserStack.
Run WebdriverIO tests on BrowserStack.
You should see the results as an artifact on the Workflow. LMK if you want my login to see how things look on Browserstack. With it I think you go to this link

To test locally

Update the capabilities in wdio.conf.ts.

capabilities: [
  {
    platformName: 'android',
    'appium:platformVersion': '12.0',
    'appium:deviceName': 'Samsung Galaxy S22 Ultra', // whatever your local device is
    'appium:automationName': 'UIAutomator2',
    'appium:app': '/path/to/local/apk/app-debug.apk', // path to your apk
    'appium:autoGrantPermissions': true,
  },
],

Start an Android emulator or connect a real device.
Run Appium in a separate terminal:
npx appium
Execute WebdriverIO:
npx wdio run wdio.conf.ts
or
npm run wdio
You will have to install appium locally to do this.

Next Steps:

Add multiple devices
Consider Jasmine instead of Mocha?
Improve element selection (add accessibilityLabels?)
Expand tests to cover more screens & flows

…ur app. Adjusting config for our needs.

… gitignore.

…vironment variable.

… it will pass.

awana-lockfile-bot · 2025-02-03T14:00:21Z

`package-lock.json` changes

Summary

Status	Count
	197
	16

Click to toggle table visibility

Name	Previous	Current
`@browserstack/ai-sdk-node`	-	1.5.17
`@colors/colors`	-	1.6.0
`@esbuild/aix-ppc64`	-	0.23.1
`@esbuild/android-arm`	-	0.23.1
`@esbuild/android-arm64`	-	0.23.1
`@esbuild/android-x64`	-	0.23.1
`@esbuild/darwin-arm64`	-	0.23.1
`@esbuild/darwin-x64`	-	0.23.1
`@esbuild/freebsd-arm64`	-	0.23.1
`@esbuild/freebsd-x64`	-	0.23.1
`@esbuild/linux-arm`	-	0.23.1
`@esbuild/linux-arm64`	-	0.23.1
`@esbuild/linux-ia32`	-	0.23.1
`@esbuild/linux-loong64`	-	0.23.1
`@esbuild/linux-mips64el`	-	0.23.1
`@esbuild/linux-ppc64`	-	0.23.1
`@esbuild/linux-riscv64`	-	0.23.1
`@esbuild/linux-s390x`	-	0.23.1
`@esbuild/linux-x64`	-	0.23.1
`@esbuild/netbsd-x64`	-	0.23.1
`@esbuild/openbsd-arm64`	-	0.23.1
`@esbuild/openbsd-x64`	-	0.23.1
`@esbuild/sunos-x64`	-	0.23.1
`@esbuild/win32-arm64`	-	0.23.1
`@esbuild/win32-ia32`	-	0.23.1
`@esbuild/win32-x64`	-	0.23.1
`@inquirer/checkbox`	-	3.0.1
`@inquirer/confirm`	-	4.0.1
`@inquirer/core`	-	9.2.1
`@inquirer/editor`	-	3.0.1
`@inquirer/expand`	-	3.0.1
`@inquirer/figures`	-	1.0.9
`@inquirer/input`	-	3.0.1
`@inquirer/number`	-	2.0.1
`@inquirer/password`	-	3.0.1
`@inquirer/prompts`	-	6.0.1
`@inquirer/rawlist`	-	3.0.1
`@inquirer/search`	-	2.0.1
`@inquirer/select`	-	3.0.1
`@inquirer/type`	-	2.0.0
`@open-draft/until`	-	1.0.3
`@percy/appium-app`	-	2.0.9
`@percy/sdk-utils`	-	1.30.6
`@percy/selenium-webdriver`	-	2.2.2
`@promptbook/utils`	-	0.69.5
`@puppeteer/browsers`	-	2.7.0
`@sec-ant/readable-stream`	-	0.4.1
`@tootallnate/quickjs-emscripten`	-	0.23.0
`@types/gitconfiglocal`	-	2.0.3
`@types/json-schema`	7.0.11	7.0.15
`@types/lodash`	4.14.199	4.17.14
`@types/mocha`	-	10.0.10
`@types/mute-stream`	-	0.0.4
`@types/sinonjs__fake-timers`	-	8.1.5
`@types/triple-beam`	-	1.3.5
`@types/which`	-	2.0.2
`@types/wrap-ansi`	-	3.0.0
`@types/ws`	-	8.5.14
`@types/yauzl`	-	2.10.3
`@vitest/pretty-format`	-	2.1.8
`@vitest/snapshot`	-	2.1.8
`@wdio/browserstack-service`	-	9.7.1
`@wdio/cli`	-	9.7.2
`@wdio/config`	-	9.7.2
`@wdio/dot-reporter`	-	9.6.3
`@wdio/globals`	-	9.7.1
`@wdio/local-runner`	-	9.7.2
`@wdio/logger`	-	9.4.4
`@wdio/mocha-framework`	-	9.6.4
`@wdio/protocols`	-	9.7.0
`@wdio/repl`	-	9.4.4
`@wdio/reporter`	-	9.6.3
`@wdio/runner`	-	9.7.2
`@wdio/spec-reporter`	-	9.6.3
`@wdio/types`	-	9.6.3
`@wdio/utils`	-	9.7.2
`@zip.js/zip.js`	-	2.7.54
`ansi-colors`	-	4.1.3
`aria-query`	-	5.3.2
`async-exit-hook`	-	2.0.1
`axios`	-	1.7.9
`bare-fs`	-	4.0.1
`bare-os`	-	3.4.0
`bare-path`	-	3.0.0
`bare-stream`	-	2.6.4
`basic-ftp`	-	5.0.5
`binary-extensions`	-	2.3.0
`browser-stdout`	-	1.3.1
`browserstack-local`	-	1.5.6
`call-bind-apply-helpers`	-	1.0.1
`call-bound`	-	1.0.3
`cheerio-select`	-	2.1.0
`cheerio`	-	1.0.0
`chokidar`	-	4.0.3
`create-require`	-	1.1.1
`css-shorthand-properties`	-	1.1.2
`css-value`	-	0.0.1
`csv-writer`	-	1.6.0
`data-uri-to-buffer`	-	6.0.2
`deepmerge-ts`	-	7.1.4
`degenerator`	-	5.0.1
`detect-libc`	2.0.2	2.0.3
`diff`	-	7.0.0
`dunder-proto`	-	1.0.1
`duplexer`	-	0.1.2
`easy-table`	-	1.2.0
`edge-paths`	-	3.0.5
`edgedriver`	-	6.1.1
`ejs`	-	3.1.10
`encoding-sniffer`	-	0.2.0
`es-define-property`	1.0.0	1.0.1
`esbuild`	-	0.23.1
`event-stream`	-	3.3.4
`expect-webdriverio`	-	5.0.5
`extract-zip`	-	2.0.1
`fast-xml-parser`	-	4.5.1
`fd-slicer`	-	1.1.0
`fecha`	-	4.2.3
`fetch-blob`	-	3.2.0
`filelist`	-	1.0.4
`flat`	-	5.0.2
`follow-redirects`	-	1.15.9
`formdata-node`	-	5.0.1
`formdata-polyfill`	-	4.0.10
`from`	-	0.1.7
`fsevents`	2.3.2	2.3.3
`geckodriver`	-	5.0.0
`get-intrinsic`	1.2.4	1.2.7
`get-proto`	-	1.0.1
`get-tsconfig`	-	4.10.0
`get-uri`	-	6.0.4
`git-repo-info`	-	2.1.1
`gitconfiglocal`	-	2.1.0
`gopd`	1.0.1	1.2.0
`grapheme-splitter`	-	1.0.4
`has-symbols`	1.0.3	1.1.0
`he`	-	1.2.0
`headers-utils`	-	1.2.5
`htmlfy`	-	0.6.0
`htmlparser2`	-	9.1.0
`immediate`	-	3.0.6
`import-meta-resolve`	-	4.1.0
`is-binary-path`	-	2.1.0
`is-running`	-	2.1.0
`jake`	-	10.9.2
`jszip`	-	3.10.1
`lie`	-	3.3.0
`locate-app`	-	2.5.0
`lodash.clonedeep`	-	4.5.0
`lodash.flattendeep`	-	4.4.0
`lodash.pickby`	-	4.6.0
`lodash.union`	-	4.6.0
`lodash.zip`	-	4.2.0
`logform`	-	2.7.0
`loglevel-plugin-prefix`	-	0.8.4
`loglevel`	-	1.9.2
`magic-string`	-	0.30.17
`make-error`	-	1.3.6
`map-stream`	-	0.1.0
`math-intrinsics`	-	1.1.0
`mocha`	-	10.8.2
`netmask`	-	2.0.2
`node-domexception`	-	1.0.0
`node-request-interceptor`	-	0.6.3
`object-inspect`	1.13.1	1.13.3
`pac-proxy-agent`	-	7.1.0
`pac-resolver`	-	7.0.1
`pako`	-	1.0.11
`parse5-htmlparser2-tree-adapter`	-	7.1.0
`parse5-parser-stream`	-	7.1.2
`pathe`	-	1.1.2
`pause-stream`	-	0.0.11
`pend`	-	1.2.0
`plist`	3.0.6	3.1.0
`proxy-agent`	-	6.5.0
`ps-tree`	-	1.2.0
`query-selector-shadow-dom`	-	1.0.1
`recursive-readdir`	-	2.2.3
`resolve-pkg-maps`	-	1.0.0
`resq`	-	1.11.0
`rgb2hex`	-	0.2.5
`safaridriver`	-	1.0.0
`send`	0.18.0	0.19.0
`serve-static`	1.15.0	1.16.2
`shell-quote`	1.7.4	1.8.2
`side-channel-list`	-	1.0.0
`side-channel-map`	-	1.0.1
`side-channel-weakmap`	-	1.0.2
`socks-proxy-agent`	8.0.2	8.0.5
`socks`	2.8.1	2.8.3
`spacetrim`	-	0.11.59
`stream-combiner`	-	0.0.4
`streamx`	2.19.0	2.21.1
`strict-event-emitter`	-	0.1.0
`strnum`	-	1.0.5
`temp-fs`	-	0.9.9
`tinyrainbow`	-	1.2.0
`triple-beam`	-	1.4.1
`ts-node`	-	9.1.1
`tsx`	-	4.19.2
`unbzip2-stream`	-	1.4.3
`unicorn-magic`	-	0.3.0
`urlpattern-polyfill`	-	10.0.0
`userhome`	-	1.0.1
`wait-port`	-	1.1.0
`webdriver`	-	9.7.2
`webdriverio`	-	9.7.2
`winston-transport`	-	4.9.0
`workerpool`	-	6.5.1
`yargs-unparser`	-	2.0.0
`yauzl`	-	3.2.0
`yn`	-	3.1.1
`yoctocolors-cjs`	-	2.1.2

ErikSin

This is not a review per-se. More just questions and comments. I think it would be good for @gmaclennan to take a look at this?

ErikSin · 2025-02-04T16:38:21Z

expo-config-plugins/increaseJavaMemory.js

Can we create a readme in the config plugins folder to document what the increase in memory is for?

I think I need Gregor's help with that. I know that the build fails and what the error message is, but I don't exactly know why.

ha I'm not sure either. Maybe just a doc to say "increase java memory to make builds work on CI"!

package.json

ErikSin · 2025-02-04T16:42:51Z

tests/e2e/test.e2e.ts

+  it('should launch the app, grant permissions, and navigate to the next screen', async () => {
+    await browser.pause(15000);
+    const description = await $(
+      'android=new UiSelector().text("Map your world, together")',


should we write reusable functions for these "strings"? Something like

function selectText(textToFind:string){ return `android=new UiSelector().text("${textToFind}")` }

Will do that in next PR when adding more tests. Thanks for suggestion but trying to keep things as simple as possible for this iteration.

tests/e2e/tsconfig.json

wdio.conf.ts

ErikSin · 2025-02-04T20:07:54Z

wdio.conf.ts

+      platformName: 'android',
+      'appium:platformVersion': '12.0',
+      'appium:deviceName': 'Samsung Galaxy S22 Ultra',
+      'appium:automationName': 'UIAutomator2',
+      'appium:app': process.env.BROWSERSTACK_APP_URL,
+      'appium:autoGrantPermissions': true,
+      'bstack:options': {
+        projectName: 'CoMapeo',
+        buildName: 'CoMapeo Android Build',
+        sessionName: 'Launch App and Grant Permissions',
+        appiumVersion: '2.12.1',
+        debug: true,
+        networkLogs: true,
+      },


where are you getting this syntax from?

A combination of from here:
https://appium.io/docs/en/2.0/guides/caps/ (specifies the appium prefix for all capabilities)
And here:
https://www.browserstack.com/docs/app-automate/capabilities
click legacy, node.js
Maybe you found syntax for Appium 1? This is for Appium 2+...

gmaclennan

Great work on this Cindy, I can see that a lot has gone into this, and it's amazing you were able to get all the moving pieces to line up and make this work. The overview about why choices were made is helpful too and the choices make sense to me based on what we know at this time. I think this is ok to merge and start using, and we can evolve and learn from it as we add more tests.

cimigree · 2025-02-11T05:35:14Z

@ErikSin, before I merge this, are you good with running it

on:
  pull_request:
    branches:
      - main
      - develop
    types: [opened, synchronize, reopened, ready_for_review]

(for the workflow yml file?)

ErikSin · 2025-02-11T20:04:47Z

on:
pull_request:
branches:
- main
- develop
types: [opened, synchronize, reopened, ready_for_review]

I think it is good to merge. Perhaps in the future, if it takes a long time and is resource intensive, we could remove syncronize and have it only run on review_requested. But we can talk about it after it is built

cimigree added 19 commits January 27, 2025 17:12

Initial setup for appium webdriver app for browserstack.

858555a

Adding more packages. Updating test location and content to reflect o…

f218376

…ur app. Adjusting config for our needs.

Got tests to run. Starting to work on getting tests to pass. Updating…

f010371

… gitignore.

Merges with develop

f6875da

Working test using UI selectors. Setting the app url via a dynamic en…

61864b2

…vironment variable.

Adds workflow file for building apk and testing on browserstack

a580e8d

Installs the eas cli.

10937e5

Trying to log in to eas

c15bbfc

Other way to install eas

915adfe

Trying to send results back from browserstack.

e295a9c

Deliberate failure

4b582b3

Fixes test reporting hopefully.

ec7978e

Using spec reporter only.

c08dd55

Ran out of disk space

e92e1d0

Fixes configuration for reporter

cd9150b

Adds packages back.

6f0fa7f

Trying again to print logs

3fddcbe

Job fails through pipefile. Spec reports always uploaded.

5fe457b

Adds a number for the file for a non pull request. Fixes test so that…

6215303

… it will pass.

cimigree changed the title ~~Feat/appium webdriver setup~~ chore: appium webdriver setup Feb 3, 2025

cimigree added 2 commits February 3, 2025 08:49

Makes package exact

3407c3a

Merges with develop

f086829

cimigree added 2 commits February 3, 2025 09:05

Fixes package lock.

68712f7

Changes when workflow is run

d7cc7bf

cimigree marked this pull request as ready for review February 3, 2025 21:00

cimigree requested a review from ErikSin February 3, 2025 21:00

Changes wording to be more accurate.

dc0f8fa

ErikSin reviewed Feb 4, 2025

View reviewed changes

ErikSin requested a review from gmaclennan February 4, 2025 20:16

cimigree added 2 commits February 10, 2025 10:49

Updates based on PR comments.

982e8a8

Handles renaming of config file.

268a824

gmaclennan approved these changes Feb 10, 2025

View reviewed changes

cimigree added 2 commits February 10, 2025 18:31

Changes to what webdriver IO expects.

06984da

Adds readme for expo config plugin

fc11b73

cimigree requested a review from ErikSin February 11, 2025 05:24

Fixes the workflow file as to when the test is done.

31206dc

cimigree merged commit 7946423 into develop Feb 11, 2025
7 checks passed

cimigree deleted the feat/appium-webdriver-setup branch February 11, 2025 20:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: appium webdriver setup #926

chore: appium webdriver setup #926

cimigree commented Jan 29, 2025 •

edited

Loading

awana-lockfile-bot bot commented Feb 3, 2025 •

edited

Loading

ErikSin left a comment

ErikSin Feb 4, 2025

cimigree Feb 10, 2025

gmaclennan Feb 10, 2025

cimigree Feb 11, 2025

ErikSin Feb 4, 2025

cimigree Feb 10, 2025

ErikSin Feb 4, 2025

cimigree Feb 10, 2025

gmaclennan left a comment

cimigree commented Feb 11, 2025

ErikSin commented Feb 11, 2025

chore: appium webdriver setup #926

chore: appium webdriver setup #926

Conversation

cimigree commented Jan 29, 2025 • edited Loading

Description of Choices Made

Driver:

Client:

Test Framework:

Test Reporter:

Testing

Configuration file

Workflow

How to test

Next Steps:

awana-lockfile-bot bot commented Feb 3, 2025 • edited Loading

package-lock.json changes

Summary

ErikSin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gmaclennan left a comment

Choose a reason for hiding this comment

cimigree commented Feb 11, 2025

ErikSin commented Feb 11, 2025

cimigree commented Jan 29, 2025 •

edited

Loading

awana-lockfile-bot bot commented Feb 3, 2025 •

edited

Loading

`package-lock.json` changes