---
title: RSpec reference
description: Reference documentation for Allure RSpec integration | How to add sub-steps and additional metadata | Create attachments | Organise tests
---

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

```ruby
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](/docs/v2/readability/#description-links-and-other-metadata).

### Description

- `Allure::description_html: (String html)`

Set the test's [description](/docs/v2/readability/#description).

```ruby
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](/docs/v2/readability/#owner).

```ruby
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](/docs/v2/readability/#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](/docs/rspec-configuration/#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](/docs/rspec-configuration/#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:**
```ruby
describe 'Test my website' do
  it 'test authentication' do
    Allure.tag 'Web interface'
    Allure.tag 'Authentication'
    # ...
  end
end
```

**RSpec metadata:**
```ruby
describe 'Test my website' do
  it 'test authentication', :'Web interface', :Authentication do
    # ...
  end
end
```

**RSpec metadata (with a boolean value):**
```ruby
describe 'Test my website' do
  auth_data = [
    ['johndoe', false],
    ['johndoe@example.com', 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](/docs/v2/readability/#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](/docs/rspec-configuration/#severity-tag).

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

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

### Label

- `Allure::label: (String name, String value)`

Set an arbitrary [label](/docs/v2/readability/#other-labels) 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
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](/docs/v2/readability/#id).

This ID is used by the “test plan” feature in [Allure TestOps](https://qameta.io/) to select which tests to run. Allure RSpec does not export the ID to the test results.

```ruby
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](/docs/v2/readability/#links) 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
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](/docs/rspec-configuration/#link-issue-pattern-link-tms-pattern) 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](/docs/rspec-configuration/#issue-tag-tms-tag)).

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

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

```ruby
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](/docs/v2/navigation/#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](/docs/rspec-configuration/#epic-tag-feature-tag-story-tag).

**Runtime API:**
```ruby
describe 'Test my website' do
  it 'test authentication' do
    Allure.epic 'Web interface'
    Allure.feature 'Essential features'
    Allure.story 'Authentication'
    # ...
  end
end
```

**RSpec metadata:**
```ruby
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](/docs/v2/navigation/#suite-based-hierarchy).

```ruby
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](/docs/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:**
```ruby
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:**
```ruby
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](/docs/v2/readability/#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.

```ruby
describe 'Test my website' do
  auth_data = [
    ['johndoe', 'qwerty'],
    ['johndoe@example.com', '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](https://docs.ruby-lang.org/en/master/File.html).

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](#test-steps), 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.

```ruby
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
```