Home

What is Emcee?

Emcee allows you to run iOS and Android tests on multiple machines. "Emcee" means master of ceremonies.

Android documentation available here.

At a Glance

Emcee starts a shared queue server daemon on a dedicated machine. Queue then starts worker daemons on all worker machines.

Workers use REST API to talk to the queue. They fetch buckets, run tests and send back the test results.

You use Emcee client to schedule jobs to execute tests, poll the queue for test results, and delete jobs when needed (e.g. when you cancel the build). Client will periodically print the state of your job and generate Junit report at the end.

Using Emcee

You will need:

• Computers: It does not make sense to run tests on a single local machine using Emcee unless you are planning to scale. Emcee uses SSH to deploy itself on remote machines. Set host names for your machines, or use LAN IP addresses when configuring Emcee.
• Build artifacts: you can generate ones using xcodebuild build-for-testing, buck build or using any other way
• Test Arg File: a JSON file that describes a job
• Queue Server Configuration File: a JSON file that describes how queue and workers operate
• Integrate Emcee with your test environment: do things like record and store video, upload test results to your test management system, et cetera and et cetera.
• Optional — HTTP server to store build artifacts: Emcee is a distributed system, multiple machines will require the same set of build artifacts to run tests locally, so there must be a way to store them in a shared place. You will need to upload your artifacts to your web server in ZIP archives, allowing Emcee workers to fetch them on demand. Only HTTP protocol is supported by now. Please read about URL Handling in Emcee to understand how Emcee accesses ZIP archives and how to authenticate if it is needed. Starting in version 16, Emcee has built-in HTTP server which should suit most of your needs.

Using CLI

To list all commands run:

$ Emcee help

The main command you'll need is runTestsOnRemoteQueue:

$ Emcee runTestsOnRemoteQueue -h

Glossary

• Queue - EmceeQueue process that provides jobs to the workers and load-balances them
• Worker daemon, worker - EmceeWorker process that manages simulators on a machine it's running on (local machine) and runs tests
• Test Arg File - a file that describes a single test plan, what tests to execute and what build artifacts to use
• Build artifacts - build results
• Test destination - a description of device which will run test. Emcee currently supports only iOS Simulators, so test destination is a pair of iOS version and simulator type, e.g. iPhone X iOS 11.3.
• Deployment destination - a single machine on which Emcee will deploy itself and spawn a worker or shared queue process; destination is a machine with an Emcee process.
• Destination configuration - a specific configuration for a destination. You may allocate more simulators on a more powerful machines and less simulators on less powerful machines.
• Termination policy - defines under what conditions Emcee queue will terminate itself. This is useful if you update Emcee: unused queues will eventually die.
• Test discovery - a process of obtaining class and method names from a xctest bundle.
• Queue server configuration - a set of settings that are applied to a newly started queue server. These settings are unchangeable after queue starts.