Allure Cucumber-JVM reference

These are the functions that you can use to integrate your Cucumber-JVM tests with Allure.

Allure Cucumber-JVM provides more than one way to use some features. In most cases, one way involves using an annotation on the test method, while the other involves a method call inside the test method body. The latter style is called “dynamic” and allows to construct values dynamically.

Metadata

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

Title

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

Set the test's title.

Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class CucumberSteps { @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 Feature with a description in your Gherkin file or call the methods for updating the values dynamically.

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

Gherkin
Feature: Labels 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"
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class CucumberSteps { @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.

You can either use the @allure.label.owner tags in your Gherkin file or call the label() method for updating the values dynamically. Note that when using tags in Gherkin, the value cannot contain spaces.

Gherkin
@allure.label.owner=JohnDoe Feature: Labels 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"
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class CucumberSteps { @When("^I open labels page$") public void openLabelsPage() { Allure.label("owner", "JohnDoe"); // ... } }

Tag

Set the test's tags.

You can either use the tags in your Gherkin file or call the label() method for updating the values dynamically.

Gherkin
@authentication @important Feature: Labels 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"
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class CucumberSteps { @When("^I open labels page$") public void openLabelsPage() { Allure.label("tag", "authentication"); Allure.label("tag", "important"); // ... } }

Severity

  • @Severity(SeverityLevel value)

Set the test's severity.

The value must be a constant from the io.qameta.allure.SeverityLevel class.

Gherkin
Feature: Labels @critical 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"
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class CucumberSteps { @When("^I open labels page$") public void openLabelsPage() { Allure.label("severity", "critical"); // ... } }

Label

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.

Gherkin
@allure.label.layer:web @allure.label.owner:eroshenkoam @allure.label.page:/{org}/{repo}/labels Feature: Labels @critical @allure.label.jira:AE-2 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"
Java
import io.cucumber.java.en.Given; import io.qameta.allure.Allure; public class CucumberSteps { @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)

You can specify test case ID for your Cucumber-JVM tests using @allure.id tag or via Runtime API:

Gherkin
Feature: Labels @allure.id:123 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"
  • Allure.link(String url)
  • Allure.link(String name, String url)
  • Allure.link(String name, String type, String url)

Add a link related to the test.

Based on the type (which can be any string), Allure will try to load a corresponding link pattern to process the URL, as defined by the allure.link.*.pattern configuration option. If no pattern found for the given type, the URL is left unmodified.

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

For convenience, Allure provides two shorthand functions with pre-selected link types: issue and tms.

Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class CucumberSteps { @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"); // ... } }

Issue

  • Allure.issue(String name, String url)

Add a link to an issue in a bug tracker related to the test.

This is a shorthand for @Link() with argument type="issue".

TMS

  • Allure.tms(String name, String url)

Add a link to an issue in a test management system (TMS) related to the test.

This is a shorthand for @Link() with argument type="tms".

Behavior-based hierarchy

  • Allure.epic(String value)
  • Allure.feature(String value)
  • Allure.story(String value)

Assign names of epics, features or user stories for a test, as part of Allure's behavior-based hierarchy.

You can either use the @allure.label.* tags in your Gherkin file or call the methods for updating the values dynamically. Note that when using tags in Gherkin, the values cannot contain spaces.

Gherkin
@allure.label.epic:WebInterface @allure.label.feature:EssentialFeatures @allure.label.story:Authentication Feature: My feature Scenario: My scenario Then my step
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class TestMyWebsite { @Then("...") public void testAuthentication() { Allure.epic("Web interface"); Allure.feature("Essential features"); Allure.story("Authentication"); // ... } }

Suite-based hierarchy

  • Allure.suite(String value)

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

You can either use the @allure.label.* tags in your Gherkin file or call the suite() and label() methods for updating the values dynamically. Note that when using tags in Gherkin, the values cannot contain spaces.

Gherkin
@allure.label.parent_suite:WebInterface @allure.label.suite:EssentialFeatures @allure.label.sub_suite:Authentication Feature: My feature Scenario: My scenario Then my step
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; import static io.qameta.allure.util.ResultsUtils.*; public class TestMyWebsite { @Then("...") public void testAuthentication() { Allure.label(PARENT_SUITE_LABEL_NAME, "Tests for web interface"); Allure.suite("Tests for essential features"); Allure.label(SUB_SUITE_LABEL_NAME, "Tests for authentication"); // ... } }

Test steps

  • @Step(String value="")
  • 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 step with the given name.

There are three ways of defining a step.

  • “An annotated step”: define a method containing a test step and decorate it with @Step().
  • “A lambda step”: write a test step in a lambda function and pass it to Allure.step().
  • “A no-op 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 step, it can accept either no arguments or a single argument of class StepContext. This object provides the following methods:

  • name() — override the step name during its execution.
  • parameter() — indicate arbitrary parameters used for the step. The available signatures of this method are the same as for the test-wide implementation, see Parametrized tests.
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Step; public class TestMyWebsite { @Then("...") public void testAuthentication() { 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() { // ... } }
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class TestMyWebsite { @Then("...") public void testAuthentication() { Allure.step("Step 1", (step) -> { // ... Allure.step("Sub-step 1"); // ... Allure.step("Sub-step 2"); }); Allure.step("Step 2", (step) -> { // ... }); } }

Parametrized tests

  • 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.

Allure Cucumber-JVM identifies tests based only on their names and Gherkin parameters. 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.
Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; public class TestMyWebsite { @Then("authorize as {string}") public void testAuthentication(String login) { Allure.parameter("auth_method", "password"); Allure.parameter("login", login); // ... } @Then("authorize with empty login") public void testAuthenticationWithEmptyLogin() { Allure.parameter("login", ""); Allure.parameter("auth_method", "password"); // ... } }

Attachments

Functions for adding attachments to test results.

Attaching content from variables

  • 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).

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 MIME type of the content as type and, optionally, a filename extension as fileExtension. The MIME 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.

Java
import io.cucumber.java.en.Then; import io.qameta.allure.Allure; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Paths; public class TestMyWebsite { @Then("...") public void attachScreenshot() throws IOException { // ... Allure.attachment("data.txt", "This is the file content."); Allure.attachment("img.png", Files.newInputStream(Paths.get("/path/img.png"))); // ... } }

Generating attachments dynamically

  • @Attachment(String value="", String type="", String fileExtension="")

Define a function that returns the data you need to attach and annotate it with @Attachment. Call the function at any point during your test to attach the data to the test result.

The data will be processed as following:

  • If the data type is byte[], Allure will use it without modification.
  • If the data type is String, Allure will convert it to byte[].
  • If the data is of any other type, Allure will call the toString() method and then convert the string to byte[].

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 MIME type of the content as type and, optionally, a filename extension as fileExtension. The MIME 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.

Java
import io.cucumber.java.en.Then; import io.qameta.allure.Attachment; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Paths; public class TestMyWebsite { @Then("...") public void testAuthentication() throws IOException { // ... attachDataTXT(); attachScreenshotPNG(); } @Attachment(value = "data", type = "text/plain", fileExtension = ".txt") public String attachDataTXT() { return "This is the file content."; } @Attachment(value = "screenshot", type = "image/png", fileExtension = ".png") public byte[] attachScreenshotPNG() throws IOException { return Files.readAllBytes(Paths.get("/path/to/image.png")); } }

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.

Results history

Flaky

  • @Flaky

Indicate that the test is known to be unstable and can may not succeed every time.

Powered by
logo

Join our newsletter

Join our community

We aim to make Allure Report as reliable and user-friendly as possible, and together with the community, we're here to help when problems arise.

© 2024 Qameta Software Inc. All rights reserved.