Allure Spock reference

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

Allure Spock 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

Title

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

Set the test's title.

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.getLifecycle().updateTestCase { result ->
            result.setName("Test Authentication!")
        }
        // ...
    }
}

Description

• @Description(String value)
• Allure.description(String description)

Set the test's description. Markdown formatting is allowed. Any HTML formatting, if present, will be stripped for security purposes.

Annotations API

import io.qameta.allure.Description
import spock.lang.Specification

class TestMyWebsite extends Specification {

    @Description("This test attempts to log into the website using a login and a password. Fails if any error happens.\n\nNote that this test does not test 2-Factor Authentication.")
    def "Test Authentication"() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.description("This test attempts to log into the website using a login and a password. Fails if any error happens.\n\nNote that this test does not test 2-Factor Authentication.")
        // ...
    }
}

Owner

• @Owner(String value)

Set the test's owner.

Allure Spock does not provide a dedicated method for setting the owner dynamically, but you can use Allure.label() with the appropriate label name instead.

Annotations API

import io.qameta.allure.Owner
import spock.lang.Specification

class TestMyWebsite extends Specification {

    @Owner("John Doe")
    def "Test Authentication"() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.label("owner", "John Doe")
        // ...
    }
}

Tag

Set the test's tags.

You can either use the Spock's @Tag annotation or call the label() method for updating the values dynamically.

Annotations API

import spock.lang.Specification
import spock.lang.Tag

class TestMyWebsite extends Specification {

    @Tag("auth")
    @Tag("security")
    def "Test Authentication"() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.label("tag", "auth")
        Allure.label("tag", "security")
        // ...
    }
}

Severity

Set the test's severity.

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

Allure Spock does not provide a dedicated method for setting the severity level dynamically, but you can use Allure.label() with the appropriate label name instead.

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.label("severity", "critical")
        // ...
    }
}

Label

• @LabelAnnotation(String name, String value=DEFAULT_VALUE)
• Allure.label(String name, String value)

Set an arbitrary label for the test. This is the underlying implementation for a lot of Allure's other functions.

To set a label dynamically, just call the label() function with a name and a value for a label. You can do it multiple times to create an array of values under that name.

Another way of setting a label is to create a custom class using @LabelAnnotation and annotate the tests with the new annotation, see the example below. Please be careful to copy @Retention, @Target and the other necessary annotations as this is shown in the example, otherwise you custom annotation may not work properly.

Annotations API

import io.qameta.allure.LabelAnnotation
import spock.lang.Specification

import java.lang.annotation.Documented
import java.lang.annotation.ElementType
import java.lang.annotation.Inherited
import java.lang.annotation.Retention
import java.lang.annotation.RetentionPolicy
import java.lang.annotation.Target

@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target([ElementType.METHOD, ElementType.TYPE])
@LabelAnnotation(name = "CustomLabelName")
@interface MyLabel {
    String value();
}

class TestMyWebsite extends Specification {

    @MyLabel("custom label value")
    def "Test Authentication"() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.label("language", "groovy")
        Allure.label("framework", "spock")
        // ...
    }
}

ID

• @AllureId(String value)

Set the test's ID.

Allure Spock does not provide a dedicated method for setting the ID dynamically, but you can use Allure.label() with the appropriate label name instead.

Annotations API

import io.qameta.allure.AllureId
import spock.lang.Specification

class TestMyWebsite extends Specification {

    @AllureId("123")
    def "Test Authentication"() {
        // ...
    }
}

Link

• @Link(String value="", name="", String url="", String type=CUSTOM_LINK_TYPE)
• @Links(Link[] value)
• 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.

Annotations API

import io.qameta.allure.Issue
import io.qameta.allure.Link
import io.qameta.allure.TmsLink
import spock.lang.Specification

class TestMyWebsite extends Specification {

    @Link(name = "Website", url = "https://dev.example.com/")
    @Issue("AUTH-123")
    @TmsLink("TMS-456")
    def "Test Authentication"() {
        // ...
    }
}

Runtime API

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        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

• @Issue(String value="")
• @Issues(Issue[] value)
• 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

• @TmsLink(String value="")
• @TmsLinks(TmsLink[] value)
• 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

• @Epic(String value="")
• @Epics(Epic[] value)
• @Feature(String value="")
• @Features(Feature[] value)
• @Story(String value="")
• @Stories(Story[] value)
• 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.

Suite-based hierarchy

• Allure.suite(String value)

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

To assign names of parent suite or sub-suite, use label() with the corresponding label names.

Test steps

• @Step(String value="")
• Allure.step(String name)
• Allure.step(String name, Status status)

Define a test step with the given name.

There are two ways of defining a step.

• “An annotated step”: define a method containing a test step and decorate it with @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.

Annotated steps

import io.qameta.allure.Step
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        // ...
        steps.step1()
        steps.step2()
    }

    private class steps {

        @Step("Step 1")
        static def step1() {
            // ...
        }

        @Step("Step 2")
        static def step2() {
            // ...
        }
    }
}

No-op steps

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.step("Step 1")
        // ...
        Allure.step("Step 2")
        // ...
    }
}

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. This can be used for adding the parameters even to those function that do not use the @ParameterizedTest() decorator. See Parametrized tests for more details.

Note that using this method is not necessary in most cases, since Allure Spock automatically detects the parameters specified via Spock's data tables.

WARNING

Allure Spock identifies tests based only on their names and data tables. 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.

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        // ...
        where:
        login                 | _
        "johndoe"             | _
        "[email protected]" | _
    }

    def "Test Authentication With Empty Login"() {
        Allure.parameter("login", "")
        // ...
    }
}

Attachments

• @Attachment(String value="", String type="", String fileExtension="")
• 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 create an attachment using the Annotations API, define a method that returns some data and annotate it with @Attachment. Call the method at any point during your test.

To create an attachment using the Runtime API, just call addAttachment() or attachment() at any point during your test. Pass the data as the content argument.

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

Annotations API

import io.qameta.allure.Attachment
import spock.lang.Specification

import java.nio.file.Files
import java.nio.file.Paths

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        // ...
        attachDataTXT()
        attachScreenshotPNG()
    }

    @Attachment(value = "data", type = "text/plain", fileExtension = ".txt")
    private String attachDataTXT() {
        return "This is the file content."
    }

    @Attachment(value = "screenshot", type = "image/png", fileExtension = ".png")
    private byte[] attachScreenshotPNG() throws IOException {
        return Files.readAllBytes(Paths.get("/path/to/image.png"))
    }
}

Runtime API

import io.qameta.allure.Allure
import spock.lang.Specification

class TestMyWebsite extends Specification {

    def "Test Authentication"() {
        Allure.attachment("data.txt", "This is the file content.")
        new File("/path/to/image.png").withInputStream { is ->
            Allure.addAttachment("image.png", is)
        }
        expect: true
    }
}

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.

Results history

Flaky

• @Flaky

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