Espresso Testing

Getting Started

To get started, please follow the steps below:

1. You will need a key and secret to connect to the TestingBot grid.
   These credentials are available in the TestingBot member area.

2. Espresso tests require a separate apk file for testing. So you will need to upload both the app (.apk or .aab file) and the test file (.apk).

TestingBot CLI

The easiest way to run Espresso tests on TestingBot is using our CLI tool. It handles uploading your app, test APK, and running tests in a single command.

Installation

npm install -g @testingbot/cli

Authentication

Authenticate using this command:

testingbot login

This opens your browser for authentication. After logging in, your credentials are saved to ~/.testingbot and you can start using the CLI.

Other Authentication Methods

• Command-line options: --api-key and --api-secret
• Environment variables: TB_KEY and TB_SECRET
• Config file: Create ~/.testingbot with content key:secret

Quick Start

Run Espresso tests with a single command:

testingbot espresso app.apk app-test.apk --device "Pixel 8" --platform-version "14"

testingbot espresso app.apk app-test.apk --device "Samsung Galaxy S24" --real-device

The CLI will:

1. Upload your app APK to TestingBot
2. Upload your test APK
3. Start the test run
4. Show real-time progress and results

Upload Android App

To run Android Espresso tests on TestingBot, you will first have to upload your .apk or .aab file to TestingBot Storage.

testingbot espresso /path/to/app/Application-debug.apk /path/to/test/Application-debug-test.apk --device "Pixel 8"

testingbot espresso --app /path/to/app/Application-debug.apk --test-app /path/to/test/Application-debug-test.apk --device "Pixel 8"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/espresso/app" \
-F "file=@/path/to/app/file/Application-debug.apk"

{
    "id": 4012
}

Upload Espresso Test Suite

You can now upload the .apk file containing the Espresso tests.
The upload process is similar to the app upload process.

testingbot espresso app.apk app-test.apk --device "Pixel 8"

testingbot espresso --app app.apk --test-app app-test.apk --device "Pixel 8"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/espresso/:id/tests" \
-F "file=@/path/to/app/file/Application-debug-test.apk"

Specify devices

You can specify one or more Android device capabilities with your API call.
These capabilities can target either Android emulators, or physical Android devices.

Android 16.0 › Pixel 9

Loading environments...

Please wait while we load the available browsers and platforms.

We offer special parameters which you can use to allocate a device:

Some Examples:

// find any Samsung Galaxy, except 23
-d '{"capabilities":[{"deviceName":"^(Galaxy.*)(?!23)$", "platformName":"Android", "realDevice": true}]}'

// find any device which name starts with Pixel
-d '{"capabilities":[{"deviceName":"Pixel.*", "platformName":"Android", "realDevice": true}]}'

Tablet Only

You can specify the tabletOnly capability when you only want to allocate a tablet device.

Phone Only

You can specify the phoneOnly capability when you only want to allocate a phone device.

-d '{"capabilities":[{"deviceName":"*", "tabletOnly": true, "platformName":"Android", "realDevice": true}]}'

-d '{"capabilities":[{"deviceName":"*", "phoneOnly": true, "platformName":"Android", "realDevice": true}]}'

Run Espresso Tests

Now that you have uploaded both your Android application and the Espresso test suite, you can run your first Espresso test on the TestingBot cloud.

# Basic usage with device selection
testingbot espresso app.apk app-test.apk --device "Pixel 8" --platform-version "14"

# Real device
testingbot espresso app.apk app-test.apk --device "Samsung Galaxy S24" --real-device

# With test name and build identifier
testingbot espresso app.apk app-test.apk \
  --device "Pixel 8" \
  --platform-version "14" \
  --name "Smoke Tests" \
  --build "v2.1.0"

# Run specific test classes
testingbot espresso app.apk app-test.apk \
  --device "Pixel 8" \
  --class "com.example.LoginTest,com.example.HomeTest"

# Run tests with specific annotations
testingbot espresso app.apk app-test.apk \
  --device "Pixel 8" \
  --annotation "com.example.SmokeTest" \
  --size "small,medium"

# Exclude specific test classes
testingbot espresso app.apk app-test.apk \
  --device "Pixel 8" \
  --not-class "com.example.SlowTest"

# With network throttling and geolocation
testingbot espresso app.apk app-test.apk \
  --device "Pixel 8" \
  --throttle-network "3G" \
  --geo-location "DE" \
  --language "de"

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/espresso/:id/run" \
-d '{"capabilities":[{"platform":"ANDROID", "version":12, "deviceName":"Pixel 6", "platformName":"Android"}]}' \
-H "Content-Type: application/json"

{
    "success": true
}

View Espresso Test Results

You will now see a test appear in the TestingBot dashboard, together with a video, test logs and other metadata.

You can also use the CLI or an API call to get the results from the run(s):

testingbot espresso app.apk app-test.apk --device "Pixel 8"

testingbot espresso app.apk app-test.apk --device "Pixel 8" --async

testingbot espresso app.apk app-test.apk --device "Pixel 8" \
  --report junit \
  --report-output-dir ./reports

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/espresso/:id"

{
  "runs": [
      {
          "status": "DONE",
          "capabilities": {
              "version": "12",
              "deviceName": "Pixel 6",
              "platformName": "Android"
          },
          "success": false,
          "test": {
              "sessionId": "30f6eild082c3-804f3c0ec2df-a18b2d431ffb-169920992163-48455547",
              "environment": {
                  "name": "chrome",
                  "os": "Pixel 6 - 12.0",
                  "version": "12.0"
              }
          }
      }
  ],
  "version": "1.0"
}