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:

• Build artifacts: you can generate ones using xcodebuild build-for-testing, buck build or using any other way
• 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 — a set of machines require to fetch build artifacts to run tests locally, so there must be a way to store them in a shared place
• Test Arg File: a JSON file that describes a job, or a test plan
• SSH: Emcee uses SSH to run itself on remote machines
• Set host names: Emcee uses hostname to identify local host name
• Computers: It does not make sense to run tests on a single local machine using Emcee unless you are planning to scale

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.
• Destination - a single machine on which Emcee will deploy itself and spawn a worker process; destination is a machine with a worker Emcee process.