Getting Started

Follow these steps to get your first test running with emulator.wtf.

API token

If you’re using the token in CI then we recommend using any sort of secrets functionality you have in your CI and naming the variable EW_API_TOKEN - most of our integrations will pick up the token automatically from the EW_API_TOKEN environment variable.

Install `ew-cli`

Download the ew-cli shell script and place it somewhere, a good spot is the $HOME/bin folder:

mkdir -p $HOME/bin && \
  curl https://maven.emulator.wtf/releases/ew-cli -o $HOME/bin/ew-cli && \
  chmod a+x $HOME/bin/ew-cli

Ensure that $HOME/bin is on your PATH variable, that way your shell will know where to find ew-cli:

export PATH="$PATH:$HOME/bin"

Try whether the binary and API token works by listing available device models:

ew-cli --models --token "AQAA..."

Expected output ↕

$ ew-cli --models --token "AQAA..."

Available emulator models and respective versions in emulator.wtf:

╔════════════════╤═══════════════════╤═══════════════════════════════════════════════════╗
║ Model          │ Versions          │ Name                                              ║
╠════════════════╪═══════════════════╪═══════════════════════════════════════════════════╣
║ Pixel2         │ 23,24,27,29,30,31 │ Pixel 2                                           ║
╟────────────────┼───────────────────┼───────────────────────────────────────────────────╢
║ Pixel2Atd      │ 30,31             │ Pixel 2 (Automated test device)                   ║
╟────────────────┼───────────────────┼───────────────────────────────────────────────────╢
║ Tablet10       │ 23,24,27,29,30,31 │ Mid-resolution 10" tablet                         ║
╟────────────────┼───────────────────┼───────────────────────────────────────────────────╢
║ Tablet10Atd    │ 30,31             │ Mid-resolution 10" tablet (Automated test device) ║
╟────────────────┼───────────────────┼───────────────────────────────────────────────────╢
║ NexusLowRes    │ 23,24,27,29,30,31 │ Low-resolution MDPI phone                         ║
╟────────────────┼───────────────────┼───────────────────────────────────────────────────╢
║ NexusLowResAtd │ 30,31             │ Low-resolution MDPI phone (Automated test device) ║
╚════════════════╧═══════════════════╧═══════════════════════════════════════════════════╝


See something that's missing? Drop an email to hello@emulator.wtf and let us know!

Build app and test APKs

Before you can test your app you’ll need two apk files - one for the app under test and one for the tests themselves. Most commonly debug variants are used. If the main app is under the app/ subproject then you can use the following to build both the app and test apk:

./gradlew :app:assembleDebug :app:assembleDebugAndroidTest

Note down the relative paths of the test apk and the app apk, you’ll need them for running the tests. For our example with the app project and debug build they are at the following paths:

app/build/outputs/apk/debug/app-debug.apk (app)
app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk (test)

Run tests with `ew-cli`

You’re now ready to run tests! Try the following command (adjusting for your API token & APK locations where needed):

ew-cli --token "AQAA..." \
  --app app/build/outputs/apk/debug/app-debug.apk \
  --test app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk

Expected output ↕

$ ew-cli --token "AQAA..." \
  --app app/build/outputs/apk/debug/app-debug.apk \
  --test app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk

20:17:47.862 INFO Creating run
20:17:48.357 INFO Created run (uuid=7678663f-91ce-4076-b8e7-f5074b3e61fd)
20:17:48.357 INFO Uploading app apk...
20:17:48.700 INFO Uploaded app apk (62.11KB) in 0.34 seconds
20:17:48.701 INFO Uploading test apk...
20:17:52.333 INFO Uploaded test apk (2.14MB) in 3.63 seconds
20:17:52.399 INFO Triggered test run, waiting for tests to finish
20:17:56.825 INFO Gathering test output
20:17:56.825 INFO Downloaded a total of 0 outputs (in 0.00 seconds)
20:17:56.886 INFO Run results: https://results.emulator.wtf/?run=7678663f-91ce-4076-b8e7-f5074b3e61fd&key=itmORiFlqAyISjtF82rsUMjPWX49NJnUizAuSsX0
20:17:56.886 INFO All tests passed

If you see All tests passed at the end of the run you’re good to go! If not, don’t hesitate to reach out to us at support@emulator.wtf and we’ll help you figure out what’s going wrong.

Try out sharding

Sharding is a great way to speed up your tests by parallelizing them across multiple emulators.

Add --num-shards 3 to run your tests on 3 emulators in parallel:

ew-cli --num-shards 3 --token "AQAA..." \
  --app app/build/outputs/apk/debug/app-debug.apk \
  --test app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk

Next steps

You’re all set! Next up you can either start with picking an integration, see more ew-cli command-line options or read more about sharding.