# Cucumber

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/ruby/2026.3/llms.txt).

[Cucumber](https://github.com/cucumber/cucumber) is a test framework for behavior-driven Ruby development. Cucumber scenarios are written using the Gherkin syntax and stored in `.feature` files. Each scenario has multiple steps that link to step definitions representing Ruby blocks.

RubyMine integrates with Cucumber and allows you to run tests, create step definitions, navigate between features and step definitions, and so on. In this topic, we'll walk through the main IDE capabilities that help you work with Cucumber for Ruby development. To learn how RubyMine helps you work with Cucumber for JavaScript development, refer to [Cucumber.js](running-cucumber-js-unit-tests.html).

> **Tip:**
> Learn Cucumber basics from the following topics:
>
>
>
> * [Get Started](https://cucumber.io/docs/guides/10-minute-tutorial/)
>
> * [Ruby Tools](https://cucumber.io/docs/tools/ruby/)

## Prerequisites

Before working with Cucumber in RubyMine, make sure that:

* The [Gherkin](https://plugins.jetbrains.com/plugin/9164-gherkin) repository plugin is installed and enabled. For more information, refer to [Managing plugins](managing-plugins.html).

* Depending on the project type (Ruby or Rails), the 'cucumber' or 'cucumber-rails' gems are added to the `Gemfile` and installed to the project's interpreter. Learn how to install gems using RubyMine from the [Bundler](using-the-bundler.html) topic.

## Enable Cucumber support in Rails applications

Procedure:

1. Add the 'cucumber-rails' gem to the `test` group of the project's `Gemfile` and [install](using-the-bundler.html) it.

2. Go to `Tools | Run Rails Generator` and start typing cucumber:install. Select the corresponding command from the list and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

![Run generator](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_rails_generator_install.png)

3. In the Setup Cucumber Support dialog, choose the test framework for Cucumber, specify the required options, and click OK.

![Setup Cucumber Support](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_setup_support_dialog.png)

RubyMine will run the `cucumber:install` generator that sets up Cucumber in your Rails project and generates necessary files in the `features` directory. After running this generator, you will also get a new Rake task called `cucumber` that can be used to [run Cucumber tests](#run_tests) in RubyMine.

## Create a feature file

Procedure:

1. In the Project tool window, right-click a directory, where feature files should be created.

2. From the context menu of this directory, choose `New | File` `Alt+Insert` (Windows), `⌘ N` (macOS), `⌃ N` (IntelliJ IDEA Classic (macOS)), `⌘ N` (macOS System Shortcuts), `Alt+Insert` (XWin), `Alt+Insert` (GNOME), `Alt+Insert` (KDE), `Alt+Insert` (Emacs), `Ctrl+N` (Sublime Text), `⌘ N` (Sublime Text (macOS)), `Ctrl+N` (Visual Studio), `⌘ N` (Visual Studio (macOS)), `Meta+Shift+N` (TextMate), `Alt+Insert` (NetBeans), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS)), and create a file with the `.feature` extension.

![New feature file](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_new_feature_file_dialog.png)

3. In the created feature file, type your scenario. For example, we'll use a code snippet from the [Cucumber Getting Started](https://cucumber.io/docs/guides/10-minute-tutorial/):

```
Feature: Is it Friday yet?
  Everybody wants to know when it's Friday

Scenario: Sunday isn't Friday
  Given today is Sunday
  When I ask whether it's Friday yet
  Then I should be told "Nope"
```

Since there are no step definitions, the steps will be highlighted as unresolved. See the [next chapter](#create_step_definition) to learn how to create step definitions.

## Create step definitions

When you're editing a feature file, RubyMine detects and highlights the steps where definitions are missing. You can generate missing step definitions in the following way:

Procedure:

1. Place the caret at the step without a definition, press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (TextMate), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)), and select Create step definition or Create all step definitions.

![Create step definition](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_create_step_definition_intention.png)

2. Choose whether to use the existing step definition file or create a new one.

![Choose step definition file](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_choose_step_definition_file_popup.png)

Press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

3. (Optional) If you selected Create new file, specify the name for the new file and the language for writing definitions.

![Create New Step Definition File](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_new_step_definition_dialog.png)

Click OK.

4. In the opened Ruby file, write step definition code.

```RUBY
Given('today is Sunday') do
  @today = 'Sunday'
end
```

## Run tests

RubyMine allows you to run either individual Cucumber scenarios or all scenarios from the specified folder or file. You can also run scenarios using [Rake](rake.html) tasks.

Procedure: Run multiple tests from a folder

* In the Project view, right-click the desired folder and select Run 'All features in ...'.

![Run tests from Project view](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_run_project_view.png)

To run a specific subset of tests, for example, only scenarios which match a certain name or marked with a specific tag, customize the  [Cucumber run/debug configuration](#cucumber_run_config).

Procedure: Run tests from the editor

To run tests from the editor, do one of the following:

* Open the `.feature` file and click the Run button in the gutter next to the required feature or scenario. Then, select the required run command from the context menu.

![Run test from gutter](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_run_scenario_gutter.png)

* Place the caret at the required feature or scenario, press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (TextMate), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)), select the required run action, and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

![Run tests with Alt Enter](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_run_scenario_alt_enter.png)

Procedure: Run tests using a Rake task

* Press `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (TextMate), `Ctrl` (NetBeans), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS)) twice to invoke the Run Anything popup. Start typing the required task name, select it from the list and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

![Run cucumber using rake](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_run_rake_task.png)

After executing tests, you can analyze [results](viewing-and-exploring-test-results.html) in the Run tool window.

## Cucumber run/debug configuration

When you run Cucumber tests using a context menu or from the editor, RubyMine automatically creates a corresponding Cucumber [temporary configuration](run-debug-configuration.html#temp_config), which can be saved. If necessary, you can create the Cucumber run/debug configuration [manually](run-debug-configuration.html#createExplicitly) from the predefined template.

To customize and run the created configuration, do the following:

Procedure:

1. Press `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Meta+Shift+A` (TextMate), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)) and start typing edit configurations. Select Edit Configurations and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

![Find Action](https://resources.jetbrains.com/help/img/idea/2026.3/ij_ruby_find_action_edit_config.png)

2. In the opened Run/Debug Configurations dialog, select the required configuration, and specify its settings.

![Run/Debug Configurations](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_run_configuration_dialog.png)

For example, you can specify the following settings:

| Option | Description |
| --- | --- |
|     Mode     |     Choose whether to run all features in a directory or file.     |
|     Features folder / Feature file     |     Specify the full path to the folder/file that contains the desired features.     |
|     Element name filter     |     Allows you to run only scenarios that match a certain name. This can be a substring of the names of Features, Scenarios, Scenario Outlines, or Example blocks. Learn more at [Cucumber help](https://relishapp.com/cucumber/cucumber/docs/cli/run-feature-elements-matching-a-name-with-name-n).     |
|     Tags filter     |     Specify tags to run subsets of features. Learn more at [Tag logic](https://relishapp.com/cucumber/cucumber/docs/cli/tag-logic).     |
|     Runner options     |     Specify the required options for running Cucumber tests. For example, the `-r features` parameter loads files from the `features` folder before running tests.     |
|     'Cucumber' gem     |     Select the Cucumber gem used to run tests.     |
|     Use custom Cucumber runner script     |     Enable this option if you want to use an alternative Cucumber runner script. You can type the full path to the Cucumber runner script in the text field, or click ![Browse](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.menu-open.svg), and select the desired runner script in the dialog that opens.     |

Click OK to save the run/debug configuration.

3. To run the saved configuration, press `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (TextMate), `Ctrl` (NetBeans), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS)) twice, start typing the configuration name, select it from the list, and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

![Run Cucumber using run anything](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_run_configuration.png)

## Scenario outlines and examples

The `Scenario Outline` can be used to run the same Scenario multiple times, with different combinations of values. These values are stored in the `Examples` table. You can learn more from [Cucumber help](https://cucumber.io/docs/gherkin/reference/#scenario-outline).

RubyMine allows you to convert scenarios to outlines and generate missing `Examples` tables.

Procedure: Convert Scenario to Outline

1. Place the caret at the desired scenario and press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (TextMate), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)).

2. Select Convert scenario to outline and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

![Convert scenario to outline](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_convert_scenario_to_outline.png)

RubyMine will change `Scenario` to `Scenario Outline` and add the `Examples` table.

![Convert scenario to outline](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_convert_scenario_to_outline_result.png)

Procedure: Create Examples in Scenario Outline

RubyMine provides an inspection to detect examples missing in scenario outlines. To create missing examples, do the following:

1. Place the caret at the highlighted scenario outline and press `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (TextMate), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS)).

2. Select Create Examples Section and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (TextMate), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

![Create Examples in Scenario Outline](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_create_examples_outline.png)

RubyMine will create the `Examples` table with a header row.

## Navigation

Procedure:

* To jump from a step in a `.feature` file to the step definition, press and hold `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (TextMate), `Ctrl` (NetBeans), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS)), hover over the step, and click the step when it turns into a link.

![Navigate from feature to step definition](https://resources.jetbrains.com/help/img/idea/2026.3/rm_cucumber_navigate_feature_step_definition.animated.gif)

## Configuring syntax highlighting

You can configure Cucumber-aware syntax highlighting in the following way:

Procedure:

1. In the Settings dialog (`Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Meta+Comma` (TextMate), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))), go to `Editor | Color Scheme | Cucumber`.

2. Select the color scheme, accept the highlighting settings inherited from defaults or customize them as described in [Configuring Colors and Fonts](configuring-colors-and-fonts.html).

## See also

