Skip to content

Runtime Dump

Jump to bottom
Vladislav Alekseev edited this page Sep 21, 2021 · 9 revisions

About Runtime Dump

Runtime dump acts like a bridge between Emcee and xctest bundle. Integrating runtime dump is important step, without it, Emcee won't be able to execute tests.

This is a hack, but it feels like the only way to execute iOS simulator code on a Mac.

How does it work?

Emcee starts a test bundle with some non-existing test case, so no actual test run will be performed. Test bundle loads its "entry point". Emcee passes an environment variable to a file where runtime dump should be stored. Entry point reads that environment, iterates over all ObjC runtime classes and dumps this list into a given file.

Runtime Dump Types

Depending on your xctest source code you may be able to execute runtime dump in logic test mode or in application test mode. The latter requires you to provide application bundle.

The runtime dump type is defined by build artifacts xcTestBundle key.

  • Runtime dump in logic test mode does not require simulator environment. Usually it is fast to perform. It is advised to attempt to use it first.

  • Runtime dump in application test mode requires simulator environment. Thus, simulator will be booted in order to launch non-existing test and trigger entry point. This is slower than running logic test mode.

If you want to perform logic test runtime dump, but it fails to dump, you may need to convert your xctest bundle to be logic tests bundle.

What to Dump?

Runtime dump entry point is expected to dump a list of DiscoveredTestEntry objects, describing all available tests in test bundle.

Ready to Use Implementation

Emcee provides a ready to be used sample implementation of the runtime dump. It is available here:

https://github.com/avito-tech/Emcee/tree/master/Samples/RuntimeDump

You will need to include these source files in your test target or link against a framework with these files, and add NSPrincipalClass key into your test's Info.plist file with "PrincipalClass" string value.

We advise to create a dynamic framework target with runtime dump and link your test bundle with that framework. You can debug entry point by setting breakpoint in its initializer and triggering any test from Xcode IDE. Debugger should stop at the breakpoint. If it does not stop, check console output for any warnings related to entry point class name.

There is a sample project that demonstrates how to integrate runtime dump feature into logic, application and UI test targets. It is available here.

  • Main app does not depend on anything

  • All test targets depend on RuntimeDumpSupport target, which is a dynamic framework with entry point

  • All test target plists define NSPrincipalClass key

Runtime dump cache

In order to reduce number of runtime dump actions on Emcee workers we advise to use cache server to store runtime dump results. User guide is here.

Clone this wiki locally