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 send back the test results.

Queue clients are also Emcee processes, they schedule jobs to execute (tests), 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. Do 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
• 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, upload test results to your test management system, et cetera and et cetera.

To run test invoke:

$ Emcee runTestsOnRemoteQueue \ 
      --emcee-version "900" \
      --job-id "YourJobId" \
      --queue-server-destination shared_queue_deployment_destinations.json \
      --queue-server-run-configuration-location http://example.com/queue_config.zip#config.json \
      --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.
• Test discovery - a process of obtaining class and method names from a xctest bundle.
• Queue server run configuration - a set of settings that are applied to a newly started queue server. These settings are unchangeable after queue starts.