### Install ew-cli and configure PATH (Shell)

Source: https://docs.emulator.wtf/getting-started

This snippet demonstrates how to download the ew-cli tool, make it executable, and add it to your system's PATH for easy access. It ensures that the command-line interface is available system-wide.

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

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

--------------------------------

### List available emulator models with ew-cli (Shell)

Source: https://docs.emulator.wtf/getting-started

This command uses the ew-cli tool to list all available emulator models and their versions supported by emulator.wtf. It requires an API token for authentication.

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

--------------------------------

### Build app and test APKs with Gradle (Shell)

Source: https://docs.emulator.wtf/getting-started

This command uses Gradle to build the debug versions of both the application APK and the Android test APK. These APKs are necessary for running automated tests on emulators.

```shell
./gradlew :app:assembleDebug :app:assembleDebugAndroidTest
```

--------------------------------

### Run tests with sharding using ew-cli (Shell)

Source: https://docs.emulator.wtf/getting-started

This command demonstrates how to speed up test execution by utilizing sharding with ew-cli. By specifying `--num-shards`, tests are parallelized across multiple emulators, reducing overall test run time.

```shell
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
```

--------------------------------

### Install emulator.wtf CLI

Source: https://docs.emulator.wtf/integrations/cli

Installs the ew-cli command-line client by downloading it from the specified URL and making it executable. Ensure $HOME/bin is on your PATH.

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

```

--------------------------------

### Run tests with ew-cli (Shell)

Source: https://docs.emulator.wtf/getting-started

This command executes your Android application tests using the ew-cli tool. It requires your API token and the paths to your application and test APKs. The output shows the test run status and a link to detailed results.

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

--------------------------------

### Start Interactive Emulator Session

Source: https://docs.emulator.wtf/integrations/cli

Starts an interactive emulator session with a specified device configuration and an optional time limit. The emulator connects to your local adb, allowing for tools like scrcpy to be used for interaction.

```APIDOC
## POST /websites/emulator_wtf/start-session

### Description
Starts an interactive emulator session with a max time limit. The emulator connects to your local adb, and can be controlled using third-party tools like scrcpy.

### Method
POST

### Endpoint
`/websites/emulator_wtf/start-session`

### Parameters
#### Query Parameters
- **device** (string) - Required - Device configuration (e.g., `model=Pixel2,version=34,gpu=auto`)
- **max-time-limit** (string) - Optional - Maximum duration for the session (e.g., `1h`, `30m`)

### Request Example
```bash
ew-cli start-session --device model=Pixel2,version=34,gpu=auto --max-time-limit 1h
```

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the started session.
- **status** (string) - The status of the session.

#### Response Example
```json
{
  "session_id": "sess_abc123",
  "status": "running"
}
```
```

--------------------------------

### Start Emulator Session

Source: https://docs.emulator.wtf/integrations/cli

Initiates an emulator session and configures ADB to connect to it. This feature is currently in closed alpha and requires direct contact for access. Sessions have a maximum time limit.

```bash
start-session
```

--------------------------------

### Gradle Plugin Installation (plugins DSL)

Source: https://docs.emulator.wtf/integrations/gradle-plugin

Configures the `mavenCentral()` repository and applies the emulator.wtf Gradle plugin using the plugins DSL. This is the recommended approach for modern Gradle builds.

```gradle
pluginManagement {
  repositories {
    mavenCentral()
    maven { url "https://plugins.gradle.org/m2/" }
  }
}

plugins {
  id "wtf.emulator.gradle" version "0.19.1"
}
```

--------------------------------

### Install Additional APKs to Emulator

Source: https://docs.emulator.wtf/concepts/push-files

Installs one or more APKs onto the device before the test execution begins. This is useful for testing interactions between multiple applications. APKs are specified as a comma-separated list.

```command-line
--additional-apks foo.apk,bar.apk
```

--------------------------------

### Emulator Device Configuration Examples

Source: https://docs.emulator.wtf/changelog/2021-10-16

Examples of new device configurations supported by emulator.wtf, including version and ATD (Automated Test Device) options. These configurations specify the device model, Android version, and whether to use an ATD image.

```text
device=Pixel2,version=30,atd=true
device=Pixel2,version=30
device=NexusLowRes,version=30,atd=true
device=NexusLowRes,version=30
```

--------------------------------

### Gradle Plugin Installation (buildscript classpath)

Source: https://docs.emulator.wtf/integrations/gradle-plugin

Adds the emulator.wtf Gradle plugin to the buildscript classpath in the root `build.gradle` file and applies it in the app project. This is an alternative method for older Gradle setups.

```gradle
buildscript {
  repositories {
    google()
    mavenCentral()
  }
  
  dependencies {
    // ... other deps here, like com.android.tools.build:gradle
    classpath "wtf.emulator:gradle-plugin:0.19.1"
  }
}

apply plugin: 'wtf.emulator.gradle'
```

--------------------------------

### Run tests with multiple device profiles

Source: https://docs.emulator.wtf/integrations/github-action

Example of configuring the emulator-wtf/run-tests action to run tests on multiple device profiles.

```APIDOC
## Run tests with multiple device profiles

By default emulator.wtf runs tests on a Pixel2-like emulator with API 27 (Android 8.1). If you want to run on a different version or device profile you can use the `devices` input to do so:

### Method
Uses action

### Endpoint
emulator-wtf/run-tests@v0

### Parameters
#### Inputs
- **api-token** (string) - API token for emulator.wtf. Required.
- **app** (string) - Path to application apk file. Required.
- **test** (string) - Path to test apk file. Required.
- **devices** (string) - Device configurations to use, in the form of `model=X,version=Y` per line.

### Request Example
```yaml
- name: Run tests
  uses: emulator-wtf/run-tests@v0
  with:
    api-token: "${{ secrets.EW_API_TOKEN }}"
    app: "app/build/outputs/apk/debug/app-debug.apk"
    test: "app/build/outputs/apk/androidTest/app-debug-androidTest.apk"
    devices: |
      model=NexusLowRes,version=23
      model=Pixel2,version=27
```
```

--------------------------------

### Configure GitHub Action Inputs for Emulator.wtf

Source: https://docs.emulator.wtf/changelog/page/5

This example shows how to configure various inputs for the emulator-wtf GitHub action. It includes options for library tests, output filtering, video recording, timeouts, sharding, side-effects, flaky test retries, and file/test caching.

```yaml
steps:
  - name: Run tests with custom configuration
    uses: emulator-wtf/run-tests@v0.9.0
    with:
      library-test: "true"
      outputs: "merged_results_xml,coverage,pulled_dirs"
      record-video: "false"
      timeout: "30m"
      num-balanced-shards: "4"
      side-effects: "disable_retries,disable_caching"
      num-flaky-test-attemtps: "2"
      file-cache: "false"
      file-cache-ttl: "2h"
      test-cache: "false"
```

--------------------------------

### Basic GitHub Action Workflow for Android Tests

Source: https://docs.emulator.wtf/integrations/github-action

This example demonstrates a basic GitHub Actions workflow to build an Android app and its test APK, run the tests using the emulator-wtf/run-tests action, and then publish the test report using the action-junit-report. It requires checkout, building the app, running tests with an API token, and publishing the report.

```yaml
name: Run tests
on: push
jobs:
  run-tests:
    runs-on: ubuntu-20.04
  steps:
    - uses: actions/checkout@v2
    - name: Build app
      run: ./gradlew assembleDebug assembleAndroidTest
    - name: Run tests
      uses: emulator-wtf/run-tests@v0
      with:
        api-token: ${{ secrets.EW_API_TOKEN }}
        app: app/build/outputs/apk/debug/app-debug.apk
        test: app/build/outputs/apk/androidTest/app-debug-androidTest.apk
        outputs-dir: build/test-results
    - name: Publish test report
      uses: mikepenz/action-junit-report@v2
      if: always() # always run even if the tests fail
      with:
        report_paths: 'build/test-results/**/*.xml'
```

--------------------------------

### Start Interactive Emulator Session with Time Limit

Source: https://docs.emulator.wtf/integrations/cli

Initiates an interactive emulator session connected to the local adb. The session has a maximum time limit and can be controlled via CLI commands. It requires the 'ew-cli' tool.

```bash
ew-cli start-session --device model=Pixel2,version=34,gpu=auto --max-time-limit 1h

```

--------------------------------

### Feed ew-cli Arguments via YAML File

Source: https://docs.emulator.wtf/integrations/cli

Allows configuration of ew-cli arguments through a YAML file, enabling complex setups and argument composition using an 'include' key. This method streamlines invocation for complex test configurations.

```yaml
atd:
  device:
    - model: Pixel2Atd
      version: 30
      
myapp:
  app: path/to/app.apk
  test: path/to/test.apk

pr-check:
  include: [atd, myapp]

```

```bash
ew-cli tests.yaml:pr-check

```

```bash
ew-cli --app path/to/app.apk --test path/to/test.apk \
  --device model=Pixel2Atd,version=30

```

--------------------------------

### Feed command-line arguments via a YAML file

Source: https://docs.emulator.wtf/integrations/cli

Allows configuration of `ew-cli` by providing arguments within a YAML file. This is useful for complex configurations or when repeating similar test setups.

```APIDOC
## POST /websites/emulator_wtf/run-tests

### Description
Executes tests using configurations defined in a YAML file. This approach allows for complex argument grouping and composition using an `include` key.

### Method
POST

### Endpoint
`/websites/emulator_wtf/run-tests`

### Parameters
#### Request Body
- **yaml_config** (string) - Required - The content of the YAML file containing test configurations.
- **test_group** (string) - Required - The specific group of arguments within the YAML file to execute (e.g., `pr-check`).

### Request Example
```yaml
# Example YAML file content:
atd:
  device:
    - model: Pixel2Atd
      version: 30

myapp:
  app: path/to/app.apk
  test: path/to/test.apk

pr-check:
  include: [atd, myapp]
```

```bash
ew-cli tests.yaml:pr-check
```

### Response
#### Success Response (200)
- **run_id** (string) - Identifier for the test run.
- **results** (object) - Detailed results of the test execution.

#### Response Example
```json
{
  "run_id": "run_xyz789",
  "results": {
    "passed": 10,
    "failed": 1
  }
}
```
```

--------------------------------

### Emulator WTF APK and Argument Configuration

Source: https://docs.emulator.wtf/integrations/gradle-plugin

This code snippet demonstrates how to configure additional APKs and environment variables for test runs using the emulatorwtf plugin. It shows how to specify extra APKs to install and how to pass custom arguments, including secret environment variables, to the AndroidJUnitRunner.

```gradle
emulatorwtf {
  // additional APKs to install, you can pass in `project.files(...)` or a 
  // Gradle configuration here
  additionalApks = configurations.additionalTestApks

  // additional arguments to AndroidJUnitRunner, by default emulator.wtf Gradle
  // plugin will pick these up from testInstrumentationRunnerArguments, however
  // you can override (or unset with null) these values here
  // 
  // for instance to only run medium tests:
  environmentVariables = [size: 'medium']

  // additional arguments to AndroidJUnitRunner, similar to the environmentVariables
  // above, but in this case the arguments will be hidden in the emulator.wtf UI.
  // Use this for passing any sort of secrets - tokens, passwords, credentials, etc.
  secretEnvironmentVariables = [token: 'hunter2']
}
```

--------------------------------

### GitHub Action for running tests with emulator.wtf

Source: https://docs.emulator.wtf/changelog/page/7

An official GitHub Action `emulator-wtf/run-tests@v0` is available for running tests using emulator.wtf. It simplifies the setup and execution of automated tests within GitHub Actions workflows.

```yaml
steps:
  - uses: emulator-wtf/run-tests@v0
    with:
      # inputs for the action
```

--------------------------------

### Run tests with orchestrator while clearing package data

Source: https://docs.emulator.wtf/integrations/github-action

Example of enabling Android Test Orchestrator and clearing package data for test runs.

```APIDOC
## Run tests with orchestrator while clearing package data

You can use Android Test Orchestrator to run the tests - this will create a new app VM from scratch for each test. Slower to run, but will ensure no static state leakage between tests. Add the optional `clear-package-data` flag to clear app persisted state between each run. Read more about orchestrator here.

### Method
Uses action

### Endpoint
emulator-wtf/run-tests@v0

### Parameters
#### Inputs
- **api-token** (string) - API token for emulator.wtf. Required.
- **app** (string) - Path to application apk file. Required.
- **test** (string) - Path to test apk file. Required.
- **use-orchestrator** (boolean) - Whether to use the Android Test Orchestrator.
- **clear-package-data** (boolean) - Whether to clear app data between every test (requires `use-orchestrator`).

### Request Example
```yaml
- name: Run tests
  uses: emulator-wtf/run-tests@v0
  with:
    api-token: "${{ secrets.EW_API_TOKEN }}"
    app: "app/build/outputs/apk/debug/app-debug.apk"
    test: "app/build/outputs/apk/androidTest/app-debug-androidTest.apk"
    use-orchestrator: true
    clear-package-data: true
```
```

--------------------------------

### Configure Proxy Settings for Emulator.wtf API

Source: https://docs.emulator.wtf/integrations/gradle-plugin

Sets up HTTP proxy details for communicating with the emulator.wtf API. These settings can be overridden by standard JVM system properties. Note that these proxy settings are for test setup and do not affect tests running within the emulator.

```gradle
proxyHost = "localhost"
proxyPort = 8080
proxyUser = "user"
proxyPassword = "hunter2"
```

--------------------------------

### Add Shard Target Runtime to ew-cli

Source: https://docs.emulator.wtf/changelog/2023-06-12

Introduces the `--shard-target-runtime` option to the ew-cli for a new sharding mode. This mode allows specifying the desired overall runtime for test execution, automatically determining the optimal number of shards. For example, `--shard-target-runtime 2m` will attempt to run a 10-minute test suite in approximately 2 minutes using 5 shards.

```bash
ew-cli --shard-target-runtime 2m
```

--------------------------------

### Display Help Information

Source: https://docs.emulator.wtf/integrations/cli

Lists all available `ew-cli` options along with their documentation. This is a fundamental command for understanding the tool's capabilities.

```bash
--help
```

--------------------------------

### Discover Available Device Profiles with emulator.wtf CLI

Source: https://docs.emulator.wtf/integrations/cli

Lists all available device profiles that can be used for running tests.

```bash
ew-cli --models

```

--------------------------------

### Options Reference

Source: https://docs.emulator.wtf/integrations/cli

Detailed reference for all available command-line options for the `ew-cli` tool, covering authentication, file handling, and test configuration.

```APIDOC
## Options Reference

### Authentication
#### `--token`
- **Type**: String
- **Description**: Your API token. Can alternatively be provided via the `EW_API_TOKEN` environment variable.

### Files
#### `--app`
- **Type**: Path
- **Description**: Path to the application APK to be tested.

#### `--test`
- **Type**: Path
- **Description**: Path to the test APK containing Android instrumentation tests (e.g., Espresso).

#### `--library-test PATH`
- **Type**: Path
- **Description**: The path to your com.android.library modules APK.

#### `--additional-apks`
- **Type**: List of Paths
- **Description**: A list of additional APKs to install alongside the primary test APKs.

#### `--other-files`
- **Type**: Key-Value Pairs (remote-path=local-path)
- **Description**: Allows uploading arbitrary files to the device. `remote-path` must start with `/sdcard/` or `/data/local/tmp`. Multiple files can be specified, separated by commas.

#### `--file-cache-ttl VALUE`
- **Type**: String (e.g., `90d`, `1h`, `5m`)
- **Description**: Maximum time to keep cached files in the remote cache. Units: `d` (days), `h` (hours), `m` (minutes), `s` (seconds). Max: `90d`, Min: `5m`. Default: `1h`.

#### `--no-file-cache / --file-cache`
- **Type**: Flag
- **Description**: Controls whether to use or disable the remote file cache for uploading APKs and test data.

### Test Configuration
#### `--display-name TEXT`
- **Type**: String
- **Description**: Display name for the test run in the web results UI.

#### `--device [key1=value1,key2=value2]`
- **Type**: Key-Value Pairs
- **Description**: Specifies the device(s) for test execution. Use repeated values for multiple devices. Possible keys: `model` (device profile), `version` (API version).

#### `--test-runner-class [value]`
- **Type**: String
- **Description**: The instrumentation runner class to use. Defaults to the value read from the test APK.

#### `--use-orchestrator`
- **Type**: Flag
- **Description**: Enables the use of Android Test Orchestrator.

#### `--clear-package-data`
- **Type**: Flag
- **Description**: Clears package data between app test runs. Only effective when `--use-orchestrator` is also set.

#### `--num-flaky-test-attempts`
- **Type**: Integer
- **Description**: Number of additional attempts for devices or shards with test failures. Maximum is 10. Attempts run in parallel.

#### `--flaky-test-repeat-mode [all|failed_only]`
- **Type**: Enum (String)
- **Description**: Determines whether to repeat the entire failed shard (`all`) or only the failed tests (`failed_only`) in case of flaky tests. Default: `failed_only`.

#### `--timeout [value]`
- **Type**: String (e.g., `10m`, `2h`)
- **Description**: Maximum allowed test runtime. Format: number + unit (`s`, `m`, `h`). Defaults to `15m`.

#### `--test-targets "<type> <target>"`
- **Type**: String
- **Description**: Filters test execution to specific targets forwarded to `AndroidJUnitRunner`. Examples: `class com.example.Foo`, `package com.example`, `size medium`.

#### `--environment-variables [key1=value1,key2=value2]`
- **Type**: Key-Value Pairs (Comma-separated)
- **Description**: A list of key-value pairs passed to `AndroidJUnitRunner`.

```

--------------------------------

### emulator.wtf CLI Help Command

Source: https://docs.emulator.wtf/integrations/cli

Displays all available options and commands for the ew-cli tool.

```bash
ew-cli --help

```

--------------------------------

### Manual Test Sharding Configuration

Source: https://docs.emulator.wtf/integrations/cli

Allows manual specification of test targets for sharding using `--test-targets-for-shard`. You can specify packages, classes, or individual methods. Multiple targets can be combined using commas or semicolons.

```bash
--test-targets-for-shard "package com.foo"
```

```bash
--test-targets-for-shard "class com.foo.MyTestClass"
```

```bash
--test-targets-for-shard "class com.foo.MyTestClass#myTestMethod"
```

```bash
--test-targets-for-shard "class com.example.Foo,com.example.Bar"
```

```bash
--test-targets-for-shard "package com.example;class com.foo.MyTestClass"
```

--------------------------------

### Configure Gradle Test Targets

Source: https://docs.emulator.wtf/changelog/2023-05-26

This configuration allows filtering tests run by the gradle-plugin. It utilizes the Android JUnit Runner's 'testTargets' option to specify which tests to execute, for example, by class name.

```gradle
testTargets = 'class foo.bar.Baz'
```

--------------------------------

### List Emulator Models via ew-cli

Source: https://docs.emulator.wtf/emulators

Lists all available emulator models using the ew-cli. Provides a human-readable output of model names and their associated API versions.

```bash
ew-cli --models
```

--------------------------------

### Configure Network Settings for Emulator

Source: https://docs.emulator.wtf/integrations/gradle-plugin

Sets up network redirection and DNS server usage for emulator instances. `dnsServers` specifies custom DNS servers, and `egressTunnel` along with `egressLocalhostForwardIp` can redirect network traffic to the local machine for testing internal environments.

```gradle
dnsServers = ["1.1.1.1"]
egresstunnel = false
egresstunnel = true
egresstunnel = false
egresstunnel = true
// Makes the machine the Gradle build is running on visible to the emulator under the given ipv4 address,
// only works together with the egressTunnel option
egreessLocalhostForwardIp = "192.168.200.1"
```

--------------------------------

### Get Outbound IP Addresses via HTTPS JSON

Source: https://docs.emulator.wtf/concepts/networking

Fetches a machine-readable JSON list of outbound IP addresses used by emulators over HTTPS. This is a convenient method for applications and scripts to obtain the IP list programmatically. The `curl` command is used to download the JSON data from the provided URL.

```shell
curl -sSL https://docs.emulator.wtf/outbound-ips.json

```

--------------------------------

### Get Outbound IP Addresses via DNS

Source: https://docs.emulator.wtf/concepts/networking

Retrieves a list of outbound IP addresses used by emulators by querying a specific DNS A record. This method is useful for automated systems that need to know the source IPs for firewall rules or network monitoring. The command uses `dig` to perform the DNS lookup.

```shell
dig a outbound.ips.emulator.wtf +short

```

--------------------------------

### List Available Device Models

Source: https://docs.emulator.wtf/integrations/cli

Displays a list of all device models supported by the emulator. When used in conjunction with the `--json` flag, the output is provided in a machine-readable JSON format.

```bash
--models
```

--------------------------------

### Run Android Tests with Orchestrator and Clear Package Data

Source: https://docs.emulator.wtf/integrations/github-action

This example configures the emulator-wtf/run-tests action to use the Android Test Orchestrator, which isolates each test in its own application APK. It also includes the `clear-package-data` flag to ensure app data is cleared between test runs, preventing state leakage. This is useful for ensuring test independence.

```yaml
- name: Run tests
  uses: emulator-wtf/run-tests@v0
  with:
    api-token: ${{ secrets.EW_API_TOKEN }}
    app: app/build/outputs/apk/debug/app-debug.apk
    test: app/build/outputs/apk/androidTest/app-debug-androidTest.apk
    use-orchestrator: true
    clear-package-data: true
```

--------------------------------

### Emulator WTF Plugin Configuration Options

Source: https://docs.emulator.wtf/integrations/gradle-plugin

This snippet details the configuration options for the emulatorwtf Gradle plugin. It shows how to set the CLI version, API token, output directories, and specify desired test outputs like summaries and captured videos. It also includes options for controlling output verbosity and enabling video recording.

```gradle
emulatorwtf {
  // CLI version to use, defaults to 0.12.1
  version = '0.12.1'

  // emulator.wtf API token, we recommend either using the EW_API_TOKEN env var
  // instead of this or passing this value in via a project property
  token = 'AQAA...'

  // where to store results in, they will be further scoped by the variant name,
  // i.e. ./gradlew :app:testFreeDebugWithEmulatorWtf will store outputs in
  // build/build-results/freeDebug
  baseOutputDir = layout.buildDirectory.dir("build-results")

  // Specify what kind of outputs to store in the base output dir
  // default: [OutputType.MERGED_RESULTS_XML, OutputType.COVERAGE, OutputType.PULLED_DIRS]
  outputs = [OutputType.SUMMARY, OutputType.CAPTURED_VIDEO, OutputType.LOGCAT]

  // Always print the ew-cli output the console when running. Useful for debugging.
  printOutput = true

  // record a video of the test run
  recordVideo = true
}
```

--------------------------------

### Configuring Test Output Types

Source: https://docs.emulator.wtf/integrations/cli

The `--outputs` argument specifies which types of test results to download into `--outputs-dir`. Options include `summary`, `merged_results_xml`, `coverage`, `pulled_dirs`, `results_xml`, `logcat`, `captured_video`, and `individual_test_videos`. The default includes `merged_results_xml`, `coverage`, and `pulled_dirs`.

```bash
--outputs summary,logcat
```

```bash
--outputs merged_results_xml,coverage,pulled_dirs
```

--------------------------------

### Specify Emulator and Version for Testing

Source: https://docs.emulator.wtf/changelog/page/5

This demonstrates how to specify particular emulator devices and Android API versions for testing. This allows for targeted testing on specific device configurations.

```cli
device=Pixel2,version=33
```

```cli
device=Tablet10,version=33
```

```cli
device=NexusLowRes,version=33
```

```cli
device=Monitor,version=33
```

--------------------------------

### Run emulator.wtf Tests on Multiple Device Profiles

Source: https://docs.emulator.wtf/integrations/cli

Executes tests across a combination of different device profiles by providing multiple --device arguments.

```bash
ew-cli --app path/to/app.apk --test path/to/test.apk \
  --device model=NexusLowRes,version=23 --device model=Pixel2,version=27

```

--------------------------------

### Emulator.wtf API Token Configuration

Source: https://docs.emulator.wtf/integrations/gradle-plugin

Demonstrates how to configure the emulator.wtf API token within the Gradle build. It shows the recommended environment variable method and an alternative using the `emulatorwtf` extension with project properties.

```gradle
emulatorwtf {
  token = project.properties.ewApiToken
}
```

--------------------------------

### Run emulator.wtf Tests with Sharding

Source: https://docs.emulator.wtf/integrations/cli

Distributes tests across multiple shards for parallel execution. Outputs for each shard are stored separately.

```bash
ew-cli --app path/to/app.apk --test path/to/test.apk --outputs-dir out --num-shards 3

```

--------------------------------

### Configure sharding options in GitHub Action

Source: https://docs.emulator.wtf/changelog/page/4

The `emulator-wtf/run-tests` GitHub Action now supports `shard-target-runtime` and `flaky-test-repeat-mode` options, mirroring the functionality available in ew-cli for optimized test execution.

```yaml
steps:
- uses: emulator-wtf/run-tests@v0.9.6
  with:
    shard-target-runtime: "2m"
    flaky-test-repeat-mode: "all"
```

--------------------------------

### Basic emulator.wtf CLI Test Execution

Source: https://docs.emulator.wtf/integrations/cli

Runs Android instrumentation tests using the ew-cli. Requires your API token and paths to the app and test APKs. Use --help for all options.

```bash
ew-cli --token YOUR_API_TOKEN --app path/to/app.apk --test path/to/test.apk

```

--------------------------------

### Optimize Test Runtime with Shard Target

Source: https://docs.emulator.wtf/integrations/cli

Configures sharding to aim for a specific total test runtime, distributing tests across parallel emulators based on historical data.

```bash
ew-cli --app path/to/app.apk --test path/to/test.apk --outputs-dir out --shard-target-runtime 2m

```

--------------------------------

### Run Emulator CLI with Coverage

Source: https://docs.emulator.wtf/concepts/coverage

Execute the emulator CLI tool with the `--with-coverage` flag to capture code coverage data. Specify output directories and devices for sharded runs.

```bash
$ ew-cli --app path/to/app.apk --test path/to/test.apk \
  --with-coverage --outputs-dir /tmp/foo \
  --device model=NexusLowRes --device model=Pixel2

```

--------------------------------

### Run Specific Tests with test-targets in GitHub Action

Source: https://docs.emulator.wtf/changelog/page/4

The `emulator-wtf/run-tests` GitHub action now supports the `--test-targets` option, enabling users to specify which tests should be run. This mirrors the functionality available in the Gradle plugin and ew-cli, allowing for precise control over test execution.

```yaml
name: Run emulator.wtf tests

on: [push]

jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests with specific targets
        uses: emulator-wtf/run-tests@v0.9.2
        with:
          # Example: Run only tests in the class foo.bar.Baz
          test-targets: 'class foo.bar.Baz'
          # Example: Run tests in package com.example.myapp and exclude tests annotated with @FlakyTest
          # test-targets: 'package com.example.myapp and notAnnotation com.example.FlakyTest'
```

--------------------------------

### Add Files to Device Before emulator.wtf Test

Source: https://docs.emulator.wtf/integrations/cli

Pushes additional files to the emulator's storage before test execution, making them accessible to the application or tests.

```bash
ew-cli --app path/to/app.apk --test path/to/test.apk \
  --other-files /sdcard/fixtures.json=fixtures.json

```

--------------------------------

### Capture video recording of test with ew-cli

Source: https://docs.emulator.wtf/changelog/page/6

The ew-cli tool now supports capturing video recordings of test runs. To enable this feature, use the `--record-video` flag in conjunction with `--outputs-dir`. A `recording.mp4` file will be saved for each device-job combination.

```bash
ew-cli --record-video --outputs-dir /path/to/outputs
```

--------------------------------

### Emulator.wtf Run Tests Action

Source: https://docs.emulator.wtf/integrations/github-action

This section details the inputs for the emulator-wtf/run-tests@v0 GitHub Action, used for running Android instrumentation tests.

```APIDOC
## emulator-wtf/run-tests@v0

### Description
This action runs instrumentation tests on Android devices.

### Method
Uses action

### Endpoint
emulator-wtf/run-tests@v0

### Parameters
#### Inputs
- **version** (string) - ew-cli version to use
- **api-token** (string) - API token for emulator.wtf. We recommend using Encrypted secrets for this.
- **app** (string) - Path to application apk file
- **test** (string) - Path to test apk file
- **library-test** (string) - Path to library test apk file
- **outputs-dir** (string) - Location to store test outputs in
- **outputs** (string) - Comma-separated list to specify what to download to output-dir. Defaults to `merged_results_xml,coverage,pulled_dirs`.
- **record-video** (boolean) - Set to true to record a video of the test run. Defaults to false.
- **devices** (string) - Device configurations to use, in the form of `model=X,version=Y` per line
- **timeout** (string) - Timeout for the test run, number with unit (`h`, `m` or `s`). Defaults to 15m.
- **use-orchestrator** (boolean) - Whether to use the Android Test Orchestrator
- **clear-package-data** (boolean) - Whether to clear app data between every test (requires `use-orchestrator`)
- **with-coverage** (boolean) - Set to true to collect coverage files and save them to `outputs-dir`
- **additional-apks** (string) - Additional apks to install, one per line
- **environment-variables** (string) - Environment variables to pass to AndroidJUnitRunner, one per line in the form of `key=value`
- **num-uniform-shards** (integer) - Set to a number larger than 1 to randomly split your tests into multiple shards to be executed in parallel
- **num-shards** (integer) - Set to a number larger than 1 to split your tests into multiple shards based on test counts to be executed in parallel
- **num-balance-shards** (integer) - Set to a number larger than 1 to split your tests into multiple shards based on test execution time to be executed in parallel
- **directories-to-pull** (string) - Directories to pull from device and store in `outputs-dir`, one per line
- **side-effects** (boolean) - Whether the test has any side effects, like hitting external APIs. Prevents any test caching and retries.
- **num-flaky-test-attempts** (integer) - Number of times to retry flaky tests. Defaults to 0.
- **file-cache** (boolean) - Whether to cache files between test runs. Defaults to true.
- **file-cache-ttl** (string) - How long to cache test files for. Defaults to 1h.
- **test-cache** (boolean) - Whether to cache test results between test runs. Defaults to true.

### Request Example
```yaml
uses: emulator-wtf/run-tests@v0
with:
  api-token: "${{ secrets.EW_API_TOKEN }}"
  app: "app/build/outputs/apk/debug/app-debug.apk"
  test: "app/build/outputs/apk/androidTest/app-debug-androidTest.apk"
  outputs-dir: "build/test-results"
```

### Response
#### Success Response (200)
- **[Response Fields]** (type) - Description of the field

#### Response Example
```json
{
  "message": "Tests completed successfully."
}
```
```

--------------------------------

### Run Tests in Parallel with Shards using run-tests Action

Source: https://docs.emulator.wtf/integrations/github-action

This snippet shows how to execute tests in parallel using the `num-shards` option of the emulator-wtf/run-tests action. It specifies the number of shards to use and directs the output from each shard to a separate folder within the `outputs-dir`. Requires an `api-token` and paths to the application and test APKs.

```yaml
    - name: Run tests
      uses: emulator-wtf/run-tests@v0
      with:
        api-token: ${{ secrets.EW_API_TOKEN }}
        app: app/build/outputs/apk/debug/app-debug.apk
        test: app/build/outputs/apk/androidTest/app-debug-androidTest.apk
        num-shards: 10
        outputs-dir: build/test-results

```

--------------------------------

### Capture Test Coverage Data with run-tests Action

Source: https://docs.emulator.wtf/integrations/github-action

This snippet demonstrates how to use the emulator-wtf/run-tests action with the `with-coverage: true` flag. It captures test run coverage data and stores the results (e.g., .exec or .ec files) in the directory specified by `outputs-dir`. Requires an `api-token` and paths to the application and test APKs.

```yaml
    - name: Run tests
      uses: emulator-wtf/run-tests@v0
      with:
        api-token: ${{ secrets.EW_API_TOKEN }}
        app: app/build/outputs/apk/debug/app-debug.apk
        test: app/build/outputs/apk/androidTest/app-debug-androidTest.apk
        with-coverage: true
        outputs-dir: build/test-results

```

--------------------------------

### Test Output Recording

Source: https://docs.emulator.wtf/integrations/cli

Enable video recording during test execution with `--record-video`. This flag captures the visual output of your tests.

```bash
--record-video
```

--------------------------------

### Record Video During emulator.wtf Test Run

Source: https://docs.emulator.wtf/integrations/cli

Executes tests while recording a video of the emulator session. The video is saved in the directory specified by --outputs-dir.

```bash
ew-cli --app path/to/app.apk --test path/to/test.apk --record-video --outputs-dir out

```

--------------------------------

### Print Version Information

Source: https://docs.emulator.wtf/integrations/cli

Outputs the current version of the `ew-cli` tool and then exits the program.

```bash
--version
```

--------------------------------

### Specify ADB Binary Path

Source: https://docs.emulator.wtf/integrations/cli

Provide the explicit path to the ADB binary to be used. If not specified, `ew-cli` will attempt to locate it using `ANDROID_HOME`, `ANDROID_SDK_ROOT` environment variables, or by searching the system's PATH. This option is valid only when using `start-session`.

```bash
--adb-binary
```

--------------------------------

### List Emulator Models in JSON format via ew-cli

Source: https://docs.emulator.wtf/emulators

Retrieves a machine-readable JSON output of emulator models, including additional details like screen sizes and densities. This is useful for programmatic access and analysis.

```bash
ew-cli --models --json
```

--------------------------------

### Capture Coverage Data with emulator.wtf CLI

Source: https://docs.emulator.wtf/integrations/cli

Enables coverage data collection during test execution. The resulting .exec files are stored in the specified output directory.

```bash
ew-cli --with-coverage --app path/to/app.apk --test path/to/test.apk \
  --outputs-dir out

```

--------------------------------

### Push additional files to emulator with ew-cli

Source: https://docs.emulator.wtf/changelog/page/6

Use the `--other-files` option with ew-cli to push additional files into the emulator's `/sdcard` or `/data/local/tmp` directories. This is useful for providing necessary resources for your tests.

```bash
ew-cli --other-files "./my_resource.txt:/sdcard/" --other-files "./config.json:/data/local/tmp/"
```

--------------------------------

### Configure ew-cli Sharding and Output Types

Source: https://docs.emulator.wtf/changelog/page/5

These snippets show how to configure the `ew-cli` for advanced sharding strategies and control the output types. The `numBalancedShards` property enables fair sharding based on historical runtime, while `outputTypes` allows customization of generated files.

```cli
--num-balanced-shards [value]
```

```cli
--outputs results_xml,coverage,pulled_dirs,logcat,captured_video
```

```gradle
emulatorwtf {
  // ...
  numBalancedShards = 4 // Example value
  outputTypes = ['results_xml', 'logcat'] // Example value
}
```

--------------------------------

### Emulator WTF File System and Caching Configuration

Source: https://docs.emulator.wtf/integrations/gradle-plugin

This snippet details the configuration for file system interactions and caching within the emulatorwtf plugin. It includes options for specifying directories to pull from the device after tests, enabling/disabling the file cache, setting its time-to-live, and controlling test result caching.

```gradle
emulatorwtf {
  // Directories to pull from device after test is over, will be stored in
  // baseOutputDir/${variant}:
  diretoriesToPull = ['/sdcard/screenshots']

  // Enable-disable the test input file cache (APKs etc)
  fileCacheEnabled = false

  // Set the maximum time-to-live of items in the test input file cache
  fileCacheTtl = Duration.ofHours(3)

  // Disable caching test results in the backend
  // NOTE! This will not disable caching at the Gradle task or Gradle build cache level,
  // use sideEffects = true to disable all caching
  testCacheEnabled = false
}
```

--------------------------------

### Run Tests with Multiple Device Profiles

Source: https://docs.emulator.wtf/integrations/gradle-plugin

Allows specifying different device models and Android API versions for running tests. The `devices` property accepts a list of maps, where each map defines a `model` and `version` for an emulator configuration.

```gradle
emulatorwtf {
  devices = [
    [model: "NexusLowRes", version: 23],
    [model: "Pixel2", version: 27]
  ]
}
```

--------------------------------

### Push Other Files to Emulator

Source: https://docs.emulator.wtf/concepts/push-files

Transfers arbitrary files, such as test fixtures or baseline screenshots, to the emulator device. Files are specified using a `remote-path=local-path` format and can be separated by commas for multiple transfers. Supported remote paths include `/data/local/tmp/` and `/sdcard/`.

```command-line
--other-files /sdcard/fixtures.json=fixtures.json
```

```command-line
--other-files /sdcard/fixtures.json=fixtures.json,/sdcard/baseline-screenshots.zip=baseline-screenshots.zip
```

--------------------------------

### Sharding Tests by Runtime

Source: https://docs.emulator.wtf/integrations/cli

Splits tests across emulator instances based on historical runtime for even distribution using `--num-balanced-shards`. Alternatively, `--shard-target-runtime` aims for a specific target runtime per shard (e.g., `3m`), falling back to heuristic sharding if data is unavailable.

```bash
--num-balanced-shards [value]
```

```bash
--shard-target-runtime 3m
```

--------------------------------

### Prepare file cache without triggering tests using ew-cli

Source: https://docs.emulator.wtf/changelog/page/6

The ew-cli includes a `--prepare` flag that allows populating the file cache without initiating any test runs. This is useful for pre-caching files for subsequent test executions.

```bash
ew-cli --prepare
```

--------------------------------

### Update GitHub Action emulator-wtf/run-tests to use node20 runtime

Source: https://docs.emulator.wtf/changelog/page/3

This update for the emulator-wtf/run-tests GitHub Action incorporates several changes, including bumping the default ew-cli version and updating subactions to utilize the node20 GitHub Actions runtime. This ensures compatibility with the latest Node.js environment for action execution.

```yaml
steps:
  - name: Run tests
    uses: emulator-wtf/run-tests@v0.9.8
    with:
      # Other inputs
      ew-cli-version: 0.10.7
```

--------------------------------

### Run emulator.wtf Tests and Save Outputs

Source: https://docs.emulator.wtf/integrations/cli

Runs tests and saves the results, including JUnit XML reports and logcat, to a specified directory. Useful for CI artifact collection.

```bash
ew-cli --app path/to/app.apk --test path/to/test.apk --outputs-dir out

```

--------------------------------

### Run emulator.wtf Tests with Orchestrator and Clear Package Data

Source: https://docs.emulator.wtf/integrations/cli

Executes tests using Android Test Orchestrator for isolated test environments and clears app data between runs to ensure a clean state.

```bash
ew-cli --use-orchestrator --clear-package-data --app path/to/app.apk \
  --test path/to/test.apk

```

--------------------------------

### Enable Video Recording in GitHub Action

Source: https://docs.emulator.wtf/changelog/page/5

This snippet demonstrates how to enable video recording for test runs within the emulator-wtf GitHub action. Video recording is off by default and can be enabled by setting the 'record-video' option to 'false' in the 'emulatorwtf {}' project extension.

```yaml
steps:
  - name: Run tests with video recording enabled
    uses: emulator-wtf/run-tests@v0.9.0
    with:
      record-video: "false"
      # Other inputs can be specified here
```

--------------------------------

### Run Android Tests on Multiple Device Profiles

Source: https://docs.emulator.wtf/integrations/github-action

This code snippet shows how to configure the emulator-wtf/run-tests action to execute tests on different emulator device profiles and Android API versions. It utilizes the `devices` input, accepting a multi-line string where each line specifies a device model and API version.

```yaml
- name: Run tests
  uses: emulator-wtf/run-tests@v0
  with:
    api-token: ${{ secrets.EW_API_TOKEN }}
    app: app/build/outputs/apk/debug/app-debug.apk
    test: app/build/outputs/apk/androidTest/app-debug-androidTest.apk
    devices: |
      model=NexusLowRes,version=23
      model=Pixel2,version=27
```

--------------------------------

### Add test-runtime-android to Gradle Build

Source: https://docs.emulator.wtf/changelog/2024-03-22

This snippet shows how to include the test-runtime-android library in your Android project's Gradle build file to enable per-test video recordings. Ensure you are using version 0.2.0 or later.

```gradle
androidTestImplementation("wtf.emulator:test-runtime-android:0.2.0")
```