skip to content

In TestNG, what can an IAnnotationTransformer and an IMethodInterceptor change about a run, and why is a transformer in @Listeners ignored?

level: middleimportance: should knowfreq 40%

answer

  1. rewrite versus reorder
  2. before parsing versus before invoking
  3. setRetryAnalyzer on ITestAnnotation
  4. @Listeners is itself an annotation

basics

~10 s

IAnnotationTransformer rewrites annotation values, such as a @Test's retryAnalyzer or enabled flag, while TestNG parses classes; IMethodInterceptor reorders, filters or adds independent methods before they run. @Listeners is read too late for a transformer.

solid answer

~40 s

An `IAnnotationTransformer` changes annotation values: its `transform(ITestAnnotation, Class, Constructor, Method)` can call setters like `setRetryAnalyzer`, `setEnabled` or `setInvocationCount`, and overloads cover configuration, `@DataProvider`, `@Factory` and `@Listeners` annotations. That is the usual way to give every test a retry analyzer without editing it. An `IMethodInterceptor.intercept(List<IMethodInstance>, ITestContext)` receives the methods that have no dependencies and returns the list to run, reordered, shorter or longer. A transformer must be known before TestNG reads any annotation, and `@Listeners` is itself an annotation, so TestNG's documentation says one declared there is ignored. Register it in `testng.xml`, with `-listener` or in code. Only one transformer is active at a time.

code

java · 14 lines
java
import java.lang.reflect.Constructor;
import java.lang.reflect.Method;
import org.testng.IAnnotationTransformer;
import org.testng.annotations.ITestAnnotation;

public class RetryEverywhereTransformer implements IAnnotationTransformer {
  @Override
  public void transform(ITestAnnotation annotation, Class testClass,
                        Constructor testConstructor, Method testMethod) {
    if (testMethod != null) {
      annotation.setRetryAnalyzer(OneRetry.class);
    }
  }
}

go deeper

for a junior

Remember that a transformer edits annotation values and an interceptor edits the list of methods to run. Know that a transformer goes in testng.xml, not @Listeners.

for a middle

Explain the timing: transformers act while annotations are parsed, interceptors just before invocation, and why that makes @Listeners useless for a transformer.

for a senior

Diagnose a blanket retry that never fires because of @Listeners, two libraries whose transformers replace each other, and an interceptor that cannot see dependent methods.

for a principal

Weigh global rewriting against explicit annotations: a transformer hides policy from anyone reading the test, so decide who owns it and how its effect is made visible.

## Two listeners that change the run Most TestNG listeners only observe. Two change what TestNG will execute, and they act at different moments: | | `IAnnotationTransformer` | `IMethodInterceptor` | |---|---|---| | Acts on | annotation values read from your classes | the list of test methods about to run | | When | while TestNG parses annotations, before it builds its plan | right before TestNG starts invoking the methods of a `<test>` | | Signature | `transform(ITestAnnotation annotation, Class testClass, Constructor testConstructor, Method testMethod)` and overloads | `List<IMethodInstance> intercept(List<IMethodInstance> methods, ITestContext context)` | | Typical use | add a retry analyzer everywhere, disable tests, change `invocationCount` | reorder, filter or multiply the runnable methods | | Registered via `@Listeners` | ignored | works | ## IAnnotationTransformer An **annotation transformer** gets a mutable view of each annotation. For `@Test` the view is an `ITestAnnotation` with setters such as `setEnabled`, `setInvocationCount` and `setRetryAnalyzer`; only one of `testClass`, `testConstructor` and `testMethod` is non-null, telling you where the annotation was found. Further overloads receive configuration annotations (`IConfigurationAnnotation`), `@DataProvider`, `@Factory` and `@Listeners`. Its best-known use is the "retry everywhere" trick: a transformer calls `annotation.setRetryAnalyzer(MyRetry.class)` so no `@Test` needs editing. Other uses: - disabling a list of quarantined tests from configuration without touching the source; - raising `invocationCount` for a soak run; - adding a group to every method of a package. **Registration is the trap.** TestNG has to know about the transformer before it reads any annotation, and `@Listeners` is itself an annotation. The documentation says a transformer declared there is **ignored**. Supported paths: 1. `<listeners>` in `testng.xml`; 2. the `-listener` option of the `org.testng.TestNG` runner; 3. `TestNG.addListener(...)` when running programmatically; 4. a ServiceLoader file, `META-INF/services/org.testng.ITestNGListener`, because discovered listeners are installed through the same start-up path. TestNG holds **one** annotation transformer at a time: registering a second, different one logs `AnnotationTransformer already set` and the later one replaces the earlier. Two teams each shipping a transformer therefore do not compose; one of them stops applying, with only a warning in the log. ## IMethodInterceptor A **method interceptor** receives the list of methods that are free to run in any order and returns the list TestNG should run, in the order TestNG will run them. Its Javadoc says: - only methods that have **no dependents and depend on no other test method** are passed in, so methods chained with `dependsOnMethods` keep their dependency order and are not offered; - the returned list may be the same list reordered, a **smaller** list (filtering) or a **bigger** one; - the `ITestContext` argument lets it store attributes for later reporting. Typical uses are running a "fast" group first, running a shard of methods by hash, or putting recently failed tests at the front. Because it works on `IMethodInstance` objects, it can read each method's annotation and groups to decide: ```java public List<IMethodInstance> intercept(List<IMethodInstance> methods, ITestContext context) { List<IMethodInstance> fastFirst = new ArrayList<>(); List<IMethodInstance> rest = new ArrayList<>(); for (IMethodInstance m : methods) { List<String> groups = Arrays.asList(m.getMethod().getGroups()); (groups.contains("fast") ? fastFirst : rest).add(m); } fastFirst.addAll(rest); return fastFirst; } ``` Unlike a transformer, an interceptor can be declared with `@Listeners`, because it acts long after annotations have been read. A transformer, for its part, must check where the annotation came from: when `@Test` sits on a class, `transform` receives `testClass` with `testMethod` null, so a transformer that acts only when `testMethod` is non-null leaves class-level annotations alone. ## Choosing between them - To change **what a test is** (its retry analyzer, whether it is enabled, how many times it runs), use a transformer. - To change **which tests run, and in what order**, use an interceptor. - Both are global: a transformer sees every annotation in the run, and an interceptor sees every independent method of each `<test>` element. Write them defensively and keep them cheap. ## Mistakes to avoid - Declaring a transformer with `@Listeners` and concluding the retry analyzer "does not work". - Using an interceptor to enforce ordering between methods that share state; dependent methods are not passed to it. - Expecting two transformers to apply in sequence.

  • Two shared libraries in one TestNG run each register an IAnnotationTransformer in testng.xml. What happens?
    TestNG keeps a single annotation transformer. Registering a second, different one logs `AnnotationTransformer already set` and the later one replaces the earlier, so only one library's changes apply. Combine them into one transformer that delegates to both.
  • Why does a TestNG IMethodInterceptor not see methods linked by dependsOnMethods?
    Its Javadoc says only methods with no dependents and no dependencies are passed in. Dependent methods run in the order their dependency graph dictates, so the interceptor can reorder and filter only the free ones.

  • @Listeners is the right place for an IAnnotationTransformer
  • IMethodInterceptor can reorder methods chained with dependsOnMethods
  • Several transformers in one run apply one after another
  • An interceptor can only reorder, never drop or add methods
  • IAnnotationTransformer runs after each test method finishes