Home

What is Emcee?

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

How does it work?

Emcee starts a daemon on a dedicated machine, it behaves like a shared queue server, or simply queue. Queue then starts daemons on all worker machines, let's call them the workers.

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

Queue clients are also Emcee processes, they schedule jobs tests to execute, poll the queue for test results, and delete jobs when needed (e.g. when you cancel the build).

How to start 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. SSH is also requirement: Emcee uses SSH to deploy itself on remote machines
• Integrate Runtime Dump: this allows you and Emcee to query xctest bundle for all available tests in it
• HTTP server to store build artifacts: Emcee is a distributed system — multiple machines would require to fetch 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 on this web server, so Emcee will be able to fetch them as needed. 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
• Set host names: Emcee uses hostname to identify local host name
• Queue Server Configuration File: a JSON file that describes how queue and workers operate
• Queue Server Destination File: a JSON file that describes where to start a shared queue as well as where to look for already running shared queue instance
• Integrate Emcee with your test environment: do things like record and store video, update test results, et cetera and et cetera.

To run test invoke:

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

Glossary

• Queue - EmceeQueue process that provides jobs to the workers and load-balances them
• Worker - EmceeWorker process that manages simulators on a 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.
• Queue server configuration, or Queue server run configuration - a set of settings that are applied to a newly started queue server. These settings are unchangeable after queue starts.