Custom Steps

Using Custom Steps you can define new steps in a programming manner.
This way you can create new Testerum integrations or you can define steps that require the full flexibility of a programming language.

Setup

In order to define new Custom Steps you can download our sample project from GitHub: Testerum Custom Steps Sample Project

Requirements

Testerum Custom Steps Sample Project is a Java project and in order to compile and execute it you need the following beforehand:

Execution

Verify installation

Before you start making any changes is better to compile the project to see if everything is setup correctly. For this you need to execute the maven package command: mvn package

Test Execution

There are 3 ways to execute the tests in this project:

Using Testerum UI you can open the Testerum Tests attached to this projects:
<testerum_custom_steps_project_path>/tests
In order to see the Custom Steps changes in the UI you need to compile the project by executing: mvn package
Using your IDE, you can open the class: <testerum_custom_steps_project_path>src/test/java/com/testerum/JunitTesterumTests.java and execute it as a JUnit test. More about jUnit integration you can find here: JUnit
Executing the Maven command: mvn test

Project Structure

In this project you will find the following directories structure:

src

This directory follows the Maven standard. It's the place where you can define the source code of your custom steps.

target

This directory is created by Maven. It contains the .jar file that is the compiled source code.

tests

This directory contains the Testerum Tests.

How to create a Custom Step

Custom Step Example:

package custom;

import com.testerum_api.testerum_steps_api.annotations.steps.Given;
import com.testerum_api.testerum_steps_api.annotations.steps.Param;
import com.testerum_api.testerum_steps_api.services.TesterumServiceLocator;
import com.testerum_api.testerum_steps_api.test_context.logger.TesterumLogger;
import com.testerum_api.testerum_steps_api.test_context.test_vars.TestVariables;

public class SimpleSteps {
    private final TesterumLogger logger = TesterumServiceLocator.getTesterumLogger();
    private final TestVariables testVariables = TesterumServiceLocator.getTestVariables();

    @Given(value = "I am logged in with the role <<roleName>>",
           description = "Step description")
        public void login(@Param(description = "Param description") String roleName) {
            logger.info("Login with the role " + roleName);
            testVariables.set("ROLE_NAME", roleName);
        }
    }
}

In order to create a new Custom Step you need to create a new Java class with a method annotated with one of the following annotations:

@Given
@When
@Then

These annotations can have the following parameters:

value

This property accepts a String that defines the step name and the parameters. A parameter can be defined using the pattern: <<parameterName>>. The parameter name used in this expresion should be the same as the parameter name used in the method definition.

description

Step documentation will be shown in the interface and the text can be written using the Markdown syntax.

tags

Defines the tags for this step.

In case the step has parameters then you need to define these parameters also as the method parameter annotated with @Param annotation.
The method's parameters needs to have the same names as the parameters used in the step definition.

description

Parameter documentation that will be shown in the interface and the text can be written using the Markdown syntax.

required

Boolean value that specifies if this parameter is required or not.

transformer

In case you want to have a custom parameter serializer from the String that is saved in the file and back then you need to implement the interface com.testerum_api.testerum_steps_api.transformer.Transformer and set a class reference to this implementation as the value of this parameter.

Logging

To log information to the console the best option is to use the class TesterumLogger.
You can see an example on how to access it and use it in Custom Step Example at lines 10 and 16.

Variable context

Each Testerum test has allocated a variable context where all the global variables, scenario variables, and step defined variables are present.
In case you want to access or add variables in this context you can use the class TestVariables.

You can see an example of how to access the Variable Context and how to add a variable that can be used by other steps in Custom Step Example at lines 11 and 17.

You can see the Variable Context as a Map where all the test variables are stored and that can be accessed by any step or expression in the test. This Variable Context is reset between the tests.

Hooks

Testerum allows you to define hooks in a programming way by annotating a method with one of the following annotations:

@BeforeAllTests

will execute once before any tests are executed

@BeforeEachTest

will execute before each test

@AfterEachTest

will execute after each test

@AfterAllTests

will execute once after all the tests have been executed

Settings

Testerum allows you to define generic settings that can be later used in your steps.

Custom Setting Example:

package settings;

import com.testerum_api.testerum_steps_api.annotations.settings.DeclareSetting;
import com.testerum_api.testerum_steps_api.services.TesterumServiceLocator;
import com.testerum_api.testerum_steps_api.test_context.logger.TesterumLogger;
import com.testerum_api.testerum_steps_api.test_context.settings.RunnerSettingsManager;
import com.testerum_api.testerum_steps_api.test_context.settings.model.Setting;
import com.testerum_api.testerum_steps_api.test_context.settings.model.SettingType;

@DeclareSetting(
    key = Settings.MY_SETTING_KEY,
    label = "My Setting",
    type = SettingType.TEXT,
    defaultValue = "Success is not the key to happiness. Happiness is the key to success. If you love what you are doing, you will be successful.",
    description = "This is the description of my Setting",
    category = Settings.MY_SETTING_CATEGORY
)
public class Settings {
    public static final String MY_SETTING_KEY = "MY_SETTING_KEY";
    public static final String MY_SETTING_CATEGORY = "My Settings";

    private final TesterumLogger logger = TesterumServiceLocator.getTesterumLogger();
    private final RunnerSettingsManager settingsManager = TesterumServiceLocator.getSettingsManager();

    public void logMySetting() {
        Setting setting = settingsManager.getSetting(MY_SETTING_KEY);
        logger.info("MY SETTING = " + setting.getResolvedValue());
    }
}

img 1

In the img 1 you can see how the Custom Setting looks in the UI.

In order to create a custom setting you need to annotate a class with the @DeclareSetting annotation.
The DeclareSetting annotation parameters are:

key

This property accepts a String value that can be used to retrieve the setting value. Example on how to retrieve the setting value of a setting with the key "MY_SETTING_KEY": TesterumServiceLocator.getSettingsManager().getSetting("MY_SETTING_KEY").getResolvedValue()

label

The text that will be displayed on the top of the input box.

type

Enum property that accepts one of the values: BOOLEAN, NUMBER, TEXT, ENUM, FILESYSTEM_DIRECTORY.

enumValues

In case you set the type ENUM, then you can use this property to specify the possible values of the enumaration.

defaultValue

Sets the default value of the setting

description

You can define the description of this setting. In order to create a rich text you can use the Markdown syntax.

category

A String that defines the name of the setting group. All the settings with the same category name will be grouped in the same screen.

Distribution

In order to make your Custom Steps implementation available for Testerum UI, you need to compile the project using the Maven command: mvn package
After the Maven compilation, a .jar file is created in the target directory. Testerum loads the steps library from 2 directories:

<testerum_installation_path>/basic_steps
<testerum_tests_project_path>/basic_steps

If you copy this .jar file in one of these directories, Testerum will load your custom steps definitions.
If you copy your .jar file in the <testerum_tests_project_path>/basic_steps your custom library will be shared together with your steps in your version control system and this way all your team members will benefit from your custom steps without having to do any changes.