Allure RSpec reference

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

Note that all the functions from the Allure module are also available via the object that RSpec passes to each test, like the t argument in the example below.

describe 'Test my website' do
  it 'test authentication' do |t|
    t.description_html 'This test attempts to log into the website using a login and a password.'
    # ...
  end
end

Metadata

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

Description

• Allure::description_html: (String html)

Set the test's description.

describe 'Test my website' do
  it 'test authentication' do
    Allure.description_html 'This test attempts to log into the website using a login and a password.'
    # ...
  end
end

Owner

Set the test's owner.

describe 'Test my website' do
  it 'test authentication' do
    Allure.label "owner", 'John Doe'
    # ...
  end
end

Tag

• Allure::tag: (String tag)

Set the test's tags.

There are three ways to add a tag to your test.

• From within the test body, call the Allure.tag() function.

• Add a symbol to the RSpec metadata. Allure RSpec will add a tag using the symbol's name, unless it is one of the ignored tags.

• Add a key-value pair to the RSpec metadata. Allure RSpec will add a tag using the value, unless the key is one of the ignored tags or the value is false. The latter is convenient when you declare multiple tests in a loop and want to add or not add a tag based on a condition, as in the example below.

Runtime API

describe 'Test my website' do
  it 'test authentication' do
    Allure.tag 'Web interface'
    Allure.tag 'Authentication'
    # ...
  end
end

RSpec metadata

describe 'Test my website' do
  it 'test authentication', :'Web interface', :Authentication do
    # ...
  end
end

RSpec metadata (with a boolean value)

describe 'Test my website' do
  auth_data = [
    ['johndoe', false],
    ['[email protected]', true],
  ]
  auth_data.each do |login, using_email|
    it "test authentication as #{login}", 'Using email': using_email do
      # ...
    end
  end
end

Severity

• severity: String

Set the test's severity.

By default, Allure RSpec will use the value under the severity key in the RSpec metadata. The key can be changed in the configuration.

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

describe 'Test my website' do
  it 'test authentication', severity: 'critical' do
    # ...
  end
end

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.

describe 'Test my website' do
  it 'test authentication' do
    Allure.label 'my custom label', 'value'
    # ...
  end
end

Allure ID (Allure TestOps)

• allure_id: String

Set the test's ID.

This ID is used by the “test plan” feature in Allure TestOps to select which tests to run. Allure RSpec does not export the ID to the test results.

describe 'Test my website' do
  it 'test authentication', allure_id: '123' do
    # ...
  end
end

Link

• issue: String
• tms: String
• Allure::add_link: (url: String, name: String?, type: String?)
• Allure::issue: (String name, String url)
• Allure::tms: (String name, String url)

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

describe 'Test my website' do
  it 'test authentication' 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
end

Alternatively, you can add issue links and TMS links via short identifiers in the RSpec metadata. To enable this, you need to specify link patterns in the configuration. Allure RSpec will use the patterns to process values under specific keys (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.

describe 'Test my website' do
  it 'test authentication', issue: 'AUTH-123', tms: 'TMS-456' do
    # ...
  end
end

If you need to specify more than one issue link or more than one TMS link to the same test, use keys with numeric postfixes after an underscore, e.g.: issue_1, issue_2, tms_1, tms_2, etc. Allure RSpec will process each of the values as usual, ignoring the keys' postfixes.

describe 'Test my website' do
  it 'test authentication', issue_1: 'AUTH-123', issue_2: 'AUTH-124' do
    # ...
  end
end

Behavior-based hierarchy

• epic: String
• feature: String
• story: String
• Allure::epic: (String epic)
• Allure::feature: (String feature)
• Allure::story: (String story)

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 RSpec metadata under certain keys. The keys by default are epic, feature and story, but they can be changed in the configuration.

Runtime API

describe 'Test my website' do
  it 'test authentication' do
    Allure.epic 'Web interface'
    Allure.feature 'Essential features'
    Allure.story 'Authentication'
    # ...
  end
end

RSpec metadata

describe 'Test my website' do
  it 'test authentication',
     epic: 'Web interface',
     feature: 'Essential features',
     story: 'Authentication' do
    # ...
  end
end

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.

describe 'Test my website' do
  it 'test authentication' do
    Allure.label 'parentSuite' 'Web interface'
    Allure.suite 'Essential features'
    Allure.label 'subSuite', 'Authentication'
    # ...
  end
end

Test steps

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

Define test steps.

There are three ways of defining a step.

• Annotated steps

  In a class that extends AllureStepAnnotation, define a method containing a test 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 step will be created for the test report. If the method calls another function that also has the step attribute, Allure Report will create a sub-step inside the current step.

• Block-based steps

  Write a test 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 steps

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

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

Annotated steps

describe 'Test my website' do
  it 'test authentication' do
    Steps.step_1
    Steps.step_2
  end
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

Block-based steps and no-op steps

describe 'Test my website' do
  it 'test authentication' 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
end

Parametrized tests

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

With Allure RSpec, it is very easy to implement the parametrized tests pattern, i.e. to run the same test logic with different test data. To do so, just write the test inside a loop and use the variable parameters in both its title and its body.

To display a parameter value in the test report, pass it to the Allure.parameter() function.

describe 'Test my website' do
  auth_data = [
    ['johndoe', 'qwerty'],
    ['[email protected]', 'qwerty'],
  ]
  auth_data.each do |login, password|
    it "Test authentication as '#{login}'" do
      Allure.parameter 'Login', login
      Allure.parameter 'Password', password
      # ...
    end
  end
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 media type of the content as type. The Allure::ContentType class contains some popular media 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.

describe 'Test my website' do
  it 'test authentication' 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
end