Skip to content

Integrations (CLI, API and others)

API tokens and authorization#

All API requests must contain a cookie emcee_token or token parameter

You can get API token on profile page

Command-line interface#

We have Command-Line interface which implements basic functionality of interaction with emcee.cloud

The main features in a nutshell:

  • Running iOS/Android tests
  • Tracking test results during a run
  • Downloading results
  • Configuration via file and cli params
  • Mac OS and Linux supported

Installation#

Mac OS#
brew tap avito-tech/tap && brew install emcee-cloud
Linux#

Follow instructions on Command-Line interface GitHub page.

Docker#

Official Emcee.cloud-CLI docker image in Docker HUB

Available Commands#

  • run - Run tests on emcee.cloud
  • help - Help about any command
  • completion - Generate the autocompletion script for the specified shell

For example, to run the android tests:

emcee-cloud run android

Configuration#

Configuration file#

We recommend using a configuration file as it is a more flexible and powerful way to customize your runs

1. Prepare your configuration file based on the example below. Don't forget to delete all unused fields and comments.

platform: ios
app: https://emcee.cloud/api/v1/file/download/e65f3887-b6af-4fe7-a791-74dcd44b62c2#EmceeSample.app
tests: /Users/Downloads/EmceeSampleHostedTests.xctest
runner: /Users/Downloads/EmceeSampleHostedTestsRunner.xctest # Optional
outputs: ["allure", "junit"] # Optional
output_folder: "/Users/Downloads" # Optional
wait_for_finish: True # Optional
token: 777
cloud_url: "https://tests.com" # Optional
configurations:
  - name: Team A
    devices:
      # iOS
      - osVersion: iOS-16-4
        locale: ru_RU
        type: 'iPhone-11'
      # Android 
      - osVersion: 33
        locale: en_EN
        screen_resolution: SCREEN_480x320
        screen_density: DPI_320
    environment: # Optional
      ENV: value
    filters: # Optional
      include: ["Class1"]
      exclude: ["Method1"]
  - name: Team B
    devices:
      - osVersion: iOS-16-4

2. Save the configuration file wherever you like with any name and .yaml extension

3. Run you tests

emcee-cloud run -c path/to/your/config.yaml
Command-line flags#

Of course our CLI supports configuration flags

Config file and flags combination

You can combine config file with cli flags

In this case, the flag values will override the values from the config file

Common flags#
  • --cloud_url - Emcee.cloud URL (default "https://emcee.cloud")
  • -h, --help - help for emcee-cloud
  • --token - Emcee.cloud api token
  • -v, --version - version for emcee-cloud
Run command flags#
  • -c, --configPath - Path to emcee.cloud config file
  • -a, --app - App binary (Path/URL) which you want to test
  • -e, --envs - Comma separated envs ex.ENV1=value1,ENV2=value2
  • --os_version - Device's OS version (API level for Android). ex --os_version 34 --os_version iOS-17-0
  • -o, --output - Output folder for test run results. Default: current folder
  • --reports - Comma separated list of reports to be downloaded upon completion. ex:allure,junit
  • -r, --runner - [iOS] Path/URL to your test runner. [Android. Optional] Class name of your test runner
  • -t, --tests - Binary (Path/URL) with tests
  • -w, --wait_for_finish - Waiting for the tests to complete. Default: true
  • -h, --help - help for run command
Run command flags in Docker#

If you use CLI in docker, there are 2 configuration options available to you:

Direct CLI invocation#

You can call the CLI directly and pass all the required flags as usual

docker run avitotech/emcee-cloud-cli emcee-cloud --version

Run via ENTRYPOINT#

Alternatively, you can run the container through a standard ENTRYPOINT and pass the parameters as environment variables

docker run -e EMCEE_TOKEN=**** -e=EMCEE_APP_PATH=my/path avitotech/emcee-cloud-cli

All available environment variables are shown below:

  • EMCEE_CLOUD_URL
  • EMCEE_TOKEN
  • EMCEE_PLATFORM
  • EMCEE_CONFIG_PATH
  • EMCEE_APP_PATH
  • EMCEE_ENVS
  • EMCEE_DEVICE_OS_VERSION
  • EMCEE_OUTPUT_FOLDER
  • EMCEE_REPORTS
  • EMCEE_RUNNER
  • EMCEE_TESTS_APP_PATH
  • EMCEE_WAIT_FOR_FINISH

GitHub action#

We have Emcee.cloud action which you can add to your GitHub pipline.

This action encapsulates CLI and allows you to perform all actions that are available in CLI

GitLab Job#

You can use Job template below to connect Emcee in GitLab:

default:
  image: docker:24.0.5
  services:
    - docker:24.0.5-dind

run-test-with-emcee:
  image: avitotech/emcee-cloud-cli:{VERSION}
  script:
   - /entrypoint.sh
  variables:
    EMCEE_TOKEN : ${{ EMCEE_TOKEN }}
    EMCEE_PLATFORM : 'android'
    EMCEE_APP_PATH : 'https://emcee.cloud/api/v1/file/download/0786d961-93cb-4dc7-a9d5-443bd8922788#cloud_sample-debug.apk'
    EMCEE_DEVICE_OS_VERSION : 27
    EMCEE_REPORTS : allure
    EMCEE_OUTPUT_FOLDER: /builds/$CI_PROJECT_PATH
    EMCEE_TESTS_APP_PATH : 'https://emcee.cloud/api/v1/file/download/944a149a-b197-45b6-9f08-bd60afcfa94e#cloud_sample-debug-androidTest.apk'
  artifacts:
    paths:
      - /builds/$CI_PROJECT_PATH/*.zip

This template uses Emcee CLI Docker image, so configuration details can be found in the corresponding section

API and custom integrations#

You can also implement any custom integrations using our open API

Open API docs