TraceEventConsumersRule

Allows tests to create and register a TraceEventConsumer that can be used to verify whether a trace event was generated during a test.

After a test finishes, all the registered TraceEventConsumer instances are automatically unregistered.

The created TraceEventConsumer instances are MockK mocks. As such the MockK verification features can be used to verify whether a trace event is generated during a test. However, as trace event processing is asynchronous, the test needs to wait until the event is processed. To do that the verifyWithTimeout function must be used instead of MockK's verify function directly. It uses the verify function under the hood with a default timeout suitable to allow the event processing to take place.

For trace events that are guaranteed to be sent from the local process, localProcessOnly can be set to true in createTraceEventConsumer or registerTraceEventConsumer. This allows the consumer to be immediately verified after Espresso is idle, and as a result also allows verifying that trace events were not sent.

The preferred way to verify that a specific event has been generated is by using a type-safe TraceEventConsumer, as this prevents the test to break when code is refactored and allows event arguments to be matched with MockK's argument matchers like: any(). A type-safe instance can be created by defining/using an interface that extends both the trace event listener interface and the TraceEventConsumer interface. For example, when FooEvents is defined like:

interface FooEvents : TraceEventListener {
    fun bar(randomValue: Int, testableAnswer: Int)
}

to create the type-safe TraceEventConsumer mock you need to define FooEventsConsumer as:

interface FooEventsConsumer : FooEvents, TraceEventConsumer

Next, the mock can be used in a test like:

class FooTest : IviFunctionalTestCase {

@Test
fun someTest() {
    val fooEventsConsumer = createTraceEventConsumer<FooEventsConsumer>()

    // Trigger something here that generates the `bar` event.
    ...

    verifyWithTimeout { fooEventsConsumer.bar(any(), 42) }
}

In the above example, the test will wait until a bar event with second argument set to 42 is generated.

Events can be consumed from all processes when the IviApplication is used as Application class. For integration tests that do not use it, only the trace events from the main process are consumed.

Only trace events of which all arguments can be written to a Parcel can be consumed when the IviApplication is used.