Allure Cucumber.rb reference

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

Metadata

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

Description

Allure::description_html: (String html)

You can either begin a Scenario with a description in your Gherkin file or call Allure.description_html() for updating it dynamically.

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.description_html 'This test attempts to create a label with specified title'
  # ...
end

Gherkin
Feature: Labels

  Scenario: Create new label for authorized user

  This test attempts to create a label with specified title

    When I open labels page
    And I create label with title "hello"
    Then I should see label with title "hello"

Owner

Set the test's owner.

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.label 'owner', 'John Doe'
  # ...
end

Tag

Allure::tag: (String tag)

Set the test's tags.

You can either use the tags in your Gherkin file or call Allure.tag() for setting tags 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"

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.tag 'authentication'
  Allure.tag 'important'
  # ...
end

Severity

@SEVERITY:trivial
@SEVERITY:minor
@SEVERITY:normal
@SEVERITY:critical
@SEVERITY:blocker

Set the test's severity.

By default, Allure Cucumber.rb will look for a Gherkin tag with the @SEVERITY: prefix. The prefix can be changed in the configuration.

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

Gherkin
Feature: Labels

  @SEVERITY: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"

Label

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.

The first argument of the function is the label name. It can be any string.

You can call Allure.label() multiple times to create an array of values under the given name.

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.label 'my custom label', 'value'
  # ...
end

Link

Allure::add_link: (url: String, name: String?, type: String?)
Allure::issue: (String name, String url)
Allure::tms: (String name, String url)
@ISSUE:⟨name⟩
@TMS:⟨name⟩

Add a link related to the test.

In Runtime API, you can do it by calling the Allure.add_link() function. 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: Allure.issue() and Allure.tms().

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.add_link url: 'https://dev.example.com/', name: 'Website'
  Allure.issue 'AUTH-123', 'https://issues.example.com/AUTH-123'
  Allure.tms 'TMS-456', 'https://tms.example.com/TMS-456'
  # ...
end

Alternatively, you can add issue links and TMS links via short identifiers in the Gherkin tags. To enable this, you need to specify link patterns in the configuration. Allure Cucumber.rb will use the patterns to process Gherkin tags with specific prefixes (defaults to @ISSUE: and @TMS: respectively, but can be changed in the configuration).

Assuming the link patterns https://issues.example.org/{} and https://tms.example.org/{}, the test in the example below will have an issue link to https://issues.example.org/AUTH-123 and a TMS link to https://tms.example.org/TMS-456.

Gherkin
Feature: Labels

  @ISSUE:AUTH-123
  @TMS:TMS-456
  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"

Behavior-based hierarchy

Allure::epic: (String epic)
Allure::feature: (String feature)
Allure::story: (String story)
@EPIC:⟨name⟩
@FEATURE:⟨name⟩
@STORY:⟨name⟩

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

You can do it via the functions in Runtime API or by specifying Gherkin tags with certain prefixes. The prefixes by default are @EPIC:, @FEATURE: and @STORY:, but they can be changed in the configuration. Note that due to a limitation in the Gherkin syntax, the value cannot contain spaces.

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.epic 'Web interface'
  Allure.feature 'Essential features'
  Allure.story 'Authentication'
  # ...
end

Gherkin
Feature: Labels

  @EPIC:WebInterface
  @FEATURE:EssentialFeatures
  @STORY:Authentication
  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"

Suite-based hierarchy

Allure::suite: (String name)

Assign the names of parent suite, suite or sub-suite for a test, as part of Allure's suite-based hierarchy.

Ruby
require 'allure-cucumber'

When 'I open labels page' do
    Allure.label 'parentSuite' 'Web interface'
    Allure.suite 'Essential features'
    Allure.label 'subSuite', 'Authentication'
  # ...
end

Test sub-steps

AllureStepAnnotation::step: (name: String, status: Status?)
Allure::run_step: (String name) { (*any) -> untyped }
Allure::step: (name: String, status: Status) { (*any) -> untyped }

Define a test sub-step with the given name.

There are three ways of defining a sub-step.

Annotated sub-steps

In a class that extends AllureStepAnnotation, define a method containing a test sub-step and add the step annotation to it, with an optional name argument (defaults to the method's name). Each time the method is called during the test execution, a new sub-step will be created within the current Gherkin step. If the method calls another function that also has the step attribute, Allure Report will create a sub-sub-step, and so on.
Block-based sub-steps

Write a test sub-step inside a block for the Allure.run_step() function. If the block returns a value, Allure.run_step() will return it without modification, and it will not affect the report.
No-op sub-steps

If you call the Allure.step() function, Allure will add to the report a no-op sub-step. This allows for a log-style reporting within a larger step. A no-op sub-step finishes immediately after it started and cannot have any sub-steps of its own.

The optional second argument indicates the status that will be shown for the sub-step in the report. Allowed values are: :passed (the default), :failed, :broken, :skipped, and :unknown.

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Steps.step_1
  Steps.step_2
end

class Steps
  extend AllureStepAnnotation

  step 'Step 1'

  def self.step_1
    step_1_1
    step_1_2
  end

  step 'Step 1.1'

  def self.step_1_1
    # ...
  end

  step 'Step 1.2'

  def self.step_1_2
    # ...
  end

  step 'Step 2'

  def self.step_2
    step_2_1
    step_2_2
  end

  step 'Step 2.1'

  def self.step_2_1
    # ...
  end

  step 'Step 2.2'

  def self.step_2_2
    # ...
  end
end

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.run_step 'Step 1' do

    # ...
    Allure.step name: 'Step 1.1', status: :passed

    # ...
    Allure.step name: 'Step 1.2', status: :passed
  end

  Allure.run_step 'Step 2' do

    # ...
    Allure.step name: 'Step 2.1', status: :passed

    # ...
    Allure.step name: 'Step 2.2', status: :passed
  end
end

Parametrized tests

An Allure test report can reflect two ways in which you can pass data from your Gherkin file to your Ruby implementation code, namely:

scenario outlines,
runtime parameters.

Scenario outlines

In Gherkin, a Scenario Outline (or a Scenario Template) implements the parametrized tests pattern. A scenario outline must contain an Examples table, from which Cucumber.rb 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 scenario based on the row. Cucumber.rb then runs each of them independently, as if it was a separate Scenario. The data can then be captured by a regular expression and passed as separate arguments to the Ruby code.

Allure Cucumber.rb automatically recognizes this pattern. No additional configuration is required.

The example below shows a Gherkin file and a Ruby 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.

Gherkin
Feature: User management

  Scenario Outline: 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 |

Ruby
require 'allure-cucumber'

When 'I go to the registration form' do
  # ...
end

And /^I enter my details: (.*), (.*), (.*), (.*)$/ do |login, password, name, birthday|
  # ...
end

Then 'the profile should be created' do
  # ...
end

Runtime parameters

Allure::parameter: (String name, String value)

The Allure.parameter() function can be used at any point, even if the Gherkin file does not specify actual parameters or data tables to any step.

The example below shows a Gherkin file and a Ruby implementation file of a test. As far as Cucumber.rb is concerned, the “I enter my details” in the example does not have any data passed to it, however, Allure will have the four parameters displayed on the test level.

Gherkin
Feature: User management

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

Ruby
require 'allure-cucumber'

When 'I go to the registration form' do
  # ...
end

And 'I enter my details' do
  Allure.parameter 'login', 'johndoe'
  Allure.parameter 'password', 'qwerty'
  Allure.parameter 'name', 'John Doe'
  Allure.parameter 'birthday', '1970-01-01'
  # ...
end

Then 'the profile should be created' do
  # ...
end

Attachments

Allure::add_attachment: (name: String, source: File | String, type: String, test_case: bool?)

Add an attachment with a given name.

The content is passed in the source argument and can be a text string or a File.

To ensure that the reader's web browser will display attachments correctly, pass the appropriate MIME type of the content as type. The Allure::ContentType class contains some popular MIME types, or you can use a custom string, as long as it will be understood by the web browser when viewing the test report.

When inside a test step, the function adds the attachment to the current step by default. To add it to the whole test result instead, pass true to the optional test_case argument.

If a Gherkin step has a data table, Allure Report display it as one of the step's attachments.

Ruby
require 'allure-cucumber'

When 'I open labels page' do
  Allure.add_attachment name: 'Screenshot',
                        source: File.new('/path/to/image.png'),
                        type: Allure::ContentType::PNG
  Allure.add_attachment name: 'Data',
                        source: 'This is the file content.',
                        type: Allure::ContentType::TXT
  # ...
end