AludraTest User Guide

Basic Usage

Base Requirements

For using AludraTest, each test class must

extend the class org.aludratest.AludraTestCase and
mark each test method with an annotation of type org.aludratest.testcase.Test

A minimal test case would be:

import org.aludratest.AludraTestCase;
import org.aludratest.testcase.Test;

public class MyTestClass extends AludraTestCase {

  @Test
  public void myTestMethod() {
  	logInfo("myTestMethod was called");
  }
}

Set-up and tear-down methods

Often, certain functionality has to be invoked before (set-up) or after (tear-down) test execution. This can be achieved by putting relevant code into particular methods. Such methods have the following requirements:

be public
do not be static
have return type void
have a @Before (set-up) or @After (tear-down) annotation

Any test class may have several methods marked with @Before or @After, also inherited methods are executed.

If a test class has several test methods, each @Before method is called before each test method and each @After method after each test method.

Example:

import org.aludratest.testcase.After;
import org.aludratest.testcase.AludraTestCase;
import org.aludratest.testcase.Before;
import org.aludratest.testcase.Test;

public class MyTestClass extends AludraTestCase {

  @Before
  public void setUp() {
      System.out.println("setUp()");
  }

  @After
  public void tearDown() {
      System.out.println("tearDown()");
  }

  @Test
  public void myTestMethod() {
  	logInfo("myTestMethod was called");
  }
}

Parameterization of tests

Test methods can have parameters to receive test data from files, e.g. an Excel sheet. For this purpose the annotation org.aludratest.testcase.data.Source can be used.

There are two different ways to apply the annotation: To a method or to method parameters.

Method Data Source

When applied to a method, each column of the data source is mapped to the primitive-typed method parameter of the same index:

import org.aludratest.testcase.AludraTestCase;
import org.aludratest.testcase.data.Source;
import org.aludratest.testcase.Test;

@Parallel
public class MyTestClass extends AludraTestCase {
	
  @Test
  @Source(uri="testSource.xls", segment="sheet1")
  public void testActivityLogic(Date date, int value) {
  	logInfo("test data: " + date + ", " + value);
  }
}

Parameter Data Source

Alternatively a data dource can be applied to a method parameter of JavaBean type. Then, data source column names are mapped to JavaBean properties. Even recursive JavaBean graphs can be constructed from a data source like an Excel sheet:

import org.aludratest.testcase.AludraTestCase;
import org.aludratest.testcase.data.Source;
import org.aludratest.testcase.Test;

@Parallel
public class MyTestClass extends AludraTestCase {
	
  @Test
  public void testActivityLogic(@Source(uri="testSource.xls", segment="sheet1") TestData data) {
  	logInfo("test data: " + data);
  }
}

A sample Excel sheet content:

name   child.name
parent child1
parent child2

The TestData class may be defined like this:

public class TestData {
   private String name;
   private Child child;
   
   public String getName() {
       return this.name;
   }
   
   public void setName(String name) {
       this.name = name;
   }
   
   public Child getChild() {
       return this.child;
   }
   
   public void setChild(Child child) {
       this.child = child;
   }
}

with the Child class:

public class Child {
   private String name;
   
   public String getName() {
       return this.name;
   }
   
   public void setName(String name) {
       this.name = name;
   }
}

Remember that the data classes must comply to JavaBeans conventions:

Have a public default constructor (or none at all)
Provide getter and setter methods for each property

Controlling Test Concurrency

On the lowest level, a test method may be annotated with the annotation org.aludratest.testcase.Parallel to allow for concurrent test execution or with org.aludratest.testcase.Sequential to forbid it. If no such annotation is applied, concurrency characteristics are inherited from the test class or an outer test suite (or suite hierarchy). Each of the elements, suite, class and test method support these concurrency annotations. If no annotation was specified at all, it is assumed that concurrent execution of all tests is allowed.

Example:

import org.aludratest.testcase.AludraTestCase;
import org.aludratest.testcase.Parallel;
import org.aludratest.testcase.data.Source;
import org.aludratest.testcase.Test;

@Parallel
public class MyTestClass extends AludraTestCase {

  @Test
  @Source(uri="testSource.xls", segment="sheet1")
  public void testActivityLogic(TestData data) {
  	logInfo("test data: " + data);
  }
}

Defining test suites

A test suite is defined as an empty Java classes with a org.aludratest.Suite annotation which lists the suite components. Each suite component may be a simple test class or a suite itself. Thus, suite structures can be nested arbitrarily deeply.

Example:

import org.aludratest.junit.AludraTestJUnitSuite;

@AludraTestJUnitSuite({ MyTestClass.class, MyOtherTestClass.class })
public class MyTestSuite {
}

As mentioned before, suite classes can be annotated with org.aludratest.testcase.Parallel or org.aludratest.testcase.Sequential to control execution concurrency of their components:

import org.aludratest.Parallel;
import org.aludratest.Suite;

@Suite({ MyTestClass.class, ActivityLogic2.class })
@Parallel
public class MyTestSuite {
}

Starting a Test Case or Suite in Eclipse

In order to start tests in Eclipse, a generic 'Eclipse run configuration' needs to be defined. This is a one-time-effort, after which you can execute any test with this generic configuration.

Creating a Run Configuration

Open the Eclipse Run Configurations dialog
Create a new "Java Application" run configuration
Change the name to "AludraTest"
As project, select your client project which contains the test class(es)
As main class, select org.aludratest.app.AludraSuiteRunner
Select the "Arguments" tab
In the text area "Program arguments", enter ${resource_path}
Click "Run"

Now the test class is executed. Please note that the test class must be the active editor in Eclipse when you click on "Run".

(Re)using the run configuration

You can reuse this single run configuration to run any individual test: Select the test class in the Package Explorer, then click the triangle on the right of the "Run" button and click "AludraTest" in the appearing list.

Creating an eclipse Run Configuration with JUnit

Testcases can be executed locally with the use of JUnit functions in Eclipse. Follow the guideline below:

Create a class AludraJUnitTest.java in your project

package com.acme.mytests.junit;

import org.aludratest.junit.AludraTestJUnitSuite;
import org.junit.runner.RunWith;

@RunWith(AludraTestJUnitSuite.class)
public class AludraJUnitTest {
}

Create a JUnit run configuration which executes exactly this class. Add this as a VM argument on the second tab:

-Dsuite=${resource_path}

Now you can reuse this single run configuration to run any individual test: Select the test class in the Package Explorer, then click the triangle on the right of the "Run" button and click "AludraTest" in the appearing list.

Executing a Test Case or Suite in Maven

TODO

Configuring AludraTest

AludraTest has a complex configuration engine. Most settings have a default value, so you do not have to configure anything to run your first tests. But if you plan to e.g. run web application tests using Selenium, you will definitely have to configure something.

For general information about the configuation engine, see Service Configuration.

For specific information about the configuration options for AludraTest or components of AludraTest, see AludraTest Services.

Advanced Topics

Excel Collection Mapping

Example Model

Imagine a DataClass model with the classes Country, State and City, interrelated with Java collections:

DataClasses

The model above is implemented with the following classes:

public class CountryData extends Data {
	
   private String id;
   private String name;
   private List<StateData> states = new ArrayList<StateData>();

   public String getId() {
       return id;
   }

   public void setId(String id) {
       this.id = id;
   }

   public String getName() {
       return name;
   }

   public void setName(String name) {
       this.name = name;
   }

   public List<StateData> getStates() {
       return states;
   }

   public void setStates(List<StateData> states) {
       this.states = states;
   }
}

public class StateData extends Data {

   private String id;
   private String name;
   private List<CityData > cities = new ArrayList<CityData >();

   public String getId() {
       return id;
   }

   public void setId(String id) {
       this.id = id;
   }

   public String getName() {
       return name;
   }

   public void setName(String name) {
       this.name = name;
   }

   public List<CityData > getCities() {
       return cities;
   }

   public void setCities(List<CityData > cities) {
       this.cities = cities;
   }
}

public class CityData extends Data {

   private String name;

   public String getName() {
       return name;
   }

   public void setName(String name) {
       this.name = name;
   }
}

Excel Sheet Mapping

Data of such a recursive collection mapping can be represented in Excel documents in the following manner:

Create a 'country' tab with columns 'id', 'name' and 'states'
In the country tab, create one row for each country, entering id and name data as usual
For each country create a dedicated Excel tab that contains all states of the country, e.g. named 'states_de', with the columns 'id', 'name' and 'cities'
In the country tab, declare the tab name containing the related data, entering 'tab:' followed by the tab name in the 'states' cell
In the states tab, create one row for each state in the related country and create cities tabs for enumerating the cities

Excel Sheet Example

As an example one can map the following hierarchy

Germany           (Country)
+- Bayern         (State)
|  +- München     (City)
|  +- Regensburg  (City)
+- Hessen         (State)
  +- Kassel      (City)
  +- Wiesbaden   (City)

Italy             (Country)
+- Veneto         (State)
|  +- Verona      (City)
|  +- Venezia     (City)
+- Lomabardia     (State)
  +- Milano      (City)
  +- Bergamo     (City)

using this Excel document structure (having all the tabs in the same Excel document):

Data Consumption in a Test Case

When consuming this data in an AludraTest method like this:

@Test
public void testInbound(@Source(uri =  "country.ent.xls", segment = "countries") CountryData country) {
   System.out.println(country.getName());
}

The test method is executed twice, once with country Germany, once with country Italy having them wired with all their states and cities.

Skipping initial Rows in an Excel Sheet

When certain data sets of an Excel sheet require further examination, one can temporarily configure the test method to skip the first n rows, applying the annotation org.aludratest.annotations.test.Offset to the test method, for example for skipping the first 5 data rows:

@Test
@Offset(5)
public void test(@Source(uri = "myfile.ent.xls", segment = "mytab") MyData data) {
   ...
}

Generating Excel Documents

AludraTest provides a feature to generate Excel documents based on a test method's signature and annotations. There is a GUI and a command line version that allows you to create an Eclipse run configuration for generating Excel documents:

Excel Generation GUI

The Excel Generation GUI is tarted by launching the main class org.aludratest.app.excelwizard.ExcelWizard. It scans the current project folder for (already compiled) AludraTest test cases and displays them in a list.

Using a filter text, the user can filter the test cases by substring:

When selecting a test case from the list, the 'Test Method' dropdown box is updated to display all test methods that have @Source annotations.

The user can then select one and click 'Create Excel Sheet'. The wizard will then create an empty Excel sheets that contains a 'config' tab and data tabs that reflect the structure of the annotated method parameters:

Excel Generation in Eclipse

For generating Excel documents in Eclipse, first create a "Java Application" run configuration that uses the project which contains the test class and set the main class to org.aludratest.app.excelwizard.CLIExcelCreator.

On second tab "Arguments", in the field 'Program Arguments' enter ${java_type_name}.

In order to execute the generator, select the test class in the Eclipse package explorer and start the new Run Configuration.