org.evomaster.client.java.instrumentation.coverage.methodreplacement

Annotation Type Replacement

@Retention(value=RUNTIME)
 @Target(value=METHOD)
public @interface Replacement

Mark a static method as a replacement one for a method in the Java API. As boolean values and exceptions lead to fitness plateaus, we need testability transformations to give gradient, eg by creating new coverage targets, in which we want to return true and false.
A Replacement method MUST have the same return type, and match name/signature of replaced method, but last parameter being a String id template. However, if replacing a non-static method, then the replacement MUST still be static, and have as first parameter the caller.
If the id template is null, then no new target should be registered. However, we might still want to do taint analysis. This is the case when instrumenting third-party libraries.
In the case of TRACKER methods, no id template is used, as those will never be testing targets. Furthermore, the first parameter must always be of type Object if it is from a third-party library
For replacement in third-party libraries, use ThirdPartyMethodReplacementClass.

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
ReplacementCategory	category
ReplacementType	type There might be different reasons to replace a methods, like dealing with methods that return booleans, or might throw an exception

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	castTo Name of the class for which the return value of this method should be cast to.
String[]	extraPackagesToConsider Only applicable if UsageFilter is ONLY_SUT
String	id Give an id to this replacement method.
boolean	isPure Whether the method has side-effects.
String[]	packagesToSkip Method replacement will not be applied to classes in given prefix package.
boolean	replacingConstructor Specify if the target to replace is a constructor call, ie, using "new".
boolean	replacingStatic Specify if the target replaced method was static
UsageFilter	usageFilter Specify where the transformation can be applied.

Element Detail

type

public abstract ReplacementType type

There might be different reasons to replace a methods, like dealing with methods that return booleans, or might throw an exception

category

public abstract ReplacementCategory category

replacingStatic

public abstract boolean replacingStatic

Specify if the target replaced method was static

Default:

false

replacingConstructor

public abstract boolean replacingConstructor

Specify if the target to replace is a constructor call, ie, using "new". Note that constructors are handled very specially. Replacement must return void, and rather save the newly create instance locally. To avoid concurrency issue, should save it in a ThreadLocal. Such instance must then be returned in a static method with name same as what currently stored in MethodReplacementClass.CONSUME_INSTANCE_METHOD_NAME See further documentation there. Also, recall that most of these constraints are checked in ReplacementListTest For an explanation of why we do this, look at the comments in MethodReplacementMethodVisitor

Default:

false

id

public abstract String id

Give an id to this replacement method. This is used to then easily access the original replaced method via reflection

Default:

""

usageFilter

public abstract UsageFilter usageFilter

Specify where the transformation can be applied. Sometimes we might want transformations only in the SUT, or sometime only in the third-party libraries.

Default:

org.evomaster.client.java.instrumentation.coverage.methodreplacement.UsageFilter.ANY

isPure

public abstract boolean isPure

Whether the method has side-effects. This is important to check if we can call it more than once without worries of changing a state

Default:

true

castTo

public abstract String castTo

Name of the class for which the return value of this method should be cast to. This is necessary for 3rd-party replacements only.

Default:

""

packagesToSkip

public abstract String[] packagesToSkip

Method replacement will not be applied to classes in given prefix package. If it starts with a '.', then it is not treated as prefix (ie match anywhere in the package full name). This latter is useful when dealing with packages that are shaded

Default:

{}

extraPackagesToConsider

public abstract String[] extraPackagesToConsider

Only applicable if UsageFilter is ONLY_SUT

Default:

{}