Skip to content

for Android

This guide covers setting and launching Emcee for Android projects. During further steps you will deploy Emcee in Docker or Kubernetes and run Android instrument tests.

Required skills - minimum experience with Docker and Kubernetes.

Keep in mind that:

  • Each worker runs 1 emulator on board with the specified Android api version inside the container. Find here all available api versions and screen resolutions

  • In trial version up to 10 Android workers will execute tests simultaneously. Rest load get executed serially.

If you encounter any issues while proceeding through the guide, please reach out via https://t.me/emcee_ios.

Table of contents#

  1. Prerequisites
  2. Deploy Emcee locally
  3. Create emceeplan
  4. Run tests
  5. Further steps

Prerequisites #

  • OS Linux, Docker, KVM
  • one container with Emcee worker requires at least 4GB RAM, 1.3 CPU (if you plan to use additional features, such as screenrecording or dynamic emulators, you will need more resources)
  • free disk space of at least 55GB. Where ~50GB for worker image, ~2.5GB for a queue one, ~2GB for Artifactory OSS
  • installed Docker Compose
  • installed Emcee CLI

Deploy Emcee queue, workers and Artifactory locally #

Create configuration file docker-compose.yml

docker-compose.yml
version: '3'
services:
  emcee-queue-service:
    image: avitotech/emcee-queue:21.2.0
    container_name: emcee-queue-service
    ports:
      - 41000:41000

  queue-worker:
    image: avitotech/emcee-worker:21.2.0
    env_file:
      - emcee-worker.env
    depends_on:
      - emcee-queue-service
    deploy:
      replicas: 3
    devices:
      - "/dev/kvm:/dev/kvm"

  emcee-artifactory:
    image: docker.bintray.io/jfrog/artifactory-oss:7.63.11
    container_name: emcee-artifactory
    ports:
      - 8081:8081
      - 8082:8082
    volumes:
      - emcee_artifactory:/var/opt/jfrog/artifactory
volumes:
  emcee_artifactory:

Create environment file emcee-worker.env next to docker-compose.yml in which you may configure environment variables for worker. Learn more in worker configuration.

Possible emcee-worker.env:

emcee-worker.env
EMCEE_WORKER_QUEUE_URL=http://emcee-queue-service:41000
EMCEE_WORKER_LOG_LEVEL=info

Then run docker compose up from directory containing docker-compose.yml. This will kickstart queue server, 3 workers and Artifactory.

Local network addresses will be:

  • http://localhost:41000/ for queue
  • http://localhost:8081/ for Artifactory

where ports match those specified in docker-compose.yml.

Create emceeplan #

To run tests you have to define emceeplan file. Take a look on example.yml:

tests:
  configurations:
    - platform: android
      appApk: app.apk
      testApk: app-androidTest.apk
      devices:
        - sdkVersion: 31
          deviceType: default
  outputs:
    - allure
queue:
  baseUrl: "http://localhost:41000"
storage:
  type: artifactory
  baseUrl: "http://localhost:8081"
  repository: emcee-transport

Configurations#

In this minimalistic emceeplan we've created single configuration to run app.apk against app-androidTest.apk. All tests will be run on single device with SDK 31 and default type:

      devices:
        - sdkVersion: 31
          deviceType: default

As a result we want to get only allure report:

  outputs:
    - allure

Queue#

Emcee requires queue and at least one worker in the system to operate. We've deployed Emcee queue and worker earlier, in emceeplan we specified that Emcee queue is running on localhost:

queue:
  baseUrl: "http://localhost:41000"

Storage#

Similar to Emcee queue, we specified that we want to use Artifactory as a file storage. It's been previously deployed and is running on localhost as well:

storage:
  type: artifactory
  baseUrl: "http://localhost:8081"
  repository: emcee

Learn more how you can setup storage.

Run tests #

To run all tests described in emceeplan use CLI in following way:

emcee run example.yml --outdir=results

After all tests finish executing you'll get short info in shell:

...
Emcee run finished.
Sent tests count: 12
Executed tests count: 12
Run status: Failed
Successful tests count: 10
Skipped tests count: 1
Skipped tests:
com.avito.emcee.regress.ExampleInstrumentedTest#assumptionFalse
Failed tests count: 1
Failed tests:
com.avito.emcee.regress.ExampleInstrumentedTest#failed

Tests results written to: /result/emcee_artifacts/regress-test

and files for Allure or JUnit report in results directory (if reports was specified in options).

Where to go from here #

In this simplified guide we utilized a few workers that unlikely will boost your pipeline significantly. To get better performance you should scale this guide up to as many machines as you have. Learn more on possible deployment options in production environment.

Find all possible test parameters you may use to configure in emceeplan to reflect your tests correctly.

You also may want to know all possible reports Emcee may yield during tests run.