# Espresso reporter

Source: https://docs.qualflare.com/docs/reporters/espresso · Last updated: 2026-10-29

Add com.qualflare:qualflare-espresso to androidTestImplementation, register its run listener and upload the reports Gradle pulls with the Qualflare CLI.

`com.qualflare:qualflare-espresso` is the Qualflare reporter for Espresso: it runs inside the instrumented app and writes each test's results, with retries, steps and screenshots, to the folder Gradle pulls from the device, and `qf <identifier> collect` uploads them as one launch.

| Fact                 | Detail                                                                                                                        |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Package              | [`com.qualflare:qualflare-espresso`](https://central.sonatype.com/artifact/com.qualflare/qualflare-espresso) on Maven Central |
| Works with           | minSdk 24, `androidx.test:monitor` 1.4.0 or later                                                                             |
| qf                   | (requires qf 0.1.24 or later) for screenshots                                                                                 |
| License              | Apache-2.0                                                                                                                    |
| Source               | [Qualflare/qualflare-espresso](https://github.com/Qualflare/qualflare-espresso) on GitHub                                     |
| Without the reporter | `--format espresso` with [Gradle's JUnit XML](https://docs.qualflare.com/docs/cli/formats#espresso)                           |

## Before you begin

* The Qualflare CLI, `qf`: [Install the CLI](https://docs.qualflare.com/docs/cli/installation).
* A saved login: `qf login <identifier>` with a project access token whose creator still holds the project role that uploads need (requires the Editor role or higher in the project) ([Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication)).
* The **Identifier** of the environment the results belong to ([Environments](https://docs.qualflare.com/docs/runs/environments#identifier)).

## Install

```kotlin
// app/build.gradle.kts
dependencies {
    androidTestImplementation("com.qualflare:qualflare-espresso:0.1.0")
}

android {
    defaultConfig {
        testInstrumentationRunnerArguments["listener"] =
            "com.qualflare.espresso.QualflareRunListener"
    }
}
```

JUnit 4 has no ServiceLoader hook, so the listener argument is required; it works with your existing runner, Hilt's included. The reporter adds nothing to your test classpath.

## Configure

Set options as instrumentation arguments, in Gradle or for one run:

```kotlin
testInstrumentationRunnerArguments["qualflare.environment"] = "staging"
```

```bash
./gradlew connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.qualflare.environment=staging
```

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `qualflare.environment` | `string` | `development` | No | The environment's Identifier. Variable `QUALFLARE_ENVIRONMENT`. |
| `qualflare.platform` | `string` | `android` | No | Variable `QUALFLARE_PLATFORM`. |
| `qualflare.branch` | `string` | `not sent` | No | The app has no git checkout, and `qf` doesn't read the branch from the report: set it on the upload. `qualflare.commit` is the same. Variable `QUALFLARE_BRANCH`. |
| `qualflare.enabled` | `string` | `on` | No | `0`, `false`, `no` and `off` turn it off. Variable `QUALFLARE_ENABLED`. |

Every reporter shares the other settings: see [Reporter configuration](https://docs.qualflare.com/docs/reporters/configuration).

Set `qualflare.environment` to the environment's Identifier: a name such as `Staging` fails the upload with HTTP 400 ([Environment](https://docs.qualflare.com/docs/reporters/configuration#environment)).

## Run and upload

```bash
./gradlew connectedAndroidTest
qf <identifier> collect "app/build/outputs/connected_android_test_additional_output/*/connected/*/qualflare-espresso-*.json"
```

Gradle nests the reports in a folder per variant and device, and `qf` reads only the files directly inside a folder, so pass the files with a quoted glob.

Below API 29, Gradle passes no output folder. The reporter writes into the app's files folder and prints the commands to pull it, including the flag that keeps the app installed after the run.

## Run in CI

```yaml
- name: Upload results to Qualflare
  if: ${{ !cancelled() }}
  env:
    QF_TOKEN: ${{ secrets.QF_TOKEN }}
    QF_BRANCH: ${{ github.head_ref || github.ref_name }}
    QF_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
  run: |
    npm install -g @qualflare/cli
    qf login ci --force
    qf ci collect "app/build/outputs/connected_android_test_additional_output/*/connected/*/qualflare-espresso-*.json"
```

`if: ${{ !cancelled() }}` uploads the results when tests fail, and `QF_BRANCH` and `QF_COMMIT` record a pull request's own branch and commit ([Pull request branches](https://docs.qualflare.com/docs/cli/ci-cd#pull-request-branches)). For GitLab CI/CD, Jenkins and Azure Pipelines, see [Run the upload when tests fail](https://docs.qualflare.com/docs/cli/ci-cd#run-when-tests-fail).

## Sharding and retries

A rerun test is one test with every attempt, marked flaky when a rerun passed. The glob collects every device's reports into one launch. See [Merge sharded CI jobs into one launch](https://docs.qualflare.com/docs/cli/sharding#merge-sharded-ci-jobs).

## What gets uploaded

* Status: passed, failed, skipped, timeout or error.
* Retries.
* Named, nested steps with parameters.
* Screenshots on demand, or on failure with `QualflareRule`.
* Attachments: bytes, a `File` or a `Bitmap`.
* Labels, tags, links, priority and description.

Screenshot on failure:

```java
private final ActivityScenarioRule<LoginActivity> activity =
        new ActivityScenarioRule<>(LoginActivity.class);

@Rule
public final RuleChain rules = RuleChain.outerRule(activity).around(new QualflareRule());
```

Put `QualflareRule` inside the rule that launches the activity. Reversed, the activity is already closed and the screenshot shows the launcher.

A test writes its own metadata:

```java
@Test
public void signsIn() {
    Qualflare.label("team", "identity");
    Qualflare.tag("smoke");
}
```

`qf` doesn't read the branch, commit, language or milestone from the report: set them on the upload ([Branch, commit, language and milestone](https://docs.qualflare.com/docs/reporters/configuration#upload-metadata)).

## Troubleshooting

* `directory "<dir>" contains no .json report files`: you passed the output folder; pass the quoted glob above.
* To see what the reporter did on the device, run `adb logcat -s QualflareEspresso`.
* `environment "Staging" does not exist in this project`: use the environment's Identifier, or pass `--environment` on the upload ([Environment](https://docs.qualflare.com/docs/reporters/configuration#environment)).
* Screenshots can't be downloaded: `qf` is older than 0.1.24. [Upgrade qf](https://docs.qualflare.com/docs/cli/installation#upgrading).

## Related

* **Guides:** [Reporters](https://docs.qualflare.com/docs/reporters) · [Upload results with qf collect](https://docs.qualflare.com/docs/cli/collect) · [Sharded runs and result directories](https://docs.qualflare.com/docs/cli/sharding) · [Upload screenshots, videos and traces](https://docs.qualflare.com/docs/cli/artifacts)
* **Reference:** [Reporter configuration](https://docs.qualflare.com/docs/reporters/configuration) · [Espresso format](https://docs.qualflare.com/docs/cli/formats#espresso)
* **More:** [Espresso test reporting in Qualflare](https://qualflare.com/espresso-test-reporting/)