--- title: Cucumber.rb reference description: Reference documentation for Allure Cucumber.rb integration | How to add sub-steps and additional metadata | Create attachments | Organise tests --- # 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](/docs/v2/readability/#description-links-and-other-metadata). ### Description - `Allure::description_html: (String html)` Set the test's [description](/docs/v2/readability/#description). You can either [begin a Scenario with a description](https://cucumber.io/docs/gherkin/reference/#feature) in your Gherkin file or call `Allure.description_html()` for updating it dynamically. **Runtime API:** ```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 description:** ```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](/docs/v2/readability/#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](/docs/v2/readability/#tags). You can either use the [tags in your Gherkin file](https://cucumber.io/docs/cucumber/api/?lang=java#tags) or call `Allure.tag()` for setting tags dynamically. **Gherkin tags:** ```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" ``` **Runtime API:** ```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](/docs/v2/readability/#severity). By default, Allure Cucumber.rb will look for a Gherkin tag with the `@SEVERITY:` prefix. The prefix [can be changed in the configuration](/docs/cucumberrb-configuration/#gherkin-tag-prefixes). 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](/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 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](/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 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](/docs/cucumberrb-configuration/#link-issue-pattern-link-tms-pattern) 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](/docs/cucumberrb-configuration/#gherkin-tag-prefixes)). 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](/docs/v2/navigation/#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](/docs/cucumberrb-configuration/#gherkin-tag-prefixes). Note that due to a limitation in the Gherkin syntax, the value cannot contain spaces. **Runtime API:** ```ruby require 'allure-cucumber' When 'I open labels page' do Allure.epic 'Web interface' Allure.feature 'Essential features' Allure.story 'Authentication' # ... end ``` **Gherkin tags:** ```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](/docs/v2/navigation/#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](/docs/steps/) 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`. **Annotated steps:** ```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 ``` **Block-based steps and no-op steps:** ```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](#scenario-outlines), - [runtime parameters](#runtime-parameters). ### Scenario outlines In Gherkin, a [`Scenario Outline`](https://cucumber.io/docs/gherkin/reference#scenario-outline) (or a `Scenario Template`) implements the [parametrized tests](/docs/v2/readability/#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: , , , 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](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-sub-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. If a Gherkin step has a [data table](https://cucumber.io/docs/gherkin/reference/#data-tables), 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 ```