Instrumentation

Added in 7.2.0

interface Instrumentation

Options to register asm class visitors and to configure the instrumentation process.

Summary

Public functions
Unit

Sets the frame computation mode that will be applied to the bytecode of the classes instrumented by ASM visitors registered through transformClassesWith.
Unit
<ParamT : InstrumentationParameters> transformClassesWith(
    classVisitorFactoryImplClass: Class<AsmClassVisitorFactory<ParamT>>,
    scope: InstrumentationScope,
    instrumentationParamsConfig: (ParamT) -> Unit
)

Registers an asm class visitor to instrument the classes defined by the given scope.

Public properties
SetProperty<String>

The set of glob patterns to exclude from instrumentation.

Public functions

setAsmFramesComputationMode

Added in 7.2.0
fun setAsmFramesComputationMode(mode: FramesComputationMode): Unit

Sets the frame computation mode that will be applied to the bytecode of the classes instrumented by ASM visitors registered through transformClassesWith. The default mode is to copy frames.

When setting this multiple times, the mode with the highest enum value will be selected.

transformClassesWith

Added in 7.2.0
fun <ParamT : InstrumentationParameters> transformClassesWith(
    classVisitorFactoryImplClass: Class<AsmClassVisitorFactory<ParamT>>,
    scope: InstrumentationScope,
    instrumentationParamsConfig: (ParamT) -> Unit
): Unit

Registers an asm class visitor to instrument the classes defined by the given scope. An instance of the factory will be instantiated and used to create visitors for each class.

Example:

androidComponents {
    onVariants(selector().all(), {
        instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                             InstrumentationScope.Project) { params ->
            params.x = "value"
        }
        instrumentation.setAsmFramesComputationMode(COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS)
    })
}
Parameters
classVisitorFactoryImplClass: Class<AsmClassVisitorFactory<ParamT>>

the factory class implementing AsmClassVisitorFactory
scope: InstrumentationScope

either instrumenting the classes of the current project or the project and its dependencies
instrumentationParamsConfig: (ParamT) -> Unit

the configuration function to be applied to the instantiated InstrumentationParameters object before passed to AsmClassVisitorFactory.createClassVisitor.

Public properties

excludes

Added in 7.2.0
val excludes: SetProperty<String>

The set of glob patterns to exclude from instrumentation. Classes matching any of these patterns in the project sources and dependencies jars do not get instrumented by any AsmClassVisitorFactory registered via transformClassesWith.

Do not add the file extension to the end as the filtration is done on compiled classes and the .class suffix is not included in the pattern matching.

Example usage:

androidComponents {
    onVariants(selector().all(), {
        instrumentation.excludes.add("com`/`example`/`donotinstrument`/`**")
        instrumentation.excludes.add("**`/`*Test")
    })
}