Running Espresso in CI with GitHub Actions
On this page
A suite that only runs when someone remembers to run it stops protecting anything within weeks. This chapter puts the Espresso Shop suite in a GitHub Actions workflow that builds both APKs on every pull request, runs them on a TestingBot device, fails the check when a test fails and keeps the JUnit report.
Two ways to run Espresso in CI#
| Emulator on the CI runner | Device cloud | |
|---|---|---|
| Setup | Install a system image, boot an emulator, wait for it, run Gradle | Build two APKs, call the CLI |
| Devices | One emulator per job, usually one Android version | Emulators and real devices, any version the cloud offers |
| Speed | The emulator boot is part of every job | No boot on the runner; runs queue for your account's parallel slots |
| Debugging | Logs from the runner | Video, logs and screenshots per run |
Running an emulator on the runner works and community actions exist for it, but it brings its own flakiness (slow boots, hardware acceleration that is not always available) and covers one device. Handing the APKs to a device cloud keeps the CI job simple and lets the same job cover real phones. This chapter takes that route.
The workflow#
Save as .github/workflows/espresso.yml in the repository:
name: Espresso
on:
push:
branches: [main]
pull_request:
jobs:
espresso:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
with:
distribution: temurin
java-version: 17
- uses: gradle/actions/setup-gradle@v6
- name: Build the app APK and the test APK
run: ./gradlew assembleDebug assembleDebugAndroidTest
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Run Espresso on TestingBot
env:
TB_KEY: ${{ secrets.TB_KEY }}
TB_SECRET: ${{ secrets.TB_SECRET }}
run: |
npx --yes @testingbot/cli@1.5.0 espresso \
app/build/outputs/apk/debug/app-debug.apk \
app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk \
--device "Pixel 8" --platform-version "14" \
--name "Espresso Shop" \
--build "espresso-shop-${{ github.run_number }}" \
--report junit --report-output-dir reports
- uses: actions/upload-artifact@v7
if: always()
with:
name: espresso-junit
path: reports/
Step by step:
-
setup-javawith 17 gives the Android Gradle Plugin the JDK it needs. GitHub's Ubuntu runners come with the Android SDK installed, so there is no separate SDK step for building APKs. -
setup-gradlecaches Gradle's downloads between runs, which saves minutes on every build. - One Gradle call builds both APKs, from the same commit, signed with the same debug key: the two rules from chapter 6.
-
The CLI step is the command from the last chapter, with the credentials coming from repository secrets. Add
TB_KEYandTB_SECRETunder the repository's Settings, Secrets and variables, Actions. The CLI reads those two variables, so no key appears in the workflow or the logs. -
--buildwith the run number groups each CI run's sessions into their own build in the TestingBot dashboard, so "which run broke on Tuesday" is one click. -
upload-artifactwithif: always()keeps the JUnit report even when the test step failed, which is exactly when you want it.
The workflow file passes actionlint. Its TestingBot step is the CLI command from chapter 7, which ran this course's APKs on a Pixel 9 and a Pixel 8 with the credentials in TB_KEY and TB_SECRET; the workflow itself was not run on GitHub for this course.
The test step fails, and the workflow run has no JUnit report attached. What is missing?
GitHub Actions skips later steps once a step fails, unless they opt in with a condition such as always(). The report was written; it was just never uploaded.
What a failing test does to the workflow#
The CLI waits for the run, prints the instrumentation output and exits with a non-zero code when any test failed. That fails the step, the job and the pull request check, with no extra scripting. Inside GitHub Actions, the CLI also adds a results table with links to each run to the job summary, annotates failed runs so they show on the pull request, and attaches the repository, branch, commit and pull request to the run in TestingBot, read from the CI environment. The Espresso documentation lists the variables and flags.
Two things can quietly turn a red run green, and both are worth searching your workflow for:
-
|| trueorcontinue-on-error: trueon the test step. Both discard the exit code. -
--json-file. With it, the CLI writes the results to a JSON file and exits 0 even when tests failed, leaving the decision to your pipeline. Use it only if a later step reads the file and fails the job itself.
Choosing devices for CI#
One device per pull request is usually right: fast feedback on the Android version most of your users run. Wider coverage belongs in a scheduled workflow (on: schedule) that runs nightly on more devices: an older Android version near your minSdk, a real Samsung phone with --real-device, a tablet with --tablet-only. Each run on one device takes one of your account's parallel slots, so a matrix of eight devices finishes fastest with eight free slots and queues otherwise. The Mobile App Testing course has a chapter on building a device matrix from your analytics.
Use the quieter options with care:
-
--retry 1re-runs a failed run once, and only the last attempt counts. It keeps a single infrastructure hiccup from blocking a merge, but it also hides genuinely flaky tests. If you enable it, watch the dashboard for runs that needed the retry. -
--priority highlets a release build's runs jump ahead of your other waiting runs, and--priority lowlets a nightly job wait. It only orders your own queue.
Alternatives to the CLI step#
If you prefer to stay in Gradle, TestingBot's Gradle plugin adds a testingbotEspresso task that uploads the two APKs, runs them on the devices you configure, downloads the JUnit report and fails the build on test failures. The REST API from the last chapter works from any CI system that can run curl.
Pull requests take too long because the workflow runs the suite on six devices. What keeps coverage without slowing down every pull request?
Splitting fast feedback from wide coverage is the standard trade-off. --async would make the check pass before any result exists, and retries make runs longer, not shorter.
That completes the path from a first onView to a suite that runs on every pull request. The knowledge check that follows covers the whole course.