Reference

Annotations

@AfterAll

The @AfterAll annotation marks a method in the control file as an 'after all' method. This method executes after all tests have executed. This method takes the list of journeys as its argument. The method must be a static method.

Definition
@Target(ElementType.METHOD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface AfterAll {

}	
Example Usage
@AfterAll
public static void after(List journeys){
    try {
        new ProcessBuilder("open", REPORTS_DIRECTORY.getAbsolutePath() + "/index.html").start();
    } catch (IOException e) {
        e.printStackTrace();
    }
}	

@BeforeAll

The @BeforeAll annotation marks a method in the control file as a 'before all' method. This method executes before the tests execute. This method takes the list of journeys as its argument. The method must be a static method.

Definition
@Target(ElementType.METHOD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface BeforeAll {

}	
Example Usage
@BeforeAll
public static void before(List journeys){

}	

@Clear

The @Clear annotation marks a method in the step file as a cleanup method. This method executes in journey order immediately prior to the teardown method.

Definition
@Target(ElementType.METHOD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Clear {  
      
}	
Example Usage
@Step 
public class OpenLandingPage { 
     @Clear 
     public void clear(){ 
         driver.close(); 
     } 
}	

@CompletenessLevel

The @CompletenessLevel annotation sets the completeness level for the test generator. The default level is Unrestricted. This annotation is not required.

Definition
@Retention(RetentionPolicy.RUNTIME) 
@Target(ElementType.TYPE) 
@Inherited 
public @interface CompletenessLevel {  
     Completeness value(); 
} 	
Example Usage
@RunWith(CascadeRunner.class) 
@Scan("uk.co.malbec.onlinebankingexample.steps") 
@CompletenessLevel(Completeness.STATE_COMPLETE) 
public class OnlineBankingTests {  
      
} 	

@Demands

The @Demands annotation marks a variable as being used by the file in which it is used. The variable and its value required to be defined elsewhere.

Definition
@Target(ElementType.FIELD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Demands {  
      
}	
Example Usage
@Step(OpenLandingPage.class) 
public class SuccessfulLogin { 
     @Demands 
     private WebDriver webDriver; 
} 	

@Factory

The @Factory annotations allows the user to override key components within Cascade in order to customise Cascade. An example is to disable the report generation.

Definition
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
public @interface Factory {
    Class[] value();
}   
Example Usage
@RunWith(CascadeRunner.class)
@Scan("com.github.robindevilliers.welcometohell.steps")
@Factory(DisableReporter.class)
public class WelcomeToHellTests {

}	

@FilterTests

The @FilterTests annotation specifies a filtering rule in the control file that the FilterStrategy will apply to the generated tests. This method is used to filter out unwanted tests for various purposes.

Definition
@Target(ElementType.FIELD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface FilterTests {  
      
}	
Example Usage
@RunWith(CascadeRunner.class) 
@Scan("uk.co.malbec.onlinebankingexample.steps") 
public class OnlineBankingTests { 
     @FilterTests 
     Predicate filter = or(withStep(Login.FailedLogin.class), withStep(Challenge.FailChallenge.class)); 
} 	

@Given

The @Given annotation marks the given method of a step file. This method is called during test construction in order to initialise variables the step file supplies.

Definition
@Target(ElementType.METHOD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Given {  
      
}	
Example Usage
@Step(OpenLandingPage.class) 
public class SuccessfulLogin {  
      
     @Supplies 
     private WebDriver webDriver; 
      
     @Given 
     public void given() {  
         webDriver = new FirefoxDriver();  
     }  
} 	

@Limit

The @Limit annotation restricts the test set to an arbitrary number of tests. This is really only used by developers who need to run the tests for a reason besides proving that the code works. Developing the tests or the continuous integration pipeline is a good example. It is applied to the control file.

@Target(ElementType.TYPE)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface Limit {
    int value() default 1;
}	
Example Usage
@RunWith(CascadeRunner.class)
@Scan("com.github.robindevilliers.welcometohell.steps")
@Limit(1)
public class WelcomeToHellTests {

}

@Narrative

The @Narrative annotation allows for each step to be given a human readable description. This description replaces the step name in the list of tests in the reports. It also forms part of the test synopsis, providing a 'narrative' for the journey within the test reports.

@Target(ElementType.TYPE)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface Narrative {
     String value();
}	
Example Usage
@Step(OpenLandingPage.class)
@Narrative("Start and go to gender page.")
public class OpenGenderPage {

} 	

@OnlyRunWith

The @OnlyRunWith annotation within a step file specifies a condition that should restrict the step's inclusion in a journey.

Definition
@Target(ElementType.FIELD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface OnlyRunWith {  
      
}	
Example Usage
@Step(Portfolio.class) 
public class OpenCurrentAccount {  
      
     @OnlyRunWith 
     Predicate predicate = or( 
         withStep(Portfolio.CurrentAndSaverAccounts.class), 
         withStep(Portfolio.CurrentAccountOnly.class), 
         withStep(Portfolio.AllAccounts.class) 
     ); 
} 	

@Parallelize

The @Parallelize annotation specifies on the control file how many tests to run in parallel when executing the test set.

@Target(ElementType.FIELD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface Parallelize {
    int value();
}	
Example Usage
@RunWith(CascadeRunner.class)
@Scan("com.github.robindevilliers.welcometohell.steps")
@Parallelize(3)
public class WelcomeToHellTests {

}

@Profile

The @Profile annotation specifies that the current control file should only execute under a certain profile. The profile is set by either an environment variable or java property.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited
public @interface Profile {
    String value();
    String name() default "CASCADE_PROFILE";
}	

The default property name is CASCADE_PROFILE but can be overridden using this annotation.

Example Usage
@RunWith(CascadeRunner.class)
@Scan("com.github.robindevilliers.welcometohell.steps")
@Profile("smoke")
public class WelcomeToHellTests {

}

In this way, you can have different control files that execute in different CI pipeline stages, or a different control file running on development machines. You could have an exhaustive weekend run of tests that you run overnight.

@ReEntrantTerminator

The @ReEntrantTerminator annotation specifies on a step file that the step file should act as a terminator to a journey once it exists a certain number of times in a journey. The default value is 1, meaning that this step file will terminate a journey once it appears for the second time in the journey.

Definition
@Target(ElementType.TYPE)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface ReEntrantTerminator {  
     int value() default 2; 
}	
Example Usage
@Step(Portfolio.class) 
@ReEntrantTerminator(1) 
public class OpenAccountPage {  
      
} 	

@Repeatable

The @Repeatable annotation specifies that the step file can be included in a test multiple times. By default, step files are only included once per test. This annotation is especially useful when used in conjunction with @SoftTerminator annotations in the creation of journeys that contain cycles.

Definition
@Target(ElementType.TYPE)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface Repeatable {
}	
Example Usage
@Step({EditAddress.class, EditEmail.class, EditMobile.class, OpenAccountPage.class, SetupStandingOrder.class})
@Repeatable
public class BackToPortfolioPage {

} 	

@Scan

The @Scan annotation specifies on the control file which packages should be scanned for step files.

Definition
@Target(ElementType.TYPE)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Scan {  
      
}	
Example Usage
@RunWith(CascadeRunner.class) 
@Scan("uk.co.malbec.onlinebankingexample.steps") 
public class OnlineBankingTests {  
      
} 	

@Setup

The @Setup annotation specifies a method within the control file that will be called after all the given methods specified in step files have been executed and immediately prior to the test being started. This method is intended to perform any actions necessary to prepare the subject application and supporting systems prior to a test.

Definition
@Target(ElementType.METHOD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Setup {  
      
}	
Example Usage
@RunWith(CascadeRunner.class) 
public class OnlineBankingTests { 
     @Setup 
     public void setup(){ 
         Client client = ClientBuilder.newBuilder().build(); 
     } 
} 	

@StateRenderingRule

The @StateRenderingRule annotation specifies a state renderer for use in serializing the current scope of fields for the html reporter.

Definition
@Target(ElementType.TYPE)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface StateRenderingRule {
     Class[] value();
}	
Example Usage
@RunWith(CascadeRunner.class)
@StateRenderingRule(ListOfStringsStateRendering.class)
public class OnlineBankingTests {

} 	

@Step

The @Step annotation marks a particular class or interface as one of the step files. Concrete implementations of step files define the parts of a journey.

Definition
@Target(ElementType.TYPE)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Step {  
     Class[] value() default Null.class; 
     public static class Null {} 
}	
Example Usage
@Step(Portfolio.class) 
public class OpenAccountPage {  
      
} 	

@StepHandler

The @StepHandler annotation on a control or step file denotes a handler class that will have its method executed between the When and Then methods.

Definition
@Target(ElementType.TYPE)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface StepHandler {  
     Class[] value(); 
}	
Example Usage
@RunWith(CascadeRunner.class) 
@StepHandler(WaitASecond.class) 
public class OnlineBankingTests {  
      
} 	

@StepPostHandler

The @StepPostHandler annotation on a control or step file denotes a handler class that will have its method executed after the Then method.

Definition
@Target(ElementType.TYPE)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface StepPostHandler {  
     Class[] value(); 
}	
Example Usage
@RunWith(CascadeRunner.class) 
@StepPostHandler(WaitASecond.class) 
public class OnlineBankingTests {  
      
} 	

@StepPreHandler

The @StepPreHandler annotation on a control or step file denotes a handler class that will have its method executed before the When method.

Definition
@Target(ElementType.TYPE)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface StepPreHandler {  
     Class[] value(); 
}	
Example Usage
@RunWith(CascadeRunner.class) 
@StepPreHandler(WaitASecond.class) 
public class OnlineBankingTests {  
      
} 	

@SoftTerminator

The @SoftTerminator annotation on a step file specifies that the step is a terminator for a cycle. A cycle is a set of steps that eventually links back on itself creating a loop. If Cascade were to execute this loop, the test would never end. Cascade does not allow these loops unless there is a @ReEntrantTerminator or @SoftTerminator step in the loop. These annotations tell Cascade when to stop. The @SoftTerminator marks the point in the cycle where processing should stop. What limits the length of a test in this case, as apposed to the @ReEntrantTerminator, is Cascade's general policy to include a step in a test only once. Care should be taken when defining steps in the loop in order to ensure that at least one step is not repeatable and is not a re-entrant or soft terminator.

Definition
@Target(ElementType.TYPE)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface SoftTerminator {
}	
Example Usage
@SoftTerminator
public class PortfolioPage {
} 	

@Supplies

The @Supplies annotation marks a variable that will be supplied by this control or step file for use by any file that demands that variable.

Definition
@Target(ElementType.FIELD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Supplies {
    Class stateRenderer() default Object.class;
    Class transitionRenderer() default Object.class;
}	

The @Supplies annotation has two properties. The stateRenderer property takes a StateRenderingStrategy implementation that serializes the current state of the field that is supplied for use in the html reports. The transitionRenderer does the same for a transition. It implements the TransitionRenderingStrategy, which has methods that supplies the original value and new value for the field this applies to. The renderer should serialise the transition into html. There are examples of this in the Cascade sources.

Example Usage
@Step(OpenLandingPage.class) 
public class SuccessfulLogin {  
     @Supplies 
     private String username; 
} 	

@Teardown

The @Teardown annotation marks a method in the control file that is executed at the very end of a test. It is intended to contain any final cleanup code.

Definition
@Target(ElementType.METHOD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Teardown {  
      
}	
Example Usage
@RunWith(CascadeRunner.class) 
public class OnlineBankingTests {  
     @Teardown 
     public void teardown(){  
         client.close() 
     } 
} 	

@Terminator

The @Terminator annotation marks a step as a terminating step. Once the step file is encountered in a journey, the journey will stop. It is not necessary to specify a terminator as a step without a following step is naturally an implicit terminator. This annotation overrides any step associations.

Definition
@Target(ElementType.TYPE)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Terminator {  
      
}	
Example Usage
@Step(Portfolio.class) 
@Terminator 
public class FailedLogin {  
      
} 	

@Then

The @Then annotation marks a method in a step as a Then method. This method is expected to perform any validation that is necessary to ascertain that the application under test has reached a certain State. For This reason, the Then method is the artefact that is used to model States or Scenarios within Cascade. When Scenario Complete completeness level is used to generate test journeys, it is the Then methods which are the primary driver for bounding the test set, so the every test method is included. Then method that this annotation decorates must accept no parameters. Otherwise, it should be public, non-static and return void.

Definition
@Target(ElementType.METHOD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface Then {
     String Null = ""; 
} 	
Example Usage
@Step(OpenLandingPage.class) 
public class SuccessfulLogin {  
     @Then 
     public void then() {  
         assertElementPresent(webDriver, "[test-form-challenge]");  
     }  
} 	

@TransitionRenderingRule

The @TransitionRenderingRule annotation specifies a transition renderer for use in serializing the current scope of fields for the html reporter. Classes that implement a transition renderer must implement the TransitionRenderingStrategy interface.

Definition
@Target(ElementType.TYPE)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface TransitionRenderingRule {
     Class[] value();
}
Example Usage
@RunWith(CascadeRunner.class)
@TransitionRenderingRule(StandingOrderTransitionRendering.class)
public class OnlineBankingTests {

} 	

@When

The @When annotation marks a method in a step as a When method. This method is expected to perform any action that exercises the subject application. It is the When method that is the artefact that is used to define the bounding set for tests when Transition Complete comnpleteness is specified. The method that the annotation decorates must accept no arguments, be public and return void. It must also not be static.

Definition
@Target(ElementType.METHOD)  
@Inherited  
@Retention(RetentionPolicy.RUNTIME)  
public @interface When {
     String Null = ""; 
} 	
Example Usage
@Step(OpenLandingPage.class) 
public class SuccessfulLogin {  
     @When 
     public void when() {  
         enterText(webDriver, "[test-field-username]", username); 
         enterText(webDriver, "[test-field-password]", password); 
         click(webDriver, "[test-cta-signin]"); 
         waitForPage(webDriver); 
     }  
}

Static Fields

REPORTS_BASE_DIRECTORY

The REPORTS_BASE_DIRECTORY static field is used by the HtmlReporter as an output directory for the generated html reports. It can be overridden by the control file by supplying it. The default value is './build/reports/tests/cascade'. The field must be static.

Example Usage
@Supplies
static File REPORTS_BASE_DIRECTORY = new File("./reportsOutput");

REPORTS_DIRECTORY

The REPORTS_DIRECTORY static field is generated and supplied by the HtmlReporter as the actual location for the html reports for the current test run. It can be demanded by the control file in order to do something with it. This might mean passing it to the CI server so that the report can be retained.

Example Usage
@Demands
static File REPORTS_DIRECTORY;

Filter Predicates

All standard predicates are supplied by static factory methods on the Predicates class.

and

This predicate returns true all enclosed predicates return true. False otherwise.

Example Usage
@FilterTests
Predicate filter = and(stepAt(0, OpenLandingPage.class), stepAt(1, Login.FailedLogin.class));

not

This predicate returns true the enclosed predicate returns false. False otherwise.

Example Usage
@FilterTests
Predicate filter = not(stepAt(1, Login.FailedLogin.class));

or

This predicate returns true any enclosed predicates return true. False otherwise.

Example Usage
@FilterTests
Predicate filter = or(stepAt(1, Login.SuccessfulLogin.class), stepAt(1, Login.FailedLogin.class));

stepAt

This predicate returns true if the journey contains the class specified at the specific index. The index starts at zero. False otherwise.

Example Usage
@FilterTests
Predicate filter = stepAt(1, Login.FailedLogin.class);

stepIsCoupledWith

This predicate returns true if the journey contains the two step files specified, where the first step file is eventually followed by the second. If the condition is false, the predicate returns false.

Example Usage
@FilterTests
Predicate filter = stepIsCoupledWith(Portfolio.SavingsAccountOnly, Account.OpenSavingsAccount.class);

withStep

This predicate returns true if the journey contains the class specified. False otherwise.

Example Usage
@FilterTests
Predicate filter = withStep(Login.FailedLogin.class);