Allure JBehave reference

These are the functions that you can use to integrate your JBehave tests with Allure.

Metadata

Assign a test's description, links and other metadata.

Title

• Allure.getLifecycle().updateTestCase(Consumer<TestResult> update)

Set the test's title.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.getLifecycle().updateTestCase(result ->
                result.setName("Some modified scenario name"));
        // ...
    }
}

Description

• Allure.description(String description)

Set the test's description.

You can either begin a story file with a description or call the methods for updating the values dynamically.

Markdown formatting is allowed. Any HTML formatting, if present, will be stripped for security purposes.

Story file

This test attempts to create a label with specified title

Scenario: Create new label for authorized user
When I open labels page
And I create label with title "hello"
Then I should see label with title "hello"

Runtime API

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.description("This test attempts to create a label with specified title");
        // ...
    }
}

Owner

Set the test's owner.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.label("owner", "John Doe");
        // ...
    }
}

Tag

Set the test's tags.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.label("tag", "ui");
        Allure.label("tag", "labels");
        // ...
    }
}

Severity

Set the test's severity.

Allowed values are: “trivial”, “minor”, “normal”, “critical”, and “blocker”.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.label("severity", "critical");
        // ...
    }
}

Label

• Allure.label(String name, String value)

Allure labels are key-value pairs used to add additional meta-information to your tests. They can be considered as a way to categorize, organize, and search for test cases within your Allure reports. Labels can be used to specify things like the test case ID, the severity of the test, the feature being tested, or the story that relates to the test. This meta-information helps to create more detailed and structured reports.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.label("layer", "web");
        Allure.label("owner", "eroshenkoam");
        Allure.label("page", "/{org}/{repo}/labels");
        Allure.label("severity", "critical");
        Allure.label("jira", "AE-2");
        // ...
    }
}

Allure ID (Allure TestOps)

Set the test's ID.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.label("ALLURE_ID", "123");
        // ...
    }
}

Link

• Allure.link(String url)
• Allure.link(String name, String url)
• Allure.link(String name, String type, String url)
• Allure.issue(String name, String url)
• Allure.tms(String name, String url)

Add a link related to the test.

The name will be used as the link's text. If it is omitted, the full URL will be used instead.

The type affects the icon that is displayed next to the link in the test report. For convenience, Allure provides two shorthand functions with pre-selected link types: issue and tms.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.link("Website", "https://dev.example.com/");
        Allure.issue("AUTH-123", "https://example.com/issues/AUTH-123");
        Allure.tms("TMS-456", "https://example.com/tms/TMS-456");
        // ...
    }
}

Behavior-based hierarchy

Being a BDD-oriented framework, JBehave organizes tests according to the story files. In the test report, Allure JBehave displays this hierarchy on the Behaviors tab. The names of the groups correspond to the names of the files. No special setup is needed.

Suite-based hierarchy

• Allure.suite(String value)

Assign the name of suite, as part of Allure's suite-based hierarchy.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        Allure.label("parentSuite", "Tests for web interface");
        Allure.suite("Tests for essential features");
        Allure.label("subSuite", "Tests for labels");
        // ...
    }
}

Test sub-steps

• Allure.step(String name)
• Allure.step(String name, Status status)
• Allure.step(String name, ThrowableRunnableVoid runnable)
• Allure.step(String name, ThrowableRunnable<T> runnable)
• Allure.step(ThrowableContextRunnableVoid<StepContext> runnable)
• Allure.step(String name, ThrowableContextRunnableVoid<StepContext> runnable)
• Allure.step(String name, ThrowableContextRunnable<T, StepContext> runnable)
• Allure.step(ThrowableContextRunnable<T, StepContext> runnable)

Define a test sub-step with the given name.

There are three ways of defining a sub-step.

• “An annotated sub-step”: define a method containing a test step and decorate it with @Step().
• “A lambda sub-step”: write a test sub-step in a lambda function and pass it to Allure.step().
• “A no-op sub-step”: just pass a name and an optional status to Allure.step() to immediately add a corresponding entry to the results as a sub-step of the current step.

When you are implementing a function for a lambda sub-step, it can accept either no arguments or a single argument of class StepContext. This object provides the following methods:

• name() — override the sub-step name during its execution.
• parameter() — indicate arbitrary parameters used for the sub-step. The available signatures of this method are the same as for the test-wide implementation, see Parametrized tests.

Annotated sub-steps

import io.qameta.allure.Step;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {
        step1();
        step2();
    }

    @Step("Step 1")
    public void step1() {
        subStep1();
        subStep2();
    }

    @Step("Sub-step 1")
    public void subStep1() {
        // ...
    }

    @Step("Sub-step 2")
    public void subStep2() {
        // ...
    }

    @Step("Step 2")
    public void step2() {
        // ...
    }
}

Lambda steps and no-op sub-steps

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() {

        Allure.step("Step 1", (step) -> {
            // ...
            Allure.step("Sub-step 1");
            // ...
            Allure.step("Sub-step 2");
        });

        Allure.step("Step 2", (step) -> {
            // ...
        });
    }
}

Parametrized tests

Allure JBehave support two ways of implementing the parametrized tests pattern:

• parametrized scenarios,
• runtime parameters.

Parametrized scenarios

In the JBehave story files, a parametrized scenario (sometimes called a scenario outline or a scenario template) implements the parametrized tests pattern. A parametrized scenario must contain an Examples table, from which JBehave loads sets of parameters, one row after another. Each set of parameters is being placed into the step declarations according to the placeholders, thus generating a new iteration of the scenario based on the row. The data can then be captured using the parameter injection syntax and passed as separate arguments to the Java code.

Allure JBehave automatically recognizes this pattern. No additional configuration is required.

The example below shows a story file and a Java implementation file of a test. In this example, the four parameters for the “I enter my details...” step will be displayed in both instances of the scenario in the test report.

Scenario: Registration
When I go to the registration form
And I enter my details: <login>, <password>, <name>, <birthday>
Then the profile should be created

Examples:
| login   | password | name     | birthday   |
| johndoe | qwerty   | John Doe | 1970-01-01 |
| janedoe | 123456   | Jane Doe | 1111-11-11 |

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;
import org.jbehave.core.annotations.When;

public class JBehaveSteps {

    @When("I go to the registration form")
    public void goToRegistrationForm() {
        // ...
    }

    @When("I enter my details: $login, $password, $name, $birthday")
    public void enterMyDetails() {
        // ...
    }

    @Then("the profile should be created")
    public void profileShouldBeCreated() {
        // ...
    }
}

Runtime parameters

• Allure.parameter(String name, T value)
• Allure.parameter(String name, T value, Boolean excluded)
• Allure.parameter(String name, T value, Parameter.Mode mode)
• Allure.parameter(String name, T value, Boolean excluded, Parameter.Mode mode)

Specify a name and value of a parameter that was used during this test. See Parametrized tests for more details.

WARNING

Allure JBehave identifies tests based only on their names and parameters passed from the story file. If you have multiple tests that only differ in dynamic parameters (i.e., the Allure.parameter() calls), they will be treated as one test for the purposes of history and retries.

If the excluded argument is set to true, Allure will not use the parameter when comparing the current test result with previous one in the history. This argument is only used by Allure TestOps.

The mode argument affects how the parameter will be displayed in the report. Available options are defined in the Parameter.Mode enumeration:

• Parameter.Mode.DEFAULT (same as not specifying any mode) — the parameter and its value will be shown in a table along with other parameters.
• Parameter.Mode.MASKED — the parameter will be shown in the table, but its value will be hidden. Use this mode for passwords, tokens and other sensitive parameters.
• Parameter.Mode.HIDDEN — the parameter and its value will not be shown in the test report. Note, however, that it is still possible to extract the value from the allure_results directory if you publish it.

Scenario: Registration
When I go to the registration form
And I enter my details
Then the profile should be created

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;
import org.jbehave.core.annotations.When;

public class JBehaveSteps {

    @When("I go to the registration form")
    public void goToRegistrationForm() {
        // ...
    }

    @When("I enter my details")
    public void enterMyDetails() {
        Allure.parameter("login", "johndoe");
        Allure.parameter("password", "qwerty");
        Allure.parameter("name", "John Doe");
        Allure.parameter("birthday", "1970-01-01");
        // ...
    }

    @Then("the profile should be created")
    public void profileShouldBeCreated() {
        // ...
    }
}

Attachments

• Allure.addAttachment(String name, String content)
• Allure.addAttachment(String name, String type, String content)
• Allure.addAttachment(String name, String type, String content, String fileExtension)
• Allure.addAttachment(String name, InputStream content)
• Allure.addAttachment(String name, String type, InputStream content, String fileExtension)
• Allure.attachment(String name, String content)
• Allure.attachment(String name, InputStream content)

Add content as an attachment to the test result under the given name (defaults to a unique pseudo-random string).

TIP

You can use data produced by any function, not necessarily read from an actual file.

To ensure that the reader's web browser will display attachments correctly, it is recommended to specify each attachment's type. To do so, pass the media type of the content as type and, optionally, a filename extension as fileExtension. The media type affects how the data will be displayed in the test report, while the filename extension is appended to the filename when user wants to save the file.

import io.qameta.allure.Allure;
import org.jbehave.core.annotations.Then;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class JBehaveSteps {

    @When("I open labels page")
    public void openLabelsPage() throws IOException {
        // ...
        Allure.attachment("data.txt", "This is the file content.");
        Allure.attachment("img.png", Files.newInputStream(Paths.get("/path/img.png")));
    }
}

INFO

Additionally, Allure provides a way to spawn threads that will add attachments to the test results asynchronously without blocking the test runner. While not recommended for the majority of cases, this approach can improve tests that otherwise have to wait for processing very large files, such as videos larger than 1 GB. Please refer to the source code for Allure.addByteAttachmentAsync() and Allure.addStreamAttachmentAsync() to learn more.