Getting Started

All Aerial transformation is mainly done in 4 steps:

1. Include dependency

2. Create requirements document

3. Configure Cucumber code generation

4. Run JUnit test

Including Aerial as Dependency

Aerial is provided as Maven dependency and can be included using the construction like:

1
2
3
4
5

<dependency>
	<groupId>com.github.mkolisnyk</groupId>
	<artifactId>aerial</artifactId>
	<version>0.0.1</version>
</dependency>

or for Gradle:

1

'com.github.mkolisnyk:aerial:0.0.1'

Document Structure

Each Aerial document has the structure like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

< Entire document description >

[Input Ref: <Name>
    <Input Data Table>
]

Feature: < Feature Name >
    < Feature description >

    Case: < Case Name >
        < Case Description >

        Action:
            < Action text >
        Input: [ <Reference Name> |
            < Input Data Table > ]
        On Success:
            < Actions in case of success >
        On Failure:
            < Actions in case of error >
        Pre-requisites:
            < Pre-requisites steps >
    Additional Scenarios:
        < Explicitly defined custom Cucumber scenarios >

Feature Section

Input Ref Section

This section is targeted to use external definitions for Input sections. The structure is the same as for Input section except it also uses the name attribute to identify the reference uniquely.

Case Section

Pre-requisites

Action

Input

On Success

On Failure

Additional Scenarios

Input Data Description

Input data is specific section which contains input values definitions with the rules how they should be validated. This section is core part of data generation. Here is some example of input section:

1
2
3

Input:
    | Name | Type | Value   |
    | Test | Int  | [0;100) |

This section defines single integer parameter named Test which acceptable values are from 0 (inclusively) to 100 (exclusively). So, Aerial will generate scenarios for different inputs for this parameter.

Input Section Structure

Input section is represented as the table with the following columns:

Data Types in Use and Acceptable Value Patterns

The most complicated and important part of this table is supported data types and value pattern to be used for generation. Currently the following data types are supported:

• Int - numeric value

• Date - any formatted date

• String - text string

• Enum - text string where each item is delimited with ; (semi-colon) character

Depending on data type we should use appropriate patterns.

Numeric Value Patterns

Date Value Patterns

String Value Patterns

Usually string acceptable value rules are defined using regular expression. It means that text value should match some specific regular expression pattern.

Input/Output Sources

Input Sources

Output Sources

Java Annotations

@Aerial

Main annotation identifying Aerial generation attributes. This annotation is set for test class which should be JUnit runnable. So, initially the class should look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

package com.github.mkolisnyk.aerial;

import org.junit.runner.RunWith;

import com.github.mkolisnyk.aerial.annotations.Aerial;
import com.github.mkolisnyk.aerial.core.AerialRunner;
import com.github.mkolisnyk.aerial.core.params.AerialSourceType;

import cucumber.api.CucumberOptions;

@RunWith(AerialRunner.class)
public class AerialRunnerTest {
}

Thus, we target JUnit to run tests using AerialRunner class which will drive Cucumber features generation with further Cucumber run. After that we’re ready to add @Aerial annotation. Here is an example of generator configuration targeted to read requirement documents from files located in the src/test/resources folder and write generated files into ./output/ folder:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

package com.github.mkolisnyk.aerial;

import org.junit.runner.RunWith;
import com.github.mkolisnyk.aerial.annotations.Aerial;
import com.github.mkolisnyk.aerial.core.AerialRunner;
import com.github.mkolisnyk.aerial.core.params.AerialSourceType;
import cucumber.api.CucumberOptions;

@Aerial(
    inputType = AerialSourceType.FILE,
    source = "src/test/resources",
    additionalParams = { "" },
    destination = "output/")
@RunWith(AerialRunner.class)
public class AerialRunnerTest {
}

The last part is to add CucumberOptions annotation to point Cucumber where to take the input from:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

package com.github.mkolisnyk.aerial;

import org.junit.runner.RunWith;
import com.github.mkolisnyk.aerial.annotations.Aerial;
import com.github.mkolisnyk.aerial.core.AerialRunner;
import com.github.mkolisnyk.aerial.core.params.AerialSourceType;
import cucumber.api.CucumberOptions;

@CucumberOptions(
        format = {"html:target/cucumber-html-report",
                  "json:target/cucumber.json",
                  "pretty:target/cucumber-pretty.txt",
                  "usage:target/cucumber-usage.json"
                 },
        features = {"output/" },
        glue = {"com/github/mkolisnyk/aerial" },
        tags = { }
)
@Aerial(
    inputType = AerialSourceType.FILE,
    source = "src/test/resources",
    additionalParams = { "" },
    destination = "output/")
@RunWith(AerialRunner.class)
public class AerialRunnerTest {
}

@AerialBeforeSuite and @AerialAfterSuite

As it was mentioned before the AerialRunner is wrapper on Cucumber JUnit runner class. So, all annotations applicable to Cucumber runner are applicable there. But there may be a need to perform some actions before and/or after any code generation or tests execution. For this purpose there’re dedicated annotations named @AerialBeforeSuite and @AerialAfterSuite correspondingly. They are assigned to methods which are supposed to be executed before and after entire suite run. With these annotations the above example can be appended like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

package com.github.mkolisnyk.aerial;

import org.junit.runner.RunWith;
import com.github.mkolisnyk.aerial.annotations.Aerial;
import com.github.mkolisnyk.aerial.core.AerialRunner;
import com.github.mkolisnyk.aerial.core.params.AerialSourceType;
import cucumber.api.CucumberOptions;

@CucumberOptions(
        format = {"html:target/cucumber-html-report",
                  "json:target/cucumber.json",
                  "pretty:target/cucumber-pretty.txt",
                  "usage:target/cucumber-usage.json"
                 },
        features = {"output/" },
        glue = {"com/github/mkolisnyk/aerial" },
        tags = { }
)
@Aerial(
    inputType = AerialSourceType.FILE,
    source = "src/test/resources",
    additionalParams = { "" },
    destination = "output/")
@RunWith(AerialRunner.class)
public class AerialRunnerTest {
    @AerialBeforeSuite
    public static void setUp() {
        System.out.println("setUp");
    }
    @AerialAfterSuite
    public static void tearDown() {
        System.out.println("tearDown");
    }
}

Using References for Input Data

Since version 0.0.6

In some cases the same input data description may be applied to multiple cases. Mainly it is related to cases which operate with the same input values but check some specific flows. In order to minimize duplication in test scenarios there was Input Ref feature introduced.

Imagine we have document with multiple cases operating with the same set of data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Feature: Sample Feature
    Case: Sample Test
        Action:
            Sample action
        Input:
            | Name | Type | Value   |
            | Test | Int  | [0;100) |
        On Success:
            This is what we see on success
        On Failure:
            This is what we see on error
        Pre-requisites:
            These are our pre-requisites

    Case: Another Sample Test
        Action:
            Sample alternative action
        Input:
            | Name | Type | Value   |
            | Test | Int  | [0;100) |
        On Success:
            Some alternative results on success
        On Failure:
            Some alternative results on error
        Pre-requisites:
            These are our pre-requisites

As it is seen from the above example we have 2 cases which operate with the same set of input data. If for any occasion we need to update the input data we need to do it in 2 places. And if the data is really related to the same input form or at least to the same input we always should do this as soon as we change something in the input. In order to minimize such duplication we can add global input definition and each case just uses reference to it. So, using this feature we can modify our requirements document like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Input Ref: Test Data
    | Name | Type | Value   |
    | Test | Int  | [0;100) |

Feature: Sample Feature
    Case: Sample Test
        Action:
            Sample action
        Input: Test Data
        On Success:
            This is what we see on success
        On Failure:
            This is what we see on error
        Pre-requisites:
            These are our pre-requisites

    Case: Another Sample Test
        Action:
            Sample alternative action
        Input: Test Data
        On Success:
            Some alternative results on success
        On Failure:
            Some alternative results on error
        Pre-requisites:
            These are our pre-requisites

Pay attention to new Input Ref: section at the top level of the document hierarchy. It contains global definition for the input. The name of this section (which goes right after Input Ref: keyword) is used then as reference in any Input section. So, the modified document does the same as the original one. When we have many input data definitions which are widely used we get an advantage and at the same time we don’t lose document structure and visibility.

Using archetypes

For several project types there are dedicated archetypes to simplify projects creation. Simple project using archetype is created in several steps:

Step 1: Create New Project

Step 2: Select Maven Project

Click on Next

Step 3: Define New Maven Project Location

Make sure the highlighted check box is unchecked and click on Next

Step 4: Select Archetype

Click on Next

Step 5: Fill in Archetype Parameters

Click on Finish

Step 6: View Project Structure

News