Home

What is Emcee?

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

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.
• 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, making Emcee workers able to fetch them as needed. HTTP protocol is only supported by now. Also, read about URL Handling in 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, or a test plan
• 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.

To run test invoke:

$ Emcee runTestsOnRemoteQueue \ 
      --queue-server-configuration-location http://example.com/queue_config.zip#config.json \
      --test-arg-file /path/to/testargfile.json \
      --temp-folder /path/to/temp_folder

Using CLI

To list all commands run:

$ Emcee help

To list all command arguments, run:

$ Emcee help --command <command_name>

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.