--- title: Espresso Testing in the cloud. description: Run Android Espresso tests in the cloud on physical Android devices. source_url: html: https://testingbot.com/support/app-automate/espresso md: https://testingbot.com/support/app-automate/espresso.md --- # Espresso Testing TestingBot provides access to Android physical devices and Android emulators, capable of running your Android Espresso tests. [Espresso](https://developer.android.com/training/testing/espresso) is a mobile automation framework from Google, designed to run UI tests for Android applications. Using Espresso in combination with TestingBot's Android cloud service is very straightforward: - Upload your native mobile Android app, together with the Espresso test apk file. These are created with either Java or Kotlin. - Specify on which devices you want to run the Espresso tests. - Retrieve the results of the Espresso tests. ## 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](https://testingbot.com/members). 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`). You can also use the [TestingBot Espresso Demo App](https://github.com/testingbot/android-espresso-demo-app) to give the Espresso Cloud Testing functionality a try. ## 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 ```bash npm install -g @testingbot/cli ``` ### Authentication Authenticate using this command: ```bash 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: ```bash testingbot espresso app.apk app-test.apk --device "Pixel 8" --platform-version "14" ``` ```bash testingbot espresso app.apk app-test.apk --device "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 If you build your Android app with Gradle, our [Gradle plugin](https://testingbot.com/support/integrations/ci-cd/gradle) can upload your app and run Espresso tests straight from your build, no separate CLI step required. ## Upload Android App To run Android Espresso tests on TestingBot, you will first have to upload your `.apk` or `.aab` file to TestingBot Storage. [CLI](https://testingbot.com#) [cURL](https://testingbot.com#) When using the CLI, the app upload is handled automatically as part of the `testingbot espresso` command. Simply specify your app APK file as the first argument: ```bash testingbot espresso /path/to/app/Application-debug.apk /path/to/test/Application-debug-test.apk --device "Pixel 8" ``` Alternatively, you can use the `--app` option: ```bash testingbot espresso --app /path/to/app/Application-debug.apk --test-app /path/to/test/Application-debug-test.apk --device "Pixel 8" ``` ```bash 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" ``` The API response will include an `id` response, which you can use in the other API calls. ```json { "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](https://testingbot.com#upload) process. [CLI](https://testingbot.com#) [cURL](https://testingbot.com#) When using the CLI, the test APK upload is handled automatically. Specify your test APK as the second argument: ```bash testingbot espresso app.apk app-test.apk --device "Pixel 8" ``` Or use the `--test-app` option: ```bash testingbot espresso --app app.apk --test-app app-test.apk --device "Pixel 8" ``` ```bash 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" ``` Replace the `:id` with the identifier you received during the app upload call. ## 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 OS selected](https://testingbot.com/assets/environments/svg/android-1b3d235e17522e2238e1c55b4e9cdd41219f653cd958ea065877d3813f32ffc3.svg) 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: Regex Input | Result || `"Pixel.*"` | This will allocate any available Pixel device (phone) | | `"*"` | This will allocate a random available Android device | | `"Pixel [8-9]"` | This will allocate either an Pixel 8 or 9 | Some Examples: ```bash # find any Samsung Galaxy, except the S23 family -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. ```bash -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. [CLI](https://testingbot.com#) [cURL](https://testingbot.com#) Use the CLI to run tests with device selection options: ```bash # 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 "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" ``` ### Device Options | Option | Description | | --- | --- | | `--device ` | Device name (e.g., "Pixel 8", "Samsung.\*") | | `--platform-version ` | Android version (e.g., "12", "13", "14") | | `--real-device` | Use a real device instead of emulator | | `--tablet-only` | Only allocate tablet devices | | `--phone-only` | Only allocate phone devices | #### Test Filtering ```bash # 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" ``` #### Test Filtering Options | Option | Description | | --- | --- | | `--class ` | Run tests in specific classes (comma-separated fully qualified names) | | `--not-class ` | Exclude tests in specific classes | | `--package ` | Run tests in specific packages (comma-separated) | | `--not-package ` | Exclude tests in specific packages | | `--annotation ` | Run tests with specific annotations (comma-separated) | | `--not-annotation ` | Exclude tests with specific annotations | | `--size ` | Run tests by size: small, medium, large (comma-separated) | #### Network & Location ```bash # With network throttling and geolocation testingbot espresso app.apk app-test.apk \ --device "Pixel 8" \ --throttle-network "3G" \ --geo-location "DE" \ --language "de" ``` ```bash curl -u api_key:api_secret \ -X POST "https://api.testingbot.com/v1/app-automate/espresso/:id/run" \ -d '{"capabilities":[{"version":"12", "deviceName":"Pixel 6", "platformName":"Android"}]}' \ -H "Content-Type: application/json" ``` Replace the `:id` with the identifier you received during the app upload call. The API response will include a `success` response, indicating if the tests will start or if an error occurred. ```json { "success": true } ``` ## View Espresso Test Results You will now see a test appear in the [TestingBot dashboard](https://testingbot.com/members), 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): [CLI](https://testingbot.com#) [cURL](https://testingbot.com#) By default, the CLI waits for test completion and displays real-time progress: ```bash testingbot espresso app.apk app-test.apk --device "Pixel 8" ``` The CLI will show: - Upload progress for app and test APK - Device allocation status - Live output from Espresso tests - Final pass/fail status ### Async Mode Use `--async` to start tests without waiting for results: ```bash testingbot espresso app.apk app-test.apk --device "Pixel 8" --async ``` #### Download JUnit Report Download the JUnit report after test completion: ```bash testingbot espresso app.apk app-test.apk --device "Pixel 8" \ --report junit \ --report-output-dir ./reports ``` ```bash curl -u api_key:api_secret \ "https://api.testingbot.com/v1/app-automate/espresso/:id" ``` Replace the `:id` with the identifier you received during the app upload call. The API response will include a response indicating the current state of the Espresso test results. ```json { "runs": [ { "status": "DONE", "capabilities": { "version": "12", "deviceName": "Pixel 6", "platformName": "Android" }, "success": false, "test": { "sessionId": "30f642d082c3-804f3c0ec2df-a18b2d431ffb-169920992163-48455547", "environment": { "name": "chrome", "os": "Pixel 6 - 12.0", "version": "12.0" } } } ], "version": "1.0" } ``` ### Looking for more help? Have questions or need more information? Reach out via email or Slack. [Email us](https://testingbot.com/contact/new) [Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)