AdviceTracer

AdviceTracer is a tool for testing pointcut descriptors.

Installation

Download the latest version. Put it in your classpath and in the aspect path of the project you want to test.

Writing test cases

Given this Java class C:

public class C {
  public void m1() { ... }
  public void m2() {
    ...
    m1();
  }
}

And this AspectJ aspect A:

public aspect A {
  @AdviceName("A1")
  before(): execution(void C.m1()) && cflow(execution(void C.m2()) {
    ...
  }
}

The advice "A1" is executed before each execution of "m1" that is in the control flow of "m2". So it has a dynamic pointcut descriptor (PCD), i.e. we can only know at runtime if the advice is executed or not.

The following test class uses AdviceTracer to specify the PCD of advice "A1":

public class Test {
  @Test
  public void test1() {
    C c = new C();
    addTracedAdvice("A1");
    setAdviceTracerOn();
    c.m1();
    setAdviceTracerOff();
    assertAdviceExecutionsEquals(0);
  }

  @Test
  public void test2() {
    C c = new C();
    addTracedAdvice("A1");
    setAdviceTracerOn();
    c.m2();
    setAdviceTracerOff();
    assertAdviceExecutionsEquals(1);
    assertExecutedAdviceAtJoinpoint("A1","C.m1:2");
}

The "addTracedAdvice" method adds an advice to the list of traced advices. Only the advices in this list are traced, others are ignored, so a test case is not affected by changes made to the PCDs of the other advices. If the list is empty then all advices are traced.

The "setAdviceTracerOn()" must be called to start tracing the advice execution. To stop tracing, "setAdviceTracerOff()" must be called. All the execution of the advices specified earlier are traced between the calls to these two methods.

The assertion "assertAdviceExecutionsEquals" passes if the number of traced advice executions is equals to the integer paramater. The assertion "assertExecutedAdviceAtJoinpoint" passes if the specified advice has been executed at the specified joinpoint.

The following sequence diagrams shows details the behavior of AdviceTracer during the execution of "test2":

AdviceTracer primitives

• setAdviceTracerOn():

• Starts the tracing of advices.
  
• setAdviceTracerOff():
  Stops the tracing. The calls to the methods under test should occur between the calls to setAdviceTracerOn and setAdviceTracerOff.
• addTracedAdvice(String advice):
  Adds the specified advice to the collection of traced advices.
• setTracedAdvices(Collection<String> advices):
  Sets the collection of traced advices. If the collection is empty (which is true by default), all the advices are traced. Otherwise only specified advices are traced.
  

AdviceTracer assertions

• assertAdviceExecutionEquals(int n):
  Passes if the number of traced advices executions equals to n.
• assertExecutedAdvice(String advice):
  Passes if the specified advice has been executed.
• assertExecutedAdviceAtJoinpoint(String advice, String joinpoint):
  Passes if the specified advice has been executed at the specified joinpoint.

Advice and joinpoint strings

Advice and joinpoints are specified using strings. The string for the advice is its name, specified using the @AdviceName annotation.

The string for the joinpoint is the qualified name of the method where it is located, followed by the ':' character and the line number where it is located. Example: "package.Class.method:34".