cucumber-website-a2557b8d5a9637c8.txt

Directory structure:
└── docs/
    ├── contributing.md
    ├── faq.md
    ├── index.md
    ├── ztest-polyglot-once.mdx
    ├── bdd/
    │   ├── _category_.json
    │   ├── better-gherkin.md
    │   ├── discovery-workshop.md
    │   ├── example-mapping.md
    │   ├── examples.md
    │   ├── history.md
    │   ├── index.md
    │   ├── myths.md
    │   └── who-does-what.md
    ├── cucumber/
    │   ├── _category_.json
    │   ├── api.mdx
    │   ├── checking-assertions.md
    │   ├── configuration.mdx
    │   ├── cucumber-expressions.md
    │   ├── debugging.mdx
    │   ├── environment-variables.md
    │   ├── index.mdx
    │   ├── mocking-and-stubbing-with-cucumber.md
    │   ├── reporting.md
    │   ├── state.mdx
    │   └── step-definitions.mdx
    ├── gherkin/
    │   ├── _category_.json
    │   ├── index.mdx
    │   ├── languages.mdx
    │   ├── reference.md
    │   └── step-organization.mdx
    ├── guides/
    │   ├── 10-minute-tutorial.mdx
    │   ├── _category_.json
    │   ├── anti-patterns.mdx
    │   ├── api-automation.md
    │   ├── browser-automation.mdx
    │   ├── continuous-integration.md
    │   ├── index.mdx
    │   ├── parallel-execution.mdx
    │   ├── testable-architecture.md
    │   └── upgrading.md
    ├── installation/
    │   ├── _category_.json
    │   ├── amp-cucumber-cpp-runner.md
    │   ├── android.md
    │   ├── clojure.md
    │   ├── cplusplus.md
    │   ├── cwt-cucumber.md
    │   ├── d.md
    │   ├── gobdd.md
    │   ├── gocuke.md
    │   ├── golang.md
    │   ├── gosu.md
    │   ├── groovy.md
    │   ├── index.mdx
    │   ├── ios.md
    │   ├── java.md
    │   ├── javascript.md
    │   ├── jruby.md
    │   ├── jython.md
    │   ├── kotlin.md
    │   ├── lua.md
    │   ├── ocaml.md
    │   ├── perl.md
    │   ├── php.md
    │   ├── pytest-bdd.md
    │   ├── python.md
    │   ├── r.md
    │   ├── reqnroll.md
    │   ├── ruby.md
    │   ├── rust.md
    │   ├── scala.md
    │   ├── tcl.md
    │   └── xunit-gherkin-quick.md
    ├── terms/
    │   ├── _category_.json
    │   ├── index.mdx
    │   └── user-story.md
    └── tools/
        ├── _category_.json
        ├── index.mdx
        ├── java.md
        ├── javascript.md
        ├── related-tools.md
        └── ruby.md

================================================
FILE: docs/contributing.md
================================================
---
description: Help us make Cucumber better
---

# Contributing

You want to contribute to Cucumber, great!

## You have a question

You can [get in touch](/community) via Discord or GitHub Discussions, or try Stack Overflow. 

## You found a bug

There are several different flavours of Cucumber for different programming languages. Try to file your issue in the repo for the Cucumber flavour you're using:

* [Cucumber JVM](https://github.com/cucumber/cucumber-jvm/issues/new)
* [Cucumber JS](https://github.com/cucumber/cucumber-js/issues/new)
* [Cucumber Ruby](https://github.com/cucumber/cucumber-ruby/issues/new)
* [Godog](https://github.com/cucumber/godog/issues/new)

If you're not sure, open an issue in the [common](https://github.com/cucumber/common/issues/new/choose) repo, and we'll take it from there.

## You want to update the documentation

Improvements to documentation are really valuable! See the [contribution guidelines](https://github.com/cucumber/website/blob/main/CONTRIBUTING.md) for the repo that drives this site for details.

## You want to contribute but don't know how

If you enjoy using Cucumber, consider [sponsoring us](/sponsors).





================================================
FILE: docs/faq.md
================================================
---
description: Frequently-asked questions
---

# FAQs

## Getting started and help

### How do I get started with Cucumber?

To get started from scratch, try the [10-minute tutorial](./guides/10-minute-tutorial.mdx).

You can read these docs to learn more about [Gherkin](./gherkin/reference.md), [Cucumber](./cucumber/api.mdx) and [BDD](./bdd/index.md).

### Where can I get more in-depth information?

If you'd like to go more in-depth, try one of the following:

- [Books](/learn)
- [Cucumber School (online training)](https://school.cucumber.io)

### Where can I get help?

For questions, you can [get in touch](/community) with the community.

## Installing and running Cucumber

### How do I install Cucumber?

How to install Cucumber, depends on which programming language you are using.

You can find information on how to install your flavour of Cucumber on the [installation](/docs/installation) page.

### Which version of Cucumber should I use?

In general, it is recommended to use the most recently released version of Cucumber for your programming language.
Each release will fix known bugs and/or add new features.

You can find the most recent version of Cucumber either in the [10-minute tutorial](/docs/guides/10-minute-tutorial), the [installation](/docs/installation) page or on [GitHub](https://github.com/cucumber).

### How should I upgrade to a newer version?

See our [guide to upgrading](./guides/upgrading.md).

### How do I run Cucumber?

For information on how to run Cucumber, see [Running Cucumber](/docs/cucumber/api/#running-cucumber).

### How do I run Cucumber from the CLI?

For information on how to run the Cucumber CLI, see [From the command line](/docs/cucumber/api/#from-the-command-line).

### What are the configuration options for running Cucumber?

For information about configuration options, see [Configuration](/docs/cucumber/configuration/).

## Usage and troubleshooting

### How do I call other steps or scenarios?
Each scenario should be *independent*; you should be able to run them in any order or in parallel without one scenario interfering with another.

Each scenario should *test exactly one thing* so that when it fails, it fails for a clear reason. This means you wouldn't reuse one scenario inside another scenario.

If your scenarios use the same or similar steps, or perform similar actions on your system, you can extract [helper methods](#how-to-use-helper-methods) to do those things.

#### How to use helper methods

Helper methods allow you to re(use) actions in steps and avoid writing multiple step definitions for similar behaviours. You write a helper method for actions like *logging in to your application* and then reuse them as a step or part of other steps.
This helps keep your tests clean, concise and maintainable.

To learn more about using helper methods, check out [Helper methods](/docs/gherkin/step-organization/#helper-methods) and [Grouping step definitions](/docs/gherkin/step-organization/#grouping-step-definitions).

### How detailed should my scenarios be?

Your scenarios should contain *just enough* information to describe the *behaviour* of the system.
They should not describe the implementation of your application, as that might change - causing your tests to fail.
They shouldn't contain too many details, as this will distract from the actual *behaviour*.

Let's illustrate this with an example.
Imagine we have a process where the user will be notified of the result.
At the moment that might be implemented as sending them an email, but that might change in the future (for instance, to a text message).
You can specify the step as follows:

```gherkin
Then the user will be notified
```

This way, if the implementation of how the user is notified changes, you will only have to change the step definition (or the helper method called by that step definition),
rather than the step itself **and** all underlying code.

For more information, have a look at [Writing better Gherkin](/docs/bdd/better-gherkin/) and/or [Writing maintainable automated acceptance tests (pdf).](http://dhemery.com/pdf/writing_maintainable_automated_acceptance_tests.pdf)

### How can I specify my test cases in Excel/CSV?

We advise you *not* to use Excel or csv files to define your test cases; using Excel or csv files is considered an anti-pattern.

One of the goals of Cucumber is to have *executable specifications*. This means your feature files should contain just the right level of information to document the expected behaviour of the system.
If your test cases are kept in separate files, how would you be able to read the documentation?

This also means you shouldn't have too many details in your feature file. If you do, you might consider moving them to your step definitions or [helper methods](#how-to-use-helper-methods).
For instance, if you have a form where you need to populate lots of different fields, you might use the [Builder pattern](https://en.wikipedia.org/wiki/Builder_pattern) to do so.

### How can I make Cucumber conditionally skip steps

Each scenario should test *one thing* and fail for one particular reason. This means there should be no reason to skip steps.

If there does seem to be a reason you'd want to skip steps conditionally, you probably have an anti-pattern.
For instance, you might be trying to test multiple things in one scenario or you might not be in control of the state of your test environment or test data.

The best thing to do here is to fix the root cause.

### How can I make Cucumber run the skipped steps after a failed step

Cucumber skips all steps after a failed step by design. Once a step has failed, the test has failed and there should be no reason to perform the next steps.
If you have a need to run the additional steps, likely your scenario is testing too many different things at once. Consider splitting your scenario into smaller tests.

### How do I take a screenshot after a (failed) step?

See our [browser automation guide](./guides/browser-automation.mdx).

### How do I share state between steps?

The JavaScript and Ruby implementations of Cucumber have the [world object](/docs/cucumber/state/#world-object) for sharing state between steps.

If you are using Cucumber on the JVM, you can use [dependency injection (DI)](/docs/cucumber/state/#dependency-injection) to share state between steps. If your project already uses a dependency framework supported by Cucumber (and/or you are familiar with one of them), it's probably easiest to use that framework. Otherwise, Picocontainer is the most light weight framework you can use.

## Cucumber-JVM

### Cucumber says my steps are undefined, but I have implemented step definitions!

If Cucumber is telling you that your steps are undefined, when you have defined step definitions, this means that Cucumber cannot *find* your step definitions.
You'll need to make sure to specify the path to your step definitions (glue path) correctly.

By default Cucumber-JVM will search in the package (or sub-packages) of the runner class.
You can also tell Cucumber-JVM explicitly which packages (and sub-packages) to search, with:
 ```java
 @CucumberOptions(glue = {"<package>", "<package>", "<etc>"})
 public class RunCucumberTest{}
```
 ```kotlin
 @CucumberOptions(glue = ["<package>", "<package>", "<etc>"])
 class RunCucumberTest
```

### Cucumber expressions vs regex

For more information about Cucumber expressions, see the section on [Cucumber expressions](/docs/cucumber/cucumber-expressions/).

You can still use regular expression (regex) also, but you cannot use Cucumber expressions and regular expressions in the same step definition.

Cucumber expressions were added in Cucumber-JVM version 3.0.0.

Note that a step definition using regex will start with `^` and end with `$`, while a step definition using Cucumber expressions will not.

An example using regex:
```java
    @Given("^today is ([0-9]{4}-[0-9]{2}-[0-9]{2})$")
    public void today_is(Date date) {
        calculator = new DateCalculator(date);
    }
```

An example using Cucumber expressions:
```java
    @When("I add {int} and {int}")
    public void adding(int arg1, int arg2) {
        calc.push(arg1);
        calc.push(arg2);
        calc.push("+");
    }
```

### How do I use lambdas to define step definitions?

To use lambdas to define your step definitions, make sure to use the `cucumber-java8` dependency, instead of the `cucumber-java` dependency.
You can find the required dependencies [here](./installation/java.md).

For an example on how to use them in Java, see this [code example](https://github.com/cucumber/cucumber-jvm/blob/main/examples/calculator-java8-cli/src/test/java/io/cucumber/examples/calculator/RpnCalculatorSteps.java). For Kotlin, see this [code example](https://github.com/cucumber/cucumber-jvm/blob/main/cucumber-kotlin-java8/src/test/kotlin/io/cucumber/kotlin/LambdaStepDefinitions.kt).

### Getting weird characters in the console output

If you are getting some weird additional characters in the output of your steps, like `[32m`, this is a problem with escaping ANSI color codes.

In order to prevent this problem, you can set the option `monochrome` to `true.

If you are using Eclipse, you might try this [plugin](https://marketplace.eclipse.org/content/ansi-escape-console).

### Arity mismatch

An arity mismatch exception (`cucumber.runtime.CucumberException: Arity mismatch`) indicates that the step does not provide the right number of arguments needed for the step definition.

### Duplicate step definition

A DuplicateStepDefinitionException indicates that you have defined the same step twice. First of all, Cucumber doesn't
distinguish between [keywords](./gherkin/reference.md#keywords) used with a particular step when
[matching steps](/docs/cucumber/api/#matching-steps). This means that `Given an order exists` and `Then an order exists`
will both match "an order exists". When providing arguments using Cucumber expressions and/or regular expressions,
multiple steps might match the same expression. Finally, this means that you cannot extend a class which defines step
definitions, as that will lead to duplicates.

### Does Cucumber-JVM support Kotlin?

You can use [Cucumber-JVM](https://github.com/cucumber/cucumber-jvm) to write step definitions in Kotlin. Please have a look at the [Kotlin examples for cucumber-jvm](https://github.com/cucumber/cucumber-jvm/tree/master/cucumber-kotlin-java8). 
At the moment it is not possible to generate step definitions in Kotlin. The reason for this is that there is no Kotlin Backend implemented. If this is something you'd like to work on, there is [a request for one](https://github.com/cucumber/cucumber-jvm/issues/1520). There is also a request for a [native Kotlin implementation of Cucumber](https://github.com/cucumber/cucumber/issues/331).

### Cucumber can't find my step definitions in IntelliJ IDEA

In this instance, you need to configure a new run configuration in IntelliJ IDEA. 
1. Click **Run** > **Edit Configurations** from the menu in IntelliJ IDEA.
2. Click the **+** icon on the top-left and type in _cucumber_. Select **Cucumber Java**.
3. Create the configuration according to the [Run/Debug Configuration Cucumber Java](https://www.jetbrains.com/help/idea/run-debug-configuration-cucumber-java.html) instructions from JetBrains. 
   
If IntelliJ IDEA doesn't recognize the package with step definitions, you can specify it manually by entering the package name in the Glue field, for example _stepdefs_.

For more information, please see [Run Cucumber Tests](https://www.jetbrains.com/help/idea/running-cucumber-tests.html) from JetBrains documentation.

### How do I fix an error where the stacktrace contains `Failed to instantiate public cucumber.runtime.java.JavaBackend` or `NoSuchMethodException`?

Check that the Cucumber version is the same for all Cucumber dependencies and make sure you only have the required dependencies. This means you need to ensure that you get the transitive dependencies that go with the version of Cucumber that you have. 

You can see all your Maven dependencies, including transitive ones by running `mvn dependency:tree`. 

If you're using any other library which also contains a dependency on Cucumber (a transitive dependency), try excluding
that transitive dependency in your pom file to ensure only one version of Cucumber is being referenced. Please refer to
the Maven [instructions for excluding dependencies](https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html#dependency-exclusions) for steps on excluding transitive dependencies.



================================================
FILE: docs/index.md
================================================
---
sidebar_position: 0
---

# Introduction

Cucumber is a tool that supports [Behaviour-Driven Development (BDD)](./bdd/index.md).
If you're new to Behaviour-Driven Development read our [BDD introduction](./bdd/index.md)
first.

## What is Cucumber?

Ok, now that you know that BDD is about discovery, collaboration and examples
(and not testing), let's take a look at Cucumber.

Cucumber reads executable specifications written in plain text and validates
that the software does what those specifications say. The specifications
consist of multiple *examples*, or *scenarios*. For example:

```gherkin
Scenario: Breaker guesses a word
  Given the Maker has chosen a word
  When the Breaker makes a guess
  Then the Maker is asked to score
```

Each scenario is a list of *steps* for Cucumber to work through. Cucumber
verifies that the software conforms with the specification and generates a
report indicating ✅ success or ❌ failure for each scenario.

In order for Cucumber to understand the scenarios, they must follow some basic
syntax rules, called [Gherkin](./gherkin/index.mdx).

## What is Gherkin?

Gherkin is a set of grammar rules that makes plain text structured enough for
Cucumber to understand. The scenario above is written in Gherkin.

Gherkin serves multiple purposes:

- Unambiguous executable specification
- Automated testing using Cucumber
- Document how the system *actually* behaves

![Single source of truth](/img/docs/single-source-of-truth.png)

The Cucumber grammar exists in different flavours for many [spoken languages](./gherkin/reference.md#spoken-languages)
so that your team can use the keywords in your own language.

Gherkin documents are stored in `.feature` text files and are typically
versioned in source control alongside the software.

See the [Gherkin reference](./gherkin/reference.md) for more details.

## What are step definitions?

[Step definitions](./cucumber/step-definitions.mdx) connect Gherkin steps to
programming code. A step definition carries out the action that should be
performed by the step. So step definitions hard-wire the specification to the
implementation.

```
┌────────────┐                 ┌──────────────┐                 ┌───────────┐
│   Steps    │                 │     Step     │                 │           │
│ in Gherkin ├──matched with──>│ Definitions  ├───manipulates──>│  System   │
│            │                 │              │                 │           │
└────────────┘                 └──────────────┘                 └───────────┘
```

Step definitions can be written in many programming languages. Here is an example
using JavaScript:

```javascript
When('{maker} starts a game', maker => {
  maker.startGameWithWord({ word: 'whale' })
})
```




================================================
FILE: docs/ztest-polyglot-once.mdx
================================================
---
unlisted: true
---

# TEST: Polyglot Once

<Tabs once="java,kotlin,scala,javascript,ruby"/>

## Generic content

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas scelerisque vitae quam vel interdum. Nunc porttitor pharetra sodales. Fusce tempor risus finibus, maximus sem ornare, efficitur metus. Morbi urna mi, gravida in tortor in, aliquet porta nunc. Integer justo diam, vehicula ut iaculis sit amet, varius et risus. Integer rhoncus, mi in viverra dapibus, ligula ligula molestie sapien, ut hendrerit ex ligula et neque. Nullam efficitur egestas nibh, in sodales ex dapibus vel. Quisque est nunc, sollicitudin vitae consectetur quis, elementum vel arcu. Integer volutpat iaculis mi et porttitor.

Nullam rutrum justo a nisi luctus semper. Nullam ut mollis metus. Curabitur viverra magna sit amet aliquam efficitur. Cras sed sem eleifend, pellentesque dui sed, pellentesque lectus. Integer velit magna, cursus pretium tellus a, porta vehicula risus. Aliquam eget ultrices ligula. Nunc ac enim sapien. Morbi in lorem eget leo iaculis tincidunt. Donec tincidunt molestie dolor a venenatis. Curabitur aliquam varius est non elementum. Sed et diam ut ante blandit cursus. Ut a felis fringilla, tristique diam vel, eleifend nibh. Phasellus tristique laoreet volutpat. Etiam non ipsum iaculis, porta lacus a, scelerisque magna. Integer justo arcu, malesuada vel molestie eget, euismod fringilla ipsum.

Aenean eget mattis augue, quis laoreet odio. Donec sed mi lectus. Nunc vitae arcu vitae magna malesuada feugiat in non nibh. Morbi felis magna, congue efficitur tempor eu, rhoncus et nunc. Proin eu est ac risus ullamcorper egestas vitae ac nunc. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Mauris semper tortor leo. Duis sit amet elit at odio maximus tempus. In hac habitasse platea dictumst. Mauris dignissim quam quis elementum dignissim. Cras nec neque eu tortor semper fringilla a eu lacus.

Nam eleifend euismod pulvinar. Sed id risus diam. Duis nec ullamcorper ligula. Ut scelerisque in erat eget bibendum. Sed sed lacus nec lorem finibus dignissim a quis massa. Donec ultricies justo ut orci volutpat posuere. Nunc efficitur malesuada urna, quis scelerisque tortor imperdiet venenatis. Sed cursus dictum iaculis. Nulla in nulla sit amet nibh dapibus imperdiet quis ut nulla. Nullam accumsan, mauris a ultricies imperdiet, orci lacus sodales augue, ut euismod elit nisi ac est. Nullam ac sapien vitae augue accumsan sodales sed et nunc.

Ut nulla nunc, commodo et euismod id, dictum sollicitudin nunc. Praesent et dui venenatis tellus semper consectetur non sed ipsum. Ut a ultricies lectus. Praesent est est, consectetur ullamcorper sapien euismod, volutpat lobortis velit. Nam nec odio vitae lorem egestas viverra. Proin fermentum tortor ut lacus fringilla, interdum auctor massa faucibus. Suspendisse dignissim porta velit, at congue mi malesuada eu. Aliquam commodo nisi erat, nec posuere magna sagittis rhoncus. Maecenas ac felis laoreet, aliquet nulla eget, ullamcorper tellus. Duis enim augue, ornare vitae lacus vel, porta posuere ex. Sed pretium nunc ac suscipit finibus. Aenean sagittis ipsum sit amet sapien venenatis lacinia. Curabitur sed diam nulla. Fusce id urna lacus.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas scelerisque vitae quam vel interdum. Nunc porttitor pharetra sodales. Fusce tempor risus finibus, maximus sem ornare, efficitur metus. Morbi urna mi, gravida in tortor in, aliquet porta nunc. Integer justo diam, vehicula ut iaculis sit amet, varius et risus. Integer rhoncus, mi in viverra dapibus, ligula ligula molestie sapien, ut hendrerit ex ligula et neque. Nullam efficitur egestas nibh, in sodales ex dapibus vel. Quisque est nunc, sollicitudin vitae consectetur quis, elementum vel arcu. Integer volutpat iaculis mi et porttitor.

Nullam rutrum justo a nisi luctus semper. Nullam ut mollis metus. Curabitur viverra magna sit amet aliquam efficitur. Cras sed sem eleifend, pellentesque dui sed, pellentesque lectus. Integer velit magna, cursus pretium tellus a, porta vehicula risus. Aliquam eget ultrices ligula. Nunc ac enim sapien. Morbi in lorem eget leo iaculis tincidunt. Donec tincidunt molestie dolor a venenatis. Curabitur aliquam varius est non elementum. Sed et diam ut ante blandit cursus. Ut a felis fringilla, tristique diam vel, eleifend nibh. Phasellus tristique laoreet volutpat. Etiam non ipsum iaculis, porta lacus a, scelerisque magna. Integer justo arcu, malesuada vel molestie eget, euismod fringilla ipsum.

Aenean eget mattis augue, quis laoreet odio. Donec sed mi lectus. Nunc vitae arcu vitae magna malesuada feugiat in non nibh. Morbi felis magna, congue efficitur tempor eu, rhoncus et nunc. Proin eu est ac risus ullamcorper egestas vitae ac nunc. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Mauris semper tortor leo. Duis sit amet elit at odio maximus tempus. In hac habitasse platea dictumst. Mauris dignissim quam quis elementum dignissim. Cras nec neque eu tortor semper fringilla a eu lacus.

Nam eleifend euismod pulvinar. Sed id risus diam. Duis nec ullamcorper ligula. Ut scelerisque in erat eget bibendum. Sed sed lacus nec lorem finibus dignissim a quis massa. Donec ultricies justo ut orci volutpat posuere. Nunc efficitur malesuada urna, quis scelerisque tortor imperdiet venenatis. Sed cursus dictum iaculis. Nulla in nulla sit amet nibh dapibus imperdiet quis ut nulla. Nullam accumsan, mauris a ultricies imperdiet, orci lacus sodales augue, ut euismod elit nisi ac est. Nullam ac sapien vitae augue accumsan sodales sed et nunc.

Ut nulla nunc, commodo et euismod id, dictum sollicitudin nunc. Praesent et dui venenatis tellus semper consectetur non sed ipsum. Ut a ultricies lectus. Praesent est est, consectetur ullamcorper sapien euismod, volutpat lobortis velit. Nam nec odio vitae lorem egestas viverra. Proin fermentum tortor ut lacus fringilla, interdum auctor massa faucibus. Suspendisse dignissim porta velit, at congue mi malesuada eu. Aliquam commodo nisi erat, nec posuere magna sagittis rhoncus. Maecenas ac felis laoreet, aliquet nulla eget, ullamcorper tellus. Duis enim augue, ornare vitae lacus vel, porta posuere ex. Sed pretium nunc ac suscipit finibus. Aenean sagittis ipsum sit amet sapien venenatis lacinia. Curabitur sed diam nulla. Fusce id urna lacus.

## Polyglot content

<Content lang="java,kotlin,scala">
    Here's some JVM stuff.
</Content>

<Content lang="javascript">
    ```js
    console.log('here')
    ```
</Content>

<Content lang="ruby">
    Gems!
</Content>


================================================
FILE: docs/bdd/_category_.json
================================================
{
  "position": 4,
  "label": "Behaviour-Driven Development"
}



================================================
FILE: docs/bdd/better-gherkin.md
================================================
---
sidebar_position: 7
---

# Writing better Gherkin

There are several ways to make your Gherkin better.

## Describe behaviour

Your scenarios should describe the intended behaviour of the system, not the implementation.
In other words, it should describe *what*, not *how*.

For example, for an authentication Scenario, you should write:

```gherkin
When "Bob" logs in
```

instead of:

```gherkin
  Given I visit "/login"
  When I enter "Bob" in the "user name" field
    And I enter "tester" in the "password" field
    And I press the "login" button
  Then I should see the "welcome" page
```

The first example, **When "Bob" logs in**, is a *functional requirement*. The second, much longer, example is a *procedural reference*.
Functional requirements are features, but procedures belong in the implementation details.

That way, when the implementation of a feature changes, you'll only need to change the process steps behind the scenes.
The behaviour does not have to change just because the implementation does.
In fact, a good question to ask yourself when writing a feature clause is: “Will this wording need to change if the implementation does?”.

If the answer is “Yes”, then you should rework it avoiding implementation specific details.
As a side benefit, in consequence your scenarios will be a lot shorter and much easier to follow and understand.

## Consider a more declarative style

One way to make scenarios easier to maintain and less brittle is to use a declarative style. Declarative style describes the behaviour of the application, rather than the implementation details. Declarative scenarios read better as "living documentation". A declarative style helps you focus on the value that the customer is getting, rather than the keystrokes they will use.

Imperative tests communicate details, and in some contexts this style of test is appropriate. On the other hand, because they are so closely tied to the mechanics of the current UI, they often require more work to maintain. Any time the implementation changes, the tests need to be updated too.

Here's an example of a feature in an imperative style:

```gherkin
Feature: Subscribers see different articles based on their subscription level 

Scenario: Free subscribers see only the free articles
  Given users with a free subscription can access "FreeArticle1" but not "PaidArticle1" 
  When I type "freeFrieda@example.com" in the email field
  And I type "validPassword123" in the password field
  And I press the "Submit" button
  Then I see "FreeArticle1" on the home page
  And I do not see "PaidArticle1" on the home page

Scenario: Subscriber with a paid subscription can access "FreeArticle1" and "PaidArticle1"
  Given I am on the login page
  When I type "paidPattya@example.com" in the email field
  And I type "validPassword123" in the password field
  And I press the "Submit" button
  Then I see "FreeArticle1" and "PaidArticle1" on the home page  
```

Each step is a precise instruction. The inputs and expected results are specified exactly. But it's easy to imagine changes to the application which would require changing these tests. The available options for free versus paid subscriptions can change. Even the means of logging in could change. What if, in the future, users log in with a voice interface or a thumbprint? 

A more declarative style hides the details of how the application's capabilities are implemented.

```gherkin
Feature: Subscribers see different articles based on their subscription level
 
Scenario: Free subscribers see only the free articles
  Given Free Frieda has a free subscription
  When Free Frieda logs in with her valid credentials
  Then she sees a Free article

Scenario: Subscriber with a paid subscription can access both free and paid articles
  Given Paid Patty has a basic-level paid subscription
  When Paid Patty logs in with her valid credentials
  Then she sees a Free article and a Paid article
``` 

With a declarative style, each step communicates an idea, but the exact values aren't specified. The details of *how* the user interacts with the system, such as which specific articles are free or paid, and the subscription level of different test users, are specified in the step definitions (the automation code that interacts with the system). The subscription packages could change in the future. The business could change what content is available to subscribers on free and paid plans, without having to change this scenario and other scenarios that use the same step definitions. If another subscription level is added later, it's easy to add a scenario for that. By avoiding terms like “click a button” that suggest implementation, the scenario is more resilient to implementation details of the UI. The intent of the scenario remains the same, even if the implementation changes later. In addition, having too many implementation details in a scenario, makes it harder to understand the intended behaviour it illustrates.



================================================
FILE: docs/bdd/discovery-workshop.md
================================================
---
sidebar_position: 1
---

# Discovery workshop

## What is a discovery workshop?

A discovery workshop is a conversation where technical and business people collaborate to explore, discover and agree as much as they can about the desired behaviour for a [User Story](/docs/terms/user-story/).

## How do you conduct a discovery workshop?

There are several discovery workshop models, these are just a few:

[**Example Mapping**](/docs/bdd/example-mapping/)

Uses a pack of index cards in four different colours to map rules (a summary of constraints/acceptance criteria the team has agreed upon) to examples (illustrations/cases of the acceptance criteria)

[**OOPSI Mapping (Outcomes, Outputs, Processes, Scenarios, Inputs)**](https://jennyjmar.com/2016/04/16/bdd-discovery-and-oopsi/)

Similar to Example Mapping, uses Post-it Notes of different colours to map shared processes/relationships between outputs and scenarios.

[**Feature Mapping**](https://johnfergusonsmart.com/feature-mapping-a-simpler-path-from-stories-to-executable-acceptance-criteria/)

Also uses Post-it Notes of different colours.  The team picks a story from the backlog, identifies the actors involved, breaks the story down into tasks, and maps those tasks to specific examples.

## When should you hold a discovery workshop?

As late as possible before development on a new User Story begins, in order to prevent details from being lost. Conducting a discovery workshop as late as possible also gives the team enough leg room to shift their plans should new details surface.

## Who should attend?

A good rule-of-thumb is 3-6 people, but at a bare minimum your [Three Amigos](/docs/bdd/who-does-what/#the-three-amigos/) should be present: a product owner, a developer, and a tester.  Your product owner will identify the problem the team should be trying to solve, your developer will address how to build a solution around said problem, and your tester will address any edge cases that could arise. 

## How long does a discovery workshop take?

A discovery workshop should ideally only last about 25-30 minutes per story.  If you need any more time than this, it's likely the story is far too large and should be broken down, or some of the specifics are missing.  In the latter case, you should set aside the story as the team needs to do more research.

## Why bother?

The purpose of a discovery workshop is to give all stakeholders, both technical and non-technical, a *shared understanding* of the work at hand.  Doing so encourages cross-functional collaboration, an increase in feedback, and covers any lost details or incorrect assumptions made.

## Conclusion

A discovery workshop is a very important piece of the BDD lifecycle, among other agile development approaches.  Without it, you are sure to run into miscommunications and your team won't discover any unknowns, which could really hamper your project's success.



================================================
FILE: docs/bdd/example-mapping.md
================================================
---
sidebar_position: 2
---

# Example Mapping

Before you pull a user story into development, it’s crucial to have a conversation to clarify and confirm the acceptance criteria.

Example Mapping is a method designed to make this conversation short and very productive.

## How it works

Concrete examples are a great way to help us explore and understand the problem domain. They are a great basis for our acceptance tests.

When discussing examples, other things might come up in the conversation that deserve to be captured too:

- **rules** that summarise a set of examples, or express other constraints.
- **questions** that cannot be answered during the conversation, or assumptions that are made.
- new **user stories** discovered or sliced and deferred out of scope.

We can capture these different types of information on index cards, and arrange them in a map:

- We write the story on a **yellow** card and place it on top.
- Each of the acceptance criteria, or rules, is written on a **blue** card and placed beneath the yellow story card.
- Examples to illustrate these rules are written on a **green** card and placed under the relevant rule.
- Questions that cannot be answered during the session are captured on a **red** card so we can move on with the conversation.

We keep going until the group is satisfied that the scope of the story is clear, or we run out of time.

## More information

For more details, see Matt Wynne's blog on [Example Mapping](/blog/bdd/example-mapping-introduction).

To get started yourself, see Steve Tooke's blog on [Your first Example Mapping session](/blog/bdd/your-first-example-mapping-session).

Or have a look at the [Example Mapping Webinar](/blog/bdd/example-mapping-webinar).



================================================
FILE: docs/bdd/examples.md
================================================
---
sidebar_position: 3
---

# Examples

Good BDD examples are *concrete* rather than *abstract*. They mention names of 
people and places, exact dates and amounts, and anything that is relevant to the
problem domain of the software.

Good examples don't mention technical details.

:::info[Imagine it's 1922]
Most software does something people could do manually (just not as efficiently).

Try hard to come up with examples that don't make any assumptions about
technology. Imagine it's 1922, when there were no computers.
:::


================================================
FILE: docs/bdd/history.md
================================================
---
sidebar_position: 4
---

# History of BDD

Behavior-driven development was pioneered by [Daniel Terhorst-North](https://dannorth.net) back in the early 00s, as he explained in a 2006 article called [Introducing BDD](http://dannorth.net/introducing-bdd/). It grew from a response to test-driven development (TDD), as a way to help programmers on new agile teams "get straight to the good stuff" of knowing how to approach testing and coding, and minimize misunderstandings. BDD has evolved into both analysis and automated testing at the acceptance level. [Liz Keogh](https://lizkeogh.com), another BDD pioneer, started writing and speaking about it extensively beginning in 2004.

## Early tools supporting BDD

In 2003, Daniel Terhorst-North started writing a replacement for JUnit called JBehave, using vocabulary based on "behaviour" rather than "test". Liz Keogh and Chris Matts also started contributing early on. Influenced by the idea of ubiquitous language introduced in Eric Evans' [Domain-Driven Design](https://domainlanguage.com/ddd/), and also focusing on business value, the "Given/When/Then" template was developed to capture a story's acceptance criteria in an executable form. It grew partly from the "As a..., I ..., So that..." template for writing user stories, created by [Rachel Davies](http://rachelcdavies.github.io/) at Connextra that had become a recognized standard.  

In 2005, the [RSpec](https://rspec.info/) project, which supported BDD in the Ruby language, was founded by [Dave Astels](http://daveastels.com/), [Steven Baker](https://stevenrbaker.com/), [Aslak Hellesøy](https://twitter.com/aslak_hellesoy) and [David Chelimsky](https://twitter.com/dchelimsky). 

## Origins of Cucumber

As he helped improve RSpec, Aslak had a lot of ideas for improvements in areas like error messages, step definition snippets, and result reporting. RSpec was designed for programmers, whereas the RSpec Story Runner was for the whole team, including non-coding stakeholders. 

He started a new project, intending to make a better version of Story Runner. He initially called it _Stories_, but asked his then-fiancée for a catchier name. She thought of _Cucumber_, and it stuck.



================================================
FILE: docs/bdd/index.md
================================================
# Behaviour-Driven Development

Behaviour-Driven Development (BDD) is the software development process that Cucumber was built to support.

There's much more to BDD than just using Cucumber.

## What is BDD?

BDD is a way for software teams to work that closes the gap between business people and technical people by:

* Encouraging collaboration across roles to build shared understanding of the problem to be solved
* Working in rapid, small iterations to increase feedback and the flow of value
* Producing system documentation that is automatically checked against the system's behaviour

We do this by focusing collaborative work around concrete, real-world examples that illustrate how we want the system to behave. We use those examples to guide us from concept through to implementation, in a process of continuous collaboration.

### BDD and agile

We assume that your team are using some kind of agile methodology already, planning work in small increments of value like [User Stories]. BDD does not replace your existing agile process, it enhances it.

Think of BDD as a set of plugins for your existing process that will make your team more able to deliver on the promises of agile: timely, reliable releases of working software that meets your organisation’s evolving needs, requiring some maintenance effort and discipline.

### Rapid iterations

We assume you would like to be able to respond quickly to feedback from your users, and do only the minimal work necessary to meet those needs.

BDD encourages working in rapid iterations, continuously breaking down your user's problems into small pieces that can flow through your development process as quickly as possible.

## Three practices

Essentially, day-to-day BDD activity is a three-step, iterative process:

1. First, take a small upcoming change to the system -- a [User Story] -- and talk about concrete examples of the new functionality to explore, discover and agree on the details of what's expected to be done.
1. Next, document those examples in a way that can be automated, and check for agreement.
1. Finally, implement the behaviour described by each documented example, starting with an automated test to guide the development of the code.

The idea is to make each change small and iterate rapidly, moving back up a level each time you need more information. Each time you automate and implement a new example, you've added something valuable to your system, and you're ready to respond to feedback.

We call these practices _Discovery_, _Formulation_, and _Automation_.

<figure>
  <img alt="Diagram of how the practices fit together" src="/img/docs/bdd-practices-diagram.png"/>
  <figcaption>Discovery, Formulation and Automation</figcaption>
</figure> 

Over time, the documented examples become an asset that enables your team to continue confidently and rapidly making changes to the system. The code reflects the documentation, and the documentation reflects the team's shared understanding of the problem domain. This shared understanding is constantly evolving.

There's lots to learn about each of these practices. We'll summarise each of them below.

### Discovery: What it _could_ do

> The hardest single part of building a software system is deciding precisely what to build.
>
> -- <cite>Fred Brooks, The mythical man-month</cite>

Although documentation and automated tests are produced by a BDD team, you can think of them as nice side-effects. The real goal is valuable, working software, and the fastest way to get there is through conversations between the people who are involved in imagining and delivering that software.

BDD helps teams to have the right conversations at the right time so you minimise the amount of time spent in meetings and maximising the amount of valuable code you produce.

We use structured conversations, called [discovery workshops], that focus around real-world examples of the system from the users' perspective. These conversations grow our team's shared understanding of the needs of our users, of the rules that govern how the system should function, and of the scope of what needs to be done.

It may also reveal gaps in our understanding, where we need more information before we know what to do.

The scrutiny of a discovery session often reveals low-priority functionality that can be deferred from the scope of a user story, helping the team to work in smaller increments, improving their flow.

If you're new to BDD, discovery is the right place to start. You won't get much joy from the other two practices until you've mastered discovery.

### Formulation: What it _should_ do

As soon as we have identified at least one valuable example from our discovery sessions, we can now formulate each example as structured documentation. This gives us a quick way to confirm that we really do have a shared understanding of what to build.

In contrast to traditional documentation, we use [a medium that can be read by both humans and computers](../gherkin), so that:

* We can get feedback from the whole team about our shared vision of what we're building.
* We'll be able to automate these examples to guide our development of the implementation.

By writing this executable specification collaboratively, we establish a shared language for talking about the system. This helps us to use problem-domain terminology all the way down into the code.

### Automation: What it _actually does_

Now that we have our executable specification, we can use it to guide our development of the implementation.

Taking one example at a time, we automate it by connecting it to the system as a test. The test fails because we have not implemented the behaviour it describes yet. Now we develop the implementation code, using [lower-level examples of the behaviour of internal system components](https://www.geepawhill.org/2020/06/12/microtest-tdd-more-definition/) to guide us as required.

The automated examples work like guide-rails, helping us to keep our development work on track.

When we need to come back and maintain the system later, the automated examples will help us to understand what the system is currently doing, and to make changes safely without unintentionally breaking anything.

This rapid, repeatable feedback reduces the burden of manual regression testing, freeing people up to do more interesting work, like exploratory testing.

## Learn more

Read the topics below to dig deeper and learn more about BDD.

[discovery workshops]: /docs/bdd/discovery-workshop/
[User Story]: /docs/terms/user-story/
[User Stories]: /docs/terms/user-story/



================================================
FILE: docs/bdd/myths.md
================================================
---
sidebar_position: 5
---

# Myths about BDD

Let's bust some of the most common myths and misunderstandings about BDD.

## Myth: You can pick and choose the practices in any order

Here's [Liz Keogh's take](https://lizkeogh.com/2014/01/22/using-bdd-with-legacy-systems/) on this:

> having conversations is more important than capturing conversations is more important than automating conversations.

Unless you've already done effective discovery work, trying to formulate scenarios is a waste of time.

Similarly, you can't automate examples when you haven't done the work to figure out the most important examples to automate, or got your business stakeholder's feedback in how to word them.

## Myth: You can automate scenarios after the code is implemented

Many people use Cucumber to do test automation, to check for bugs after the code has already been implemented. That's a perfectly reasonable way to do test automation, but it's not BDD.

## Myth: Discovery doesn't need a conversation

We see plenty of teams who try to leave the work of identifying examples and turning them into formulated scenarios to a single individual on the team.

That's not BDD. Discovery work needs to be done _collaboratively_, bringing together representatives of the different specialists who all need to share understanding about what will be built.

## Myth: Using Cucumber means you're doing BDD

Just because you're using Cucumber, doesn't mean you're doing BDD. [There's much more to BDD than using Cucumber](/docs/bdd).



================================================
FILE: docs/bdd/who-does-what.md
================================================
---
sidebar_position: 6
---

# Who does what?

Who should be writing [Gherkin](/docs/gherkin/) documents, and who should write
[step definitions](/docs/cucumber/step-definitions)?

Product owners, business analysts, programmers and testers are often confused
about who should take on what responsibilities.

The answer depends on several factors, such as team structure, skills, culture,
process and more.

## The Three Amigos

*The Three Amigos* is a meeting that takes user stories and turns them into clean, thorough Gherkin scenarios. It involves three voices (at least):

- **The product owner** - This person is most concerned with the scope of the application. This involves translating user stories into a series of features. As the tester comes up with edge cases, the product owner is responsible for deciding what is within scope.
- **The tester** - This person will be generating lots of Scenarios, and lots of edge cases. How will the application break? What user stories have we not accounted for within these Features?
- **The developer** - This person will add many of the Steps to the Scenarios, and think of the details that go into each requirement. How will this application execute? What are some of the roadblocks or requirements behind the scenes?

These conversations can produce great tests, because each amigo sees
the product from a different perspective. For this reason it is *essential* that all of these roles have conversations to discover examples *together*.
[Example Mapping](/docs/bdd/example-mapping) and Event Storming are great collaborative analysis techniques for discovering examples.

Finally, there is no reason to limit these meetings to three people—or to hold only one such meeting at the beginning of the project. Continually refine your features and collaborate with everyone to best understand how to talk about, develop, and test your application.

## Writing Gherkin

To start with, when the language and style used in the scenarios
is still being established, it is recommended that the entire team collaborate on writing the Gherkin.
Later, it can be efficiently done by a pair: a developer (or someone who is responsible for the
automation) and a tester (or someone who is responsible for quality) as long as their
output is actively reviewed by the product owner (or business representative).

## Writing features

Cucumber tests are written in terms of “Features”. Each feature consists of one or more “Scenarios”.

Let’s start with an example Feature file:

```Gherkin
Feature: Explaining Cucumber
  In order to gain an understanding of the Cucumber testing system
  As a non-programmer
  I want to have an overview of Cucumber that is understandable by non-geeks

  Scenario: A worker seeks an overview of Cucumber
    Given I have a coworker who knows a lot about Cucumber
    When I ask my coworker to give an overview of how Cucumber works
    And I listen to their explanation
    Then I should have a basic understanding of Cucumber
```

Note that the scenarios do not go into the details of what the software
(or, in this case, the coworker) will do. It stays focused on the perspective of
the person the Feature is intended to serve (in this case, “a non-programmer”).

Every feature file has a single feature description at the top, but can have any
number of scenarios.

The `Feature` line names the feature. This should be a short label.

`In order to` presents the reason/justification for having the feature. In
general, this should match to one of the project’s core purposes or “business
values” such as:

- Protect revenue
- Increase revenue
- Manage cost
- Increase brand value
- Make the product remarkable
- Provide more value to your customers

`As a` describes the role of the people/users being served by the feature.

`I want` is a one sentence explanation of what the Feature is expected to do.

So, those three lines cover Why, Who, and What. Then, the document gets into the “How” with scenarios.

## Scenarios

You can have any number of scenarios for a feature.

If you have lots and lots of scenarios in one feature, you might
actually be describing *more* than one feature. When that happens, we recommend
splitting up the document into separate Feature definitions (The definition of
“lots and lots” here is subjective, and it's up to you to determine when it's time to split up a feature).

The first line provides a short description of what the scenario is intended to
cover. If you can’t describe your scenario in a single sentence (and not a
run-on sentence), then it’s probably trying to cover too much, and should be
split into multiple scenarios.

That is followed by some combination of “Steps”—lines that begin with the
keywords `Given`, `When`, and `Then` (typically in that order).

You can have many lines that use the same keyword (e.g., `Given there is something` followed by `Given I have another thing`). To increase the readability, you can substitute the keywords `And` or `But` (e.g., `Given there is something` followed by `And I have another thing`).

In general, any `Given` step line should describe only one thing. If you have
words like “and” in the middle of a step, you are probably describing more than
one step, and should split it into multiple steps.

For example:

```gherkin
When I fill in the "Name" field and the "Address" field
```

Becomes:

```gherkin
When I fill in the "Name" field
And I fill in the "Address" field
```

Cucumber features are best served by consistency. Don't say the same thing in
different ways — say it the same way every time.

For example:

```gherkin
Given I am logged in
```

and

```Gherkin
Given I have logged in to the site
```

have identical meaning, so it’s better to pick one and use the same line in
every Scenario where you need to be logged in.



================================================
FILE: docs/cucumber/_category_.json
================================================
{
  "position": 2,
  "label": "Cucumber"
}



================================================
FILE: docs/cucumber/api.mdx
================================================
---
sidebar_position: 2
description: "Using Cucumber: step definitions, hooks, tags"
---

# Cucumber reference

Cucumber can be used to implement automated tests based on scenarios described in your Gherkin feature files.

## Step arguments

In the example given in [step definitions](/docs/cucumber/step-definitions), Cucumber extracts the text `48` from the step, converts it to an `int`
and passes it as an argument to the <Term>stepdef-body</Term>.

The number of parameters in the <Term>stepdef-body</Term> has to match the number of <Term>expression-parameter</Term>s in the expression. (If there is a mismatch, Cucumber will throw an error).

## Data tables

Data tables from Gherkin can be accessed by using the `DataTable` object as the
last parameter in a step definition.

<Tabs>
    <Tab lang="java,kotlin,scala">

Depending on the table shape, the following collections can be also used as the
last parameter in a step definition. This conversion is done by Cucumber.

```java
List<List<String>> table
List<Map<String, String>> table
Map<String, String> table
Map<String, List<String>> table
Map<String, Map<String, String>> table
```

In addition to collections of `String`, `Integer`, `Float`, `BigInteger` and
`BigDecimal`. `Byte`, `Short`, `Long` and `Double` are also supported by
Cucumber. By registering a data table type it is also possible to support other
types. See [cucumber-jvm data-table-type](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-java#data-table-type)
for more.
  </Tab>
  <Tab lang="javascript"> 
    <!-- Intentionally left blank -->
  </Tab>
</Tabs>

The simplest way to pass a list of strings to a step definition is to use a data table:

```gherkin
Given the following animals:
| cow   |
| horse |
| sheep |
```
<Tabs>
  <Tab lang="java">

Declare the argument as a `List<String>` but don't define any capture group in the expression.

Annotated method style:

```java
@Given("the following animals:")
public void the_following_animals(List<String> animals) {
}
```

In this case, the `DataTable` is automatically flattened to a list of strings by Cucumber (using `DataTable.asList(String.class)`) before invoking the step definition.

    </Tab>
    <Tab lang="kotlin">

Declare the argument as a `List<String>` but don't define any capture group in the expression.

Annotated method style:

```kotlin
@Given("the following animals:")
fun the_following_animals(animals: List<String>) {
}
```

In this case, the `DataTable` is automatically flattened to a list of strings by Cucumber (using `DataTable.asList(String.class)`) before invoking the step definition.

    </Tab>
    <Tab lang="scala">

```scala
Given("the following animals:") { animals: java.util.List[String] =>
}
```

In this case, the `DataTable` is automatically flattened to a list of strings by Cucumber (using `DataTable.asList(String.class)`) before invoking the step definition.

For now, Cucumber Scala does not support using Scala collection types, see [this issue](https://github.com/cucumber/cucumber-jvm-scala/issues/50).

    </Tab>
    <Tab lang="javascript">
      For an example of using data tables in JavaScript, go [here](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/data_table_interface.md)
    </Tab>
</Tabs>


## Steps

A step is analogous to a method call or function invocation.

For example:

```gherkin
Given I have 93 cucumbers in my belly
```

In this step, you're "calling" the above step definition with one argument: the value `93`.

Steps are declared in your `*.feature` files.

### Matching steps

1. Cucumber matches a step against a step definition's `Regexp`
2. Cucumber gathers any <Term>expression-parameter</Term>s or variables
3. Cucumber passes them to the step definition's <Term>stepdef-body</Term> and executes it

Recall that step definitions start with a [preposition](https://www.merriam-webster.com/dictionary/given) or an [adverb](https://www.merriam-webster.com/dictionary/when) (**`Given`**, **`When`**, **`Then`**, **`And`**, **`But`**).

All step definitions are loaded (and defined) before Cucumber starts to execute the plain text in the feature file.

Once execution begins, for each step, Cucumber will look for a registered step definition with a matching `Regexp`. If it finds one, it will execute it, passing all <Term>expression-parameter</Term>s and variables from the Regexp as arguments to the <Term>stepdef-body</Term>.

The specific preposition/adverb used has **no** significance when Cucumber is registering or looking up step definitions.

Also, check out [multiline step arguments](/docs/gherkin/reference#step-arguments) for more info on how to pass entire tables or bigger strings to your step definitions.

### Step results

Each step can have one of the following results:

#### Success

When Cucumber finds a matching step definition it will execute it. If the block in the step definition doesn't raise an error, the step is marked as successful (green). Anything you `return` from a step definition has no significance whatsoever.

#### Undefined

When Cucumber can't find a matching step definition, the step gets marked as undefined (yellow), and all subsequent steps in the scenario are skipped.

#### Pending

When a step definition's <Term>stepdef-body</Term> invokes the `pending` <Term>stepdef-body</Term>, the step is marked as pending (yellow, as with `undefined` ones), indicating that you have work to do.

#### Failed Steps

When a step definition's <Term>stepdef-body</Term> is executed and raises an error, the step is marked as failed (red). What you return from a step definition has no significance whatsoever.

Returning `null`, `false` or some other falsy value in your programming language will **not** cause a step definition to fail.

#### Skipped

Steps that follow `undefined`, `pending`, or `failed` steps are never executed, even if there is a matching step definition. These steps are marked as skipped (cyan).

#### Ambiguous

Step definitions have to be unique for Cucumber to know what to execute. If more than one step definition is matched for the same step, Cucucmber can't resolve the ambiguity on its own. The behaviour varies a bit between implementations:

<Tabs>
    <Tab lang="java,kotlin,scala">Cucumber will throw an `AmbiguousStepDefinitionsException`.</Tab>
    <Tab lang="javascript">Cucumber will report an `ambiguous` result status.</Tab>
    <Tab lang="ruby">Cucumber will raise a `Cucumber::Ambiguous` error.</Tab>
</Tabs>

## Hooks

Hooks are blocks of code that can run at various points in the Cucumber execution cycle.
They are typically used for setup and teardown of the environment before and after each scenario.

Where a hook is defined has no impact on what scenarios or steps it is run for.
If you want more fine-grained control, you can use [conditional hooks](#conditional-hooks).

<Tabs>
    <Tab lang="java,kotlin">You can declare hooks in any class.</Tab>
    <Tab lang="scala">You can declare hooks in any class, trait or object.</Tab>
    <Tab lang="javascript">You can declare hooks in your `features/support/env.js` file, or any other file under the `features/support` directory (for example, in a file called `features/support/hooks.js`).</Tab>
    <Tab lang="ruby">You can declare hooks in your `features/support/env.rb` file, or any other file under the `features/support` directory (for example, in a file called `support/hooks.rb`).</Tab>
</Tabs>

### Scenario hooks

Scenario hooks run for every scenario.

#### Before

`Before` hooks run before the first step of each scenario.

<Tabs>
    <Tab lang="java">

Annotated method style:

```java
@Before
public void doSomethingBefore() {
}
```

Lambda style:

```java
Before(() -> {
});
```

    </Tab>
    <Tab lang="kotlin">

Lambda style:

```kotlin
Before { scenario: Scenario ->
    // doSomething
}
```

    </Tab>
    <Tab lang="scala">

```scala
Before { scenario: Scenario =>
    // doSomething
}
```

    </Tab>
    <Tab lang="javascript">

```javascript
// Import the Before function
const { Before } = require('@cucumber/cucumber')

Before(async function () {
})
```

:::warning[Avoid arrow functions]
Arrow functions (`() => {}`) bind `this` to the current context, which prevents sharing state between hooks and step definitions.
:::

    </Tab>
    <Tab lang="ruby">

```ruby
Before do
  # Do something before each scenario
end
```

    </Tab>
</Tabs>

:::tip[Think twice before you use `Before`]
Whatever happens in a `Before` hook is invisible to people who only read the features.
You should consider using a [background](/docs/gherkin/reference#background) as a more explicit
alternative, especially if the setup should be readable by non-technical people.
Only use a `Before` hook for low-level logic such as starting a browser or deleting
data from a database.
:::

<Tabs>
    <Tab lang="java">

You can specify an explicit order for hooks if you need to.

Annotated method style:

```java
@Before(order = 10)
public void doSomething(){
    // Do something before each scenario
}
```

Lambda style:

```java
Before(10, () -> {
    // Do something before each scenario
});
```

    </Tab>
    <Tab lang="kotlin">

You can specify an explicit order for hooks if you need to.

```kotlin
Before(10) { scenario: Scenario ->
    // Do something before each scenario
}
```
:::warning[Using Kotlin named objects or companion objects]

If `@BeforeAll`, `@AfterAll` etc. are used in Kotlin named objects or companion objects an `io.cucumber.java.InvalidMethodSignatureException`
will be thrown, as Kotlin will create a class `MyStepDefinitions$Companion` which has non-static methods. [Read more about it here](https://kotlinlang.org/docs/java-to-kotlin-interop.html#static-methods).

The `@JvmStatic` annotation does not prevent this behaviour of Kotlin; it adds the static methods to `MyStepDefinitionsMethod` only.

Consequently, Cucumber will detect the static methods in `MyStepDefinitions` class, as well as the non-static methods in `MyStepDefinitions$Companion` class and will complain about the second one.

As a solution to this problem, use [ package level functions](https://kotlinlang.org/docs/java-to-kotlin-interop.html#package-level-functions) - this is, without companion objects.
:::

```kotlin
package io.cucumber.example

import io.cucumber.java.AfterAll
import io.cucumber.java.BeforeAll

@BeforeAll
fun beforeAll() {
   println("before all")
}

@AfterAll
fun afterAll() {
   println("after all")
}
```

    </Tab>
    <Tab lang="scala">

You can specify an explicit order for hooks if you need to.

```scala
Before(10) { scenario: Scenario =>
    // Do something before each scenario
}
```

    </Tab>
    <Tab lang="javascript,ruby">`Before` hooks run in the **same order** in which they are declared.</Tab>
</Tabs>

#### After

`After` hooks run after the last step of each scenario, even when the step result is `failed`, `undefined`, `pending`, or `skipped`.

<Tabs>
    <Tab lang="java">

Annotated method style:

```java
@After
public void doSomethingAfter(Scenario scenario){
    // Do something after after scenario
}
```

Lambda style:

```java
After((Scenario scenario) -> {
});
```

    </Tab>
    <Tab lang="kotlin">

Lambda style:

```kotlin
After { scenario: Scenario ->
    // doSomething
}
```

    </Tab>
    <Tab lang="scala">

```scala
After { scenario: Scenario =>
    // doSomething
}
```

    </Tab>
    <Tab lang="javascript">

```javascript
After(async function (scenario) {
})
```

    </Tab>
    <Tab lang="ruby">

```ruby
After do |scenario|
end
```

Here is an example in which we exit at the first failure (which could be useful in some cases like [Continuous Integration](/docs/guides/continuous-integration), where fast feedback is important).

```ruby
After do |s|
  # Tell Cucumber to quit after this scenario is done - if it failed.
  Cucumber.wants_to_quit = true if s.failed?
end
```

    </Tab>
</Tabs>

The `scenario` parameter is optional. If you use it, you can inspect the status of the scenario.

For example, you can take a screenshot for failed scenarios and embed them in Cucumber's report(s); see the [browser automation page](/docs/guides/browser-automation/#screenshot-on-failure) for an example on how to do so.

#### Around

:::info[Ruby only]
This section is only applicable to the Ruby implementation of Cucumber.
:::

`Around` hooks will run "around" a scenario. This can be used to wrap the execution of a scenario in a block. The `Around` hook receives a `Scenario` object and a block (`Proc`) object. The scenario will be executed when you invoke `block.call`.

The following example will cause scenarios tagged with `@fast` to fail if the execution takes longer than 0.5 seconds:

```ruby
Around('@fast') do |scenario, block|
  Timeout.timeout(0.5) do
    block.call
  end
end
```

### Step hooks

Step hooks are invoked before and after a step. The hooks have "invoke around" semantics, meaning that if a `BeforeStep`
hook is executed the `AfterStep` hooks will also be executed regardless of the result of the step. If a step did not
pass, the following step and its hooks will be skipped.

#### BeforeStep

<Tabs>
    <Tab lang="java">

Annotated method style:

```java
@BeforeStep
public void doSomethingBeforeStep(Scenario scenario){
}
```

Lambda style:

```java
BeforeStep((Scenario scenario) -> {

});
```

    </Tab>
    <Tab lang="kotlin">

Lambda style:

```kotlin
BeforeStep { scenario: Scenario ->
    // doSomething
}
```

    </Tab>
    <Tab lang="scala">

```scala
BeforeStep { scenario: Scenario =>
    // doSomething
}
```

    </Tab>
    <Tab lang="javascript">

```javascript
BeforeStep(async function({pickle, pickleStep, gherkinDocument, testCaseStartedId, testStepId}) {
    // doSomething
})

BeforeStep({tags: "@foo"}, async function() {
    // apply this hook to only specific scenarios
})
```

    </Tab>
    <Tab lang="ruby">Cucumber-Ruby does not support `BeforeStep` hooks.</Tab>
</Tabs>

#### AfterStep

<Tabs>
    <Tab lang="java">

Annotated method style:

```java
@AfterStep
public void doSomethingAfterStep(Scenario scenario){
}
```

Lambda style:

```java
AfterStep((Scenario scenario) -> {
});
```

    </Tab>
    <Tab lang="kotlin">

Lambda style:

```kotlin
AfterStep { scenario: Scenario ->
    // doSomething
}
```

    </Tab>
    <Tab lang="scala">

```scala
AfterStep { scenario: Scenario =>
    // doSomething
}
```

    </Tab>
    <Tab lang="javascript">

```javascript
AfterStep(async function({pickle, pickleStep, gherkinDocument, result, testCaseStartedId, testStepId}) {
    // doSomething
})
```

    </Tab>
    <Tab lang="ruby">

```ruby
AfterStep do |scenario|
end
```

    </Tab>
</Tabs>

### Conditional hooks

Hooks can be conditionally selected for execution based on the tags of the scenario. To run a particular hook only for certain scenarios, you can associate a hook with a [tag expression](#tag-expressions).

<Tabs>
    <Tab lang="java">

Annotated method style:

```java
@After("@browser and not @headless")
public void doSomethingAfter(Scenario scenario){
}
```

Lambda style:

```java
After("@browser and not @headless", (Scenario scenario) -> {
});
```

    </Tab>
    <Tab lang="kotlin">

Lambda style:

```kotlin
After (arrayOf("@browser and not @headless")) { scenario: Scenario ->
    driver.quit()
}
```

    </Tab>
    <Tab lang="scala">

```scala
After("@browser and not @headless") { scenario: Scenario =>

}
```

    </Tab>
    <Tab lang="javascript">

```javascript
Before({tags: '@browser and not @headless'}, async function () {
})
```

    </Tab>
    <Tab lang="ruby">

```ruby
Before('@browser and not @headless') do
end
```

    </Tab>
</Tabs>

See more documentation on [tags](#tags).

### Global hooks

Global hooks will run once before any scenario is run or after all scenarios have been run.

#### BeforeAll

Each `BeforeAll` hook will run before any scenario is run.

<Tabs>
    <Tab lang="java">

Annotated method style:

```java
@BeforeAll
public static void beforeAll() {
    // Runs before all scenarios
}
```

    </Tab>
    <Tab lang="kotlin">

```kotlin
BeforeAll {
    // doSomething
}
```

    </Tab>
    <Tab lang="scala">

```scala
BeforeAll {
    // doSomething
}
```

    </Tab>
    <Tab lang="javascript">

```javascript
const { BeforeAll } = require('@cucumber/cucumber');

BeforeAll(async function () {
  // perform some shared setup
});
```

    </Tab>
    <Tab lang="ruby">

Put the code at the top-level in your `env.rb` file (or any other file under `features/support` directory).

```ruby
BeforeAll do
  # Do something before any scenario is executed
end
```

    </Tab>
</Tabs>

#### AfterAll

Each `AfterAll` hook will run after all scenarios have been executed.

<Tabs>
    <Tab lang="java">

Annotated method style:

```java
@AfterAll
public static void afterAll() {
    // Runs after all scenarios
}
```

    </Tab>
    <Tab lang="kotlin">

```kotlin
AfterAll {
    // doSomething
}
```

    </Tab>
    <Tab lang="scala">

```scala
AfterAll {
    // doSomething
}
```

    </Tab>
    <Tab lang="javascript">

```javascript
const { AfterAll } = require('@cucumber/cucumber');

AfterAll(async function () {
  // perform some shared setup
});
```

    </Tab>
    <Tab lang="ruby">

```ruby
AfterAll do
  # Do something after all scenarios have been executed
end
```

    </Tab>
</Tabs>

### InstallPlugin

:::info[Ruby only]
This section is only applicable to the Ruby implementation of Cucumber.
:::

You may provide an `InstallPlugin` hook that will be run after Cucumber has been configured. The block you provide will be passed on to Cucumber's configuration (an instance of `Cucumber::Cli::Configuration`), and a wrapper to some cucumber internals as a registry.

```ruby
InstallPlugin do |config, registry|
  puts "Features dwell in #{config.feature_dirs}"
end
```

This hook will run _only once_: after support has been loaded, and before any features are loaded.

You can use this hook to extend Cucumber. For example, you could affect how features are loaded, or register custom formatters programmatically. [cucumber-wire](https://github.com/cucumber/cucumber-ruby-wire) is a good example
of how to use InstallPlugin and what a Cucumber plugin can do.

## Tags

Tags are a great way to organise your features and scenarios.

They can be used for two purposes:

* [Running a subset of scenarios](#running-a-subset-of-scenarios)
* [Restricting hooks to a subset of scenarios](#conditional-hooks)

Consider the following example:

```gherkin
@billing
Feature: Verify billing

  @important
  Scenario: Missing product description
    Given hello

  Scenario: Several products
    Given hello
```

A feature or scenario can have as many tags as you like. Separate them with spaces:

```gherkin
@billing @bicker @annoy
Feature: Verify billing
```

Tags can be placed above the following Gherkin elements:

* `Feature`
* `Rule`
* `Scenario`
* `Scenario Outline`
* `Examples`

In `Scenario Outline`, you can use tags on different sets of examples like below:

```gherkin
Scenario Outline: Steps will run conditionally if tagged
  Given user is logged in
  When user clicks <link>
  Then user will be logged out

  @mobile
  Examples:
    | link                  |
    | logout link on mobile |

  @desktop
  Examples:
    | link                   |
    | logout link on desktop |
```

It is *not* possible to place tags above `Background` or steps (`Given`, `When`, `Then`, `And` and `But`).

### Tag inheritance

Tags are inherited by child elements. So, tags that are placed above a `Feature` will be inherited by `Rule`, `Scenario`, `Scenario Outline`, or `Examples`. And similarly tags that are placed above a `Scenario Outline` will be inherited by `Examples`.

### Running a subset of scenarios

You can tell Cucumber to only run scenarios with a particular tag:

<Tabs>
    <Tab lang="java,kotlin,scala">

For JUnit 5 see the [cucumber-junit-platform-engine documentation](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine#tags)

For JUnit 4 and TestNG using a JVM system property:

```shell
mvn test -Dcucumber.filter.tags="@smoke and @fast"
```

Or an environment variable:

```shell
# Linux / OS X:
CUCUMBER_FILTER_TAGS="@smoke and @fast" mvn test

# Windows:
set CUCUMBER_FILTER_TAGS="@smoke and @fast"
mvn test
```

Or annotating your JUnit 4/TestNG  runner class:

```java
@CucumberOptions(tags = "@smoke and @fast")
```

    </Tab>
    <Tab lang="javascript">

```shell
# You can omit the quotes if the expression is a single tag
./node_modules/.bin/cucumber.js --tags "@smoke and @fast"
```

    </Tab>
    <Tab lang="ruby">

```shell
# You can omit the quotes if the expression is a single tag
cucumber --tags "@smoke and @fast"
```

    </Tab>
</Tabs>

### Ignoring a subset of scenarios

You can tell Cucumber to ignore scenarios with a particular tag:

<Tabs>
    <Tab lang="java,kotlin,scala">

By annotating your JUnit 4/TestNG  runner class:

```java
@CucumberOptions(tags = "not @smoke")
```

    </Tab>
    <Tab lang="javascript">

```shell
# You can omit the quotes if the expression is a single tag
./node_modules/.bin/cucumber.js --tags "not @smoke"
```

    </Tab>
    <Tab lang="ruby">

```shell
# You can omit the quotes if the expression is a single tag
cucumber --tags "not @smoke"
```

    </Tab>
</Tabs>

:::tip[Filtering by line]
Another way to run a subset of scenarios is to use the `file.feature:line` pattern or the `--scenario` option.
:::

### Tag expressions

A tag expression is an *infix boolean expression*. Below are some examples:

| Expression           |                                                       Description |
|----------------------|------------------------------------------------------------------:|
| `@fast`              |                                     Scenarios tagged with `@fast` |
| `@wip and not @slow` | Scenarios tagged with `@wip` that aren't also tagged with `@slow` |
| `@smoke and @fast`   |                   Scenarios tagged with both `@smoke` and `@fast` |
| `@gui or @database`  |                Scenarios tagged with either `@gui` or `@database` |

For even more advanced tag expressions you can use parenthesis for clarity, or
to change operator precedence:

```
(@smoke or @ui) and (not @slow)
```

### Using tags for documentation

Your imagination is the only limitation when it comes to using tags for documentation.

#### Link to other documents

Tags can refer to IDs in external systems such as requirement management tools, issue trackers or
test management tools:

```gherkin
@BJ-x98.77 @BJ-z12.33
Feature: Convert transaction
```

You can use a custom Cucumber reporting plugin that will turn tags into links pointing to
documents in your external tool.

#### Development process

Another creative way to use tags is to keep track of where in the development process a certain feature is:

```gherkin
@qa_ready
Feature: Index projects
```

### `@wip`

:::info[Rails only]
This section is only applicable to the Rails implementation of Cucumber.
:::

As distributed, Cucumber-Rails builds a Rake task that recognizes the `@wip` tag.
However, any string may be used as a tag and any scenario or entire feature can have multiple tags associated with it.

The default profile contained in the distributed `config/cucumber.yml` contains these lines:

```yaml
<%
.  .  .
std_opts = "--format #{ENV['CUCUMBER_FORMAT'] || 'progress'} --strict --tags ~@wip"
%>
default: <%= std_opts %> features
.  .  .
```

Note the trailing option `--tags ~@wip`.  Cucumber provides for negating tags by prefacing the `--tags` argument with a tilde character (**`~`**).
This tells Cucumber to not process features and scenarios with this tag. If you do not specify a different profile (`cucumber -p profilename`), then the default profile will be used.
If the default profile is used, then the `--tags ~@wip` will cause Cucumber to skip any scenario with this tag. This will override the `--tags=@authen` option passed in the command line, and so you will see this:

```shell
cucumber --tags=@authentication
Using the default profile...

0 scenarios
0 steps
0m0.000s
```

Since version 0.6.0, one can no longer overcome this default setting by adding the `--tags=@wip` to the Cucumber argument
list on the command line, because now all `--tags` options are combined with "and" logic. Thus, the combination of `--tags @wip` **and** `--tags ~@wip` fails everywhere.

You either must create a special profile in `config/cucumber.yml` to deal with this, or alter the default profile to suit your needs.

The `@wip` tags are a special case. If any scenario tagged as `@wip` passes all of its steps without error, and the
`--wip` option is also passed, Cucumber reports the run as failing (because Scenarios that are marked as a work in progress are not *supposed* to pass!)

Note as well that the `--strict` and `--wip` options are mutually exclusive.

The number of occurrences of a particular tag in your features may be controlled by appending a colon followed by a
number to the end of the tag name passed to the `--tags` option, like so:

```shell
cucumber --tags=@wip:3 features/log\*
```

The existence of more than the specified number of occurrences of that tag in all the features that are exercised during
a particular Cucumber run will produce a warning message. If the `--strict` option is passed as well, as is the case with
the default profile, then instead of a warning the run will fail.

Limiting the number of occurrences is commonly used in conjunction with the `@wip` tag to restrict the number of
unspecified scenarios to manageable levels. Those following [Kanban](https://en.wikipedia.org/wiki/kanban) or
[Lean Software Development](https://en.wikipedia.org/wiki/Lean_software_development) based methodologies will find this useful.

## Running Cucumber

<Tabs>
    <Tab lang="java,kotlin,scala">Cucumber is a Java library with extensions for different tools and platforms. It is launched by running JUnit 4, JUnit 5, your build tool, your IDE or the CLI.</Tab>
    <Tab lang="javascript">Cucumber is a command line tool. It is launched by running `cucumber-js` from the command line, or a build script.</Tab>
    <Tab lang="ruby">Cucumber is a command line tool. It is launched by running `cucumber` from the command line, or a build script.</Tab>
</Tabs>

It is possible to [configure](/docs/cucumber/configuration) how Cucumber should run features.

### From the command line

<Tabs>
    <Tab lang="java,kotlin,scala">

The *Command-Line Interface Runner (CLI Runner)* is an executable Java class that can be run from the command-line.

```
java io.cucumber.core.cli.Main
```
Note that you will need to add the `cucumber-core` jar and all of its transitive dependencies to your classpath, in addition to the location of your compiled .class files. You can find these jars in [Maven Central](https://mvnrepository.com/repos/central).

You will also need to provide the CLI with your step definitions via the `--glue` option followed by its package name, and the filepath of your feature file(s).

For example:
```shell
java -cp "path/to/each/jar:path/to/compiled/.class/files" io.cucumber.core.cli.Main /path/to/your/feature/files --glue hellocucumber --glue anotherpackage
```
Alternatively if you are using a Maven project, you can run the CLI using the [Exec Maven](https://www.mojohaus.org/exec-maven-plugin/) plugin:

```shell
mvn exec:java                                  \
    -Dexec.classpathScope=test                 \
    -Dexec.mainClass=io.cucumber.core.cli.Main \
    -Dexec.args="/path/to/your/feature/files --glue hellocucumber --glue anotherpackage"
```

    </Tab>
    <Tab lang="javascript">

The most common option is to run Cucumber from the command line. By default, Cucumber will treat anything ending in`.js` under the root directory as a step definition file.
Thus, a step contained in `features/models/entities/step-definitions/anything.js` can be used in a feature file, provided that:

- Cucumber is invoked on a root directory common to both (`./features`, in this example); OR
- Explicitly required on the command line

Cucumber.js includes an executable file to run the features. After installing Cucumber in a project, you can run it with:

``` shell
./node_modules/.bin/cucumber.js
```

:::warning[Global installs]
Cucumber does not work when installed globally because Cucumber needs to be imported/required in support files and globally installed modules cannot be imported/required.
:::


    </Tab>
    <Tab lang="ruby">

The most common option is to run Cucumber from the command line. By default, Cucumber will treat anything ending in `.rb` under the root library directory as a step definition file.
Thus, a step contained in `features/models/entities/step_definitions/anything.rb` can be used in a feature file contained in `features/views/entity_new`, provided that:

- Cucumber is invoked on a root directory common to both (`./features`, in this example); OR
- Explicitly required on the command line

The following command will run the `authenticate_user` feature. Any feature in a subdirectory of `features/` directory must `require` features.

```shell
cucumber --require features features/authentication/authenticate_user.feature
```

Note that if the `--require` option is passed, then **ONLY** that directory tree will be searched for step definition matches.
You may specify the `--require` option multiple times if you need to include step definitions from directories that do not share a convenient root.

Otherwise, to run all features:

```
cucumber
```

    </Tab>
</Tabs>

You can also run features using a [build tool](/docs/tools#build-tools) or an [IDE](/docs/tools#ides).

### With test runners

#### JUnit 5 (for JVM)

See the [cucumber-junit-platform-engine documentation](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine#configuration-options) for more information.

#### JUnit 4 (for JVM)

To use JUnit to execute Cucumber scenarios add the `cucumber-junit` dependency to your pom.

```xml
<dependencies>
  [...]
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-junit</artifactId>
        <version>${cucumber.version}</version>
        <scope>test</scope>
    </dependency>
  [...]
</dependencies>
```
Note that `cucumber-junit` is based on JUnit 4. If you're using JUnit 5, use the [cucumber-junit-platform-engine](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine) or include `junit-vintage-engine` dependency, as well. For more information, please refer to [JUnit 5 documentation](https://junit.org/junit5/docs/current/user-guide/#migrating-from-junit4-running)

Create an empty class that uses the Cucumber JUnit runner:

<Tabs>
    <Tab lang="java">

```java
package com.example;

import io.cucumber.junit.Cucumber;
import io.cucumber.junit.CucumberOptions;
import org.junit.runner.RunWith;

@RunWith(Cucumber.class)
@CucumberOptions()
public class RunCucumberTest {
}
```

    </Tab>
    <Tab lang="kotlin">

```kotlin
package com.example

import io.cucumber.junit.Cucumber
import io.cucumber.junit.CucumberOptions
import org.junit.runner.RunWith

@RunWith(Cucumber::class)
@CucumberOptions()
class RunCucumberTest {
}
```

    </Tab>
    <Tab lang="scala">

```scala
package com.example

import io.cucumber.junit.Cucumber
import io.cucumber.junit.CucumberOptions
import org.junit.runner.RunWith

@RunWith(classOf[Cucumber])
@CucumberOptions()
class RunCucumberTest {
}
```

    </Tab>
</Tabs>

This will execute all scenarios in same package as the runner, by default glue code is also assumed to be in the same
package.

The `@CucumberOptions` annotation can be used to provide[additional configuration](#list-configuration-options) to the runner.

##### Using plugins

For example if you want to tell Cucumber to use the two formatter plugins `pretty` and `html`, you can specify it like this:

```java
@CucumberOptions(plugin = {"pretty", "html:target/cucumber.html"})
```

Or if you want to tell Cucumber to print code snippets for missing step definitions use the `summary` plugin, you can specify it like this:

```java
@CucumberOptions(plugin = {"pretty", "summary"}, snippets = SnippetType.CAMELCASE)
```

The default option for `snippets` is `UNDERSCORE`. This settings can be used to specify the way code snippets will be created by Cucumber.

##### Performing a dry-run

For example if you want to check whether all feature file steps have corresponding step definitions, you can specify it like this:

```java
@CucumberOptions(dryRun=true)
```

The default option for `dryRun` is `false`.

##### Formatting console output

For example if you want console output from Cucumber in a readable format, you can specify it like this:


```java
@CucumberOptions(monochrome=true)
```

The default option for `monochrome` is `false`.

##### Select scenarios using tags

For example if you want to tell Cucumber to only run the scenarios specified with specific tags, you can specify it like this:

```java
@CucumberOptions(tags = "@foo and not @bar")
```

##### Specify an object factory

For example if you are using Cucumber with a DI framework and want to use a custom object factory, you can specify it like this:

```java
@CucumberOptions(objectFactory = FooFactory.class)
```

The default option for `objectFactory` is to use the default object factory.
Additional information about using custom object factories can be found [here](/docs/cucumber/state/#the-cucumber-object-factory)

There are additional options available in the `@CucumberOptions` annotation.

Usually, the test class will be empty. You can, however, specify several JUnit rules.

:::warning[JUnit annotations]
Cucumber supports JUnits `@ClassRule`, `@BeforeClass` and `@AfterClass` annotations. These will be executed before and after all scenarios. Using them is not recommended, as it limits the portability between different runners;
they may not execute correctly when using the command line, [IntelliJ IDEA](https://www.jetbrains.com/help/idea/cucumber.html) or
[Cucumber-Eclipse](https://github.com/cucumber/cucumber-eclipse) . Instead, it is recommended to use Cucumber's `Before` and `After` [hooks](#hooks).
:::

The Cucumber runner acts like a suite of a JUnit tests. As such other JUnit features such as Categories, Custom JUnit
Listeners and Reporters can all be expected to work.

For more information on JUnit, see the [JUnit website](https://www.junit.org)

### Options

Cucumber provides several options that can be passed via the command-line or other mechanisms.

<Tabs>
    <Tab lang="java,kotlin,scala">

Pass the `--help` option to print out all the available configuration options:

```shell
java io.cucumber.core.cli.Main --help
```

Cucumber will in order of precedence parse properties from system properties,
environment variables and the `cucumber.properties` file.

Note that options provided by `@CucumberOptions` take precedence over the
properties file and CLI arguments take precedence over all.

Note that the `cucumber-junit-platform-engine` is provided with properties
by the Junit Platform rather than Cucumber. See
[junit-platform-engine Configuration Options](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine#configuration-options)
for more information.

For example, if you are using Maven and want to run a subset of scenarios tagged
with `@smoke`:

```shell
mvn test -Dcucumber.filter.tags="@smoke"
```

Supported properties are:
```
cucumber.ansi-colors.disabled=  # true or false. default: false
cucumber.execution.dry-run=     # true or false. default: false
cucumber.execution.limit=       # number of scenarios to execute (CLI only).
cucumber.execution.order=       # lexical, reverse, random or random:[seed] (CLI only). default: lexical
cucumber.execution.wip=         # true or false. default: false.
cucumber.features=              # comma separated paths to feature files. example: path/to/example.feature, path/to/other.feature
cucumber.filter.name=           # regex. example: .*Hello.*
cucumber.filter.tags=           # tag expression. example: @smoke and not @slow
cucumber.glue=                  # comma separated package names. example: com.example.glue
cucumber.plugin=                # comma separated plugin strings. example: pretty, json:path/to/report.json
cucumber.object-factory=        # object factory class name. example: com.example.MyObjectFactory
cucumber.snippet-type=          # underscore or camelcase. default: underscore
```

Note that the filter options `cucumber.filter.name` and `cucumber.filter.tags` are combined using an `and` operation. In other words, both expressions need to match.

    </Tab>
    <Tab lang="javascript">

Use the `cucumber-js --help` command to see which arguments can be passed to the executable file.

For more information on how to configure options, take a look at the [docs on GitHub](https://github.com/cucumber/cucumber-js/blob/main/docs/configuration.md)

    </Tab>
    <Tab lang="ruby">

Assuming you've installed Cucumber as a gem, run this at a command prompt to see the options for running features:

```shell
cucumber --help
```

You can also define common command-line options in a [`cucumber.yml`](/docs/cucumber/configuration) file.

    </Tab>
</Tabs>


================================================
FILE: docs/cucumber/checking-assertions.md
================================================
---
sidebar_position: 2
description: "How to determine success or failure"
---

# Checking assertions

Your `Then` steps should make assertions comparing expected results to actual results from your application.

Cucumber does not come with an assertion library. Instead, use the assertion methods from an appropriate testing tool.

## Java

### JUnit 5

When using the [cucumber-junit-platform-engine](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine)
you are free to use any assertion library of your choice. For example:

 * [AssertJ](https://assertj.github.io/doc/)
 * [Hamcrest](http://hamcrest.org/JavaHamcrest/)
 * [JUnit Jupiter](https://junit.org/junit5/docs/current/user-guide/#writing-tests-assertions)

### JUnit 4

When using JUnit 4 to run Cucumber we recommend using [JUnit 4](https://junit.org/junit4/)'s `assert*` methods.

If you are using Maven, add the following to your `pom.xml`:

```xml
<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>{{% version "junit" %}}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

:::note[Cucumber version]
Make sure to use the same version for `cucumber-junit` that you are using for `cucumber-java` or `cucumber-java8`.
:::

Below is an example using `assertEquals`:

```java
import static org.junit.Assert.*;

public class Example {

    @Then("the result should be {int}")
    public void the_result_should_be(int expectedResult) {
        assertEquals(expectedResult, result);
    }
}
```

For more examples of how to use JUnit assertions, see the [JUnit Wiki](https://github.com/junit-team/junit4/wiki/Assertions).

### TestNG

You can also use [TestNG](https://testng.org/doc/)'s assertions'.

If you are using Maven, add the following to your `pom.xml`:

```xml
<dependency>
    <groupId>org.testng</groupId>
    <artifactId>testng</artifactId>
    <version>{{% version "testng" %}}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-testng</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

TestNG assertions are similar JUnit.
For a more extensive example of how to use TestNG with Cucumber, see the [calculator-java-testng example](https://github.com/cucumber/cucumber-jvm/tree/main/examples/calculator-java-testng).

For more information on how to use TestNG assertions, see the [TestNG documentation](https://testng.org/doc/documentation-main.html#success-failure).

## JavaScript

We recommend using Node.js' built-in [assert](https://nodejs.org/dist/latest-v8.x/docs/api/assert.html) module.

```javascript
const assert = require('assert')

Then('the result should be {word}', function (expected) {
  // this.actual is typically set in a previous step
  assert.equal(this.actual, expected)
})
```

You can use any other assertion library if you wish. Here is an example using [Chai](https://www.chaijs.com/):

```javascript
const { expect } = require('chai')

Then('the result should be {word}', function (expected) {
  expect(this.actual).to.eql(expected)
})
```

## Ruby

### RSpec

We recommend using [RSpec](https://rspec.info/) for assertions.

Add the `rspec-expectations` gem to your `Gemfile`.
Cucumber will automatically load RSpec's matchers and expectation methods to be
available in your step definitions. For example:

```ruby
Given /^a nice new bike$/ do
  expect(bike).to be_shiny
end
```

If you want to configure RSpec, you'll need to also add the `rspec-core` gem
to your `Gemfile`. Then, you can add to your `features/support/env.rb`
configuration, such as:

```ruby
RSpec.configure do |config|
  config.expect_with :rspec do |c|
    c.syntax = :expect
  end
end
```

Realize that tests/assertions/expectations either “pass” or “fail” (raise an error), and that “fail” is **not** the same as `false`.
Anything besides “fail” is a pass.

When, in RSpec, `something.should_be 0` and it is not, then what is returned is an error exception, not a Boolean value.
In Cucumber, one writes `fail if false` and not only `false`.
This is because `false` might be the expected successful outcome of a test, and thus not an error.

Sometimes however, we wish to test how our application handles an exception and therefore do not want that exception
to be handled by Cucumber. For that situation use the `@allow-rescue` [tag](/docs/cucumber/api/#tags).

### Test::Unit

If you prefer to use `Test::Unit`'s `assert` methods you can mix them into
your `World`.

```ruby
require 'test/unit/assertions'

World(Test::Unit::Assertions)
```



================================================
FILE: docs/cucumber/configuration.mdx
================================================
---
sidebar_position: 3
description: "How to configure Cucumber"
---

# Configuration

## Parameter types

Parameter types let you convert parameters from [Cucumber expressions](./cucumber-expressions.md) to objects.

<Tabs>
    <Tab lang="java">

Data table and doc string types let you convert data tables and doc strings to objects. Like step definitions, type definitions are part of the glue. When placed on the glue path Cucumber will detect them automatically.

For example, the following class registers a custom "Author" data table type:

```java
package com.example;

import io.cucumber.java.DataTableType;
import io.cucumber.java.en.Given;

import java.util.List;
import java.util.Map;

public class StepDefinitions {

    @DataTableType
    public Author authorEntry(Map<String, String> entry) {
        return new Author(
            entry.get("firstName"),
            entry.get("lastName"),
            entry.get("famousBook"));
    }

    @Given("These are my favorite authors")
    public void these_are_my_favourite_authors(List<Author> authors) {
        // step implementation
    }
}
```

This class registers a custom "Book" type from an expression:

```java
package com.example;

import io.cucumber.java.ParameterType;
import io.cucumber.java.en.Given;

public class StepDefinitions {

    @ParameterType(".*")
    public Book book(String bookName) {
    	return new Book(bookName);
    }

    @Given("{book} is my favorite book")
    public void this_is_my_favorite_book(Book book) {
        // step implementation
    }
}
```

This class registers a custom type for a doc string:

```java
package com.example;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.cucumber.java.DocStringType;
import io.cucumber.java.en.Given;

public class StepsDefinitions {

    private static ObjectMapper objectMapper = new ObjectMapper();

    @DocStringType
    public JsonNode json(String docString) throws JsonProcessingException {
        return objectMapper.readValue(docString, JsonNode.class);
    }

    @Given("Books are defined by json")
    public void books_are_defined_by_json(JsonNode books) {
        // step implementation
    }
}
```

For lambda-defined step definitions, there are `DataTableType`, `ParameterType` and `DocStringType` functions:

```java
package com.example;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import io.cucumber.java8.En;

import java.util.Map;

public class LambdaStepDefinitions implements En {

    private static ObjectMapper objectMapper = new ObjectMapper();

    public LambdaStepDefinitions() {

        DataTableType((Map<String, String> entry) -> new Author(
            entry.get("firstName"),
            entry.get("lastName"),
            entry.get("famousBook")
        ));

        ParameterType("book", ".*", (String bookName) -> new Book(bookName));

        DocStringType("json", (String docString) ->
            objectMapper.readValue(docString, JsonNode.class));
    }
}
```

Using the `@DefaultParameterTransformer`, `@DefaultDataTableEntryTransformer` and `@DefaultDataTableCellTransformer` annotations, it is also possible to plug in an object mapper. The object mapper (Jackson in this example) will handle the conversion of anonymous parameter types and data table entries:

```java
package com.example;

import com.fasterxml.jackson.databind.ObjectMapper;
import io.cucumber.java.DefaultDataTableCellTransformer;
import io.cucumber.java.DefaultDataTableEntryTransformer;
import io.cucumber.java.DefaultParameterTransformer;

import java.lang.reflect.Type;

public class StepDefinitions {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @DefaultParameterTransformer
    @DefaultDataTableEntryTransformer
    @DefaultDataTableCellTransformer
    public Object transformer(Object fromValue, Type toValueType) {
        return objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType));
    }
}
```

For lambda-defined step definitions, there are `DefaultParameterTransformer`, `DefaultDataTableCellTransformer` and `DefaultDataTableEntryTransformer` <Term>stepdef-body</Term>s:

```java
package com.example;

import io.cucumber.java8.En;

import com.fasterxml.jackson.databind.ObjectMapper;

import java.lang.reflect.Type;

public class LambdaStepDefinitions implements En {

    public LambdaStepDefinitions() {
        ObjectMapper objectMapper = new ObjectMapper();

        DefaultParameterTransformer((String fromValue, Type toValueType) ->
            objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType)));

        DefaultDataTableCellTransformer((fromValue, toValueType) ->
            objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType)));

        DefaultDataTableEntryTransformer((fromValue, toValueType) ->
            objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType)));
    }
}
```

    </Tab>
    <Tab lang="kotlin">

Data table and doc string types let you convert data tables and doc strings to objects. Like step definitions, type definitions are part of the glue. When placed on the glue path Cucumber will detect them automatically.

For example, the following class registers a custom "Author" data table type:

```kotlin
package com.example

import io.cucumber.java.DataTableType
import io.cucumber.java.en.Given
import kotlin.streams.toList

class StepDefinitions {

    @DataTableType
    fun authorEntry(entry: Map<String, String>): Author {
        return Author(
                entry["firstName"],
                entry["lastName"],
                entry["famousBook"])
    }

    @Given("There are my favorite authors")
    fun these_are_my_favourite_authors(authors: List<Author>) {
        // step implementation
    }
}
```

This class registers a custom "Book" type from an expression:

```kotlin
package com.example

import io.cucumber.java.ParameterType
import io.cucumber.java.en.Given

class StepDefinitions {

    @ParameterType(".*")
    fun book(bookName: String): Book {
        return Book(bookName)
    }

    @Given("{book} is my favorite book")
    fun this_is_my_favorite_book(book: Book) {
        // step implementation
    }
}
```

This class registers a custom type for a doc string:

```kotlin
package com.example

import com.fasterxml.jackson.core.JsonProcessingException
import com.fasterxml.jackson.databind.JsonNode
import com.fasterxml.jackson.databind.ObjectMapper
import io.cucumber.java.DocStringType
import io.cucumber.java.en.Given

class StepsDefinitions {

    companion object {
        private val objectMapper = ObjectMapper()
    }

    @DocStringType
    @Throws(JsonProcessingException::class)
    fun json(docString: String): JsonNode {
        return objectMapper.readValue(docString, JsonNode::class)
    }

    @Given("Books are defined by json")
    fun books_are_defined_by_json(books: JsonNode) {
        // step implementation
    }
}
```

For lambda-defined step definitions, there are `DataTableType`, `ParameterType` and `DocStringType` functions:

```kotlin
package com.example

import com.fasterxml.jackson.databind.JsonNode
import com.fasterxml.jackson.databind.ObjectMapper

import io.cucumber.java8.En

class LambdaStepDefinitions : En {

    init {
        val objectMapper = ObjectMapper()

        ParameterType("book", ".*") { s : String ->
            Book(s)
        }

        DataTableType { entry: Map<String, String> ->
            Author(entry["firstName"], entry["lastName"], entry["famousBook"])
        }

        DocStringType("json") { docString: String ->
	        objectMapper.readValue(docString, JsonNode::class)
	    }
    }
}
```

Using the `@DefaultParameterTransformer`, `@DefaultDataTableEntryTransformer` and `@DefaultDataTableCellTransformer` annotations, it is also possible to plug in an object mapper. The object mapper (Jackson in this example) will handle the conversion of anonymous parameter types and data table entries:

```kotlin
package com.example

import com.fasterxml.jackson.databind.ObjectMapper
import io.cucumber.java.DefaultDataTableCellTransformer
import io.cucumber.java.DefaultDataTableEntryTransformer
import io.cucumber.java.DefaultParameterTransformer

import java.lang.reflect.Type

class StepDefinitions {

    private val objectMapper = ObjectMapper()

    @DefaultParameterTransformer
    @DefaultDataTableEntryTransformer
    @DefaultDataTableCellTransformer
    fun transformer(fromValue: Any, toValueType: Type): Any {
        return objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType))
    }
}
```

For lambda-defined step definitions, there are `DefaultParameterTransformer`, `DefaultDataTableCellTransformer` and `DefaultDataTableEntryTransformer` <Term>stepdef-body</Term>s:

```kotlin
import com.fasterxml.jackson.databind.ObjectMapper

import io.cucumber.java8.En
import java.lang.reflect.Type

class LambdaStepDefinitions : En {
    init {
        val objectMapper = ObjectMapper()

        DefaultParameterTransformer { fromValue: String, toValueType: Type ->
            objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType))
        }

        DefaultDataTableCellTransformer { fromValue, toValueType ->
            objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType))
        }

        DefaultDataTableEntryTransformer { fromValue, toValueType ->
            objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType))
        }
    }
}
```

    </Tab>
    <Tab lang="scala">

Data table and doc string types let you convert data tables and doc strings to objects. Like step definitions, type definitions are part of the glue. When placed on the glue path Cucumber will detect them automatically.

For example, the following class registers a custom "Author" data table type:

```scala
package com.example

import io.cucumber.scala.{ScalaDsl, EN}

class StepDefinitions extends ScalaDsl with EN {

    DataTableType { entry: Map[String, String] =>
        Author(
            entry("firstName"),
            entry("lastName"),
            entry("famousBook"))
    }

    Given("There are my favorite authors") { authors: List[Author] =>
        // step implementation
    }
}
```

This class registers a custom "Book" type from an expression:

```scala
package com.example

import io.cucumber.scala.{ScalaDsl, EN}

class StepDefinitions extends ScalaDsl with EN {

    ParameterType("book", ".*") { bookName: String =>
        Book(bookName)
    }

    Given("{book} is my favorite book") { book: Book =>
        // step implementation
    }
}
```

This class registers a custom type for a doc string:

```scala
package com.example

import com.fasterxml.jackson.core.JsonProcessingException
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper
import io.cucumber.scala.{ScalaDsl, EN}

object StepsDefinitions {
    private val objectMapper = ObjectMapper()
}

class StepsDefinitions extends ScalaDsl with EN {

    DocStringType("json") { docString: String =>
        objectMapper.readValue(docString, classOf[JsonNode])
    }

    Given("Books are defined by json") { books: JsonNode =>
        // step implementation
    }
}
```

Using the `DefaultParameterTransformer`, `DefaultDataTableEntryTransformer` and `DefaultDataTableCellTransformer` methods, it is also possible to plug in an object mapper. The object mapper (Jackson in this example) will handle the conversion of anonymous parameter types and data table entries:

```scala
package com.example

import com.fasterxml.jackson.databind.ObjectMapper
import io.cucumber.scala.ScalaDsl

import java.lang.reflect.Type

class StepDefinitions extends ScalaDsl {

    private val objectMapper = ObjectMapper()

    DefaultParameterTransformer { (fromValue: String, toValueType: Type) =>
        objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType))
    }

    DefaultDataTableCellTransformer { (fromValue: String, toValueType: Type) =>
        objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType))
    }

    DefaultDataTableEntryTransformer { (fromValue: Map[String, String], toValueType: Type) =>
        objectMapper.convertValue(fromValue, objectMapper.constructType(toValueType))
    }
}
```

If you want to, you can use the predefined `JacksonDefaultDataTableEntryTransformer` trait which defines default transformers using Jackson Scala Module.

See [Default Jackon DataTable Transformer](https://github.com/cucumber/cucumber-jvm-scala/blob/master/docs/default_jackson_datatable_transformer.md).

    </Tab>
    <Tab lang="javascript">

See the cucumber-js docs on GitHub for more on working with [parameter types](https://github.com/cucumber/cucumber-js/blob/main/features/parameter_types.feature) and [data tables](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/data_table_interface.md) in JavaScript.

    </Tab>
    <Tab lang="ruby">

A parameter type lets you transform an argument from a string to another type before it's passed to the step definition.

For example, let's define our own "Person" type:

```ruby
ParameterType(
  name: 'person',
  regexp: /[A-Z][a-z]+/,
  transformer: -> (name) { Person.new(name) }
)
```

Here's an example of how to use this in a step definition:

```ruby
Then('a user {person} should have {int} followers') do |person, count|
  puts person.is_a?(Person)
end
```

    </Tab>
</Tabs>

If you try to use a type that has not yet been defined, you will see an error similar to:

```shell
The parameter type "person" is not defined.
```

## Profiles

<Tabs>
    <Tab lang="java,kotlin,scala">

Cucumber profiles are not available on Cucumber-JVM.  However, it is possible to set configuration options using [Maven profiles](https://maven.apache.org/guides/introduction/introduction-to-profiles.html)

For instance, we can configure separate profiles for scenarios which are to be run in separate environments like so:

```xml
    <profiles>
        <profile>
          <id>dev</id>
            <properties>
                <cucumber.filter.tags>@dev and not @ignore</cucumber.filter.tags>
            </properties>
        </profile>
        <profile>
          <id>qa</id>
            <properties>
                <cucumber.filter.tags>@qa</cucumber.filter.tags>
            </properties>
        </profile>
    </profiles>

    <build>
        <plugins>
            ...
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.0.0-M4</version>
                <configuration>
                    <systemPropertyVariables>
                       <cucumber.filter.tags>${cucumber.filter.tags}</cucumber.filter.tags>
                    </systemPropertyVariables>
                </configuration>
            </plugin>
        </plugins>
    </build>
```

To mimick similar behavior using Gradle, see the Gradle docs on [Migrating Maven profiles and properties](https://docs.gradle.org/current/userguide/migrating_from_maven.html#migmvn:profiles_and_properties).

    </Tab>
    <Tab lang="javascript">See the cucumber-js docs on GitHub for more on how to work with [profiles](https://github.com/cucumber/cucumber-js/blob/main/docs/profiles.md) in JavaScript.</Tab>
    <Tab lang="ruby">

You can specify configuration options for Cucumber in a `cucumber.yml` or `cucumber.yaml` file.
This file must be in a `.config` directory, or `config` subdirectory of your current working directory.

```yaml
config/cucumber.yml
## ##YAML Template
html_report: --format progress --format html --out=features_report.html
bvt: --tags @bvt
```

Defining a template requires a name and then the command-line options that you
want to execute with this profile.

The example above generates two profiles:

1. `html_report`, with a list of command-line options that specify new output formats, and
2. `bvt`, which executes all Features and Scenarios [tagged](/docs/cucumber/api#tags) with `@bvt`.

Cucumber-Rails creates a `cucumber.yml` file in the project config directory containing a number of predefined profiles,
one of which is the default profile. When Cucumber is run from the command line, it is usually necessary to provide both
the directory name containing the root directory of the tree containing feature files and the directory name containing
references to the necessary library files. In a typical project, `cucumber --require features features/some/path` will suffice.
Repetitious usages can be added to user-defined profiles contained in the project's `cucumber.yml` file.

To execute the profile, use:

```shell
\[user@system project] cucumber --profile html_report
\[user@system project] cucumber -p bvt
```

Use the flag `--profile` or `-p` to execute Cucumber with a profile.
You can still use other command line arguments alongside `--profile` or `-p`,
if desired.

```shell
\[user@system project] cucumber --profile html_report --tags ~@wip
```

Multiple profiles can even be specified together. The following executes all
Features and Scenarios tagged `@bvt`, with the specified progress and HTML
output.

```shell
\[user@system project] cucumber -p html_report -p bvt
```

Chances are you’ll want to execute Cucumber with a particular profile most of the time.
The Cucumber configuration file uses a `default` profile to provide this functionality.
When you specify a `default` profile, you are telling Cucumber to use the `default` command-line options whenever you don't explicitly specify a different profile.

Using the same example, perhaps we want the `html_report` profile to be our default execution.
```yaml
1. config/cucumber.yml
   ## ##YAML Template
   default: --profile html_report --profile bvt
   html_report: --format progress --format html --out=features_report.html
   bvt: --tags @bvt
```

```shell
\[user@system project] cucumber
```

With this setup, Cucumber will now use both the `bvt` profile and `html_report`
profile, testing all Features and Scenarios tagged with `@bvt`, along with the
progress output and HTML output.

The `cucumber.yml` file is preprocessed by [ERB (Embedded RuBy)](https://ruby-doc.org/stdlib-2.5.0/libdoc/erb/rdoc/ERB.html). This allows you to use Ruby code
to generate values in the `cucumber.yml` file.

So, if you have several profiles with similar values, you might do this:

```yaml
1. config/cucumber.yml
   ## ##YAML Template
   <% common = "--tags ~@wip --strict" %>
   default: <%= common %> features
   html_report: <%= common %> --format html --out=features_report.html features
```

    </Tab>
</Tabs>

## Environment variables

<Tabs>
    <Tab lang="java,kotlin,scala">Cucumber-JVM does not support configuration with an `env` file.</Tab>
    <Tab lang="javascript">Cucumber-JS does not support configuration with an `env` file.</Tab>
    <Tab lang="ruby">

You can use environment variables in the profile argument list, just as you would normally specify them on the command-line.

```yaml
1. config/cucumber.yml
   \##YAML Template
2. ## ie profile executes the browser features with Internet Explorer
   default: --profile html_report --profile bvt
   html_report: --format progress --format html --out=features_report.html
   bvt: --tags @bvt
   ie: BROWSER=IE
   ```

When [running Cucumber](/docs/cucumber/api#running-cucumber), it can sometimes be handy to pass special
values to Cucumber for your [step definitions](/docs/cucumber/step-definitions) to use.

You can do this on the command line:

```shell
cucumber FOO=BAR --format progress features
```

You can now pick up `ENV\['FOO']` in Ruby (for example, in `env.rb`, or a Step Definition) and perform actions according to the value.

You can also do this in `cucumber.yml`.

For example, the following sets up a profile that runs the specified Tag and sets an environment variable:

```yaml
baz: --tags @mytag FOO=BAR
```

Local Cucumber customisation code in `support/env.rb` itself as that file is typically
overwritten by `script/generate cucumber:install | rails g cucumber`. Customisations that
must be loaded before the rest of Cucumber initialises must be placed at the beginning of the `env.rb file`.

Every file ending in `.rb` that is found in features/support is loaded by Cucumber. Therefore, if you place local
customisations in any `.rb` file in that directory, they will get loaded. However, be advised that in
Cucumber < 4.x, the `--dry-run` option only excludes files in `features/support` that match the regexp `/env\\..\*/`
(*note that the trailing dot is significant*). So a file with local customisations called `my_locals.rb` will be loaded regardless.
In Cucumber 4.x, all support files, including `env.rb` files, are loaded.

If you put custom files inside `features/support` that you do not wish loaded when you do a dry-run with Cucumber,
you can use the `--exclude` flag to ensure they aren't loaded. In Cucumber versions < 4.x, you can also prefix the filenames
with `env`, as in `env.local.rb`. Note that a file called `local_env.rb`, for example, does not match the regex
above and therefore will be loaded in all versions of Cucumber unless specifically excluded.

As a matter of good practice you should always run `script/generate cucumber | rails g cucumber:install` whenever you
install an updated version of Cucumber or cucumber-rails. However, this overwrites `features/support/env.rb`.
In order to keep any custom configurations from your `env.rb` file, check in your `env.rb` along with the rest of your version
controlled files and be prepared to diff and merge changes to `env.rb` between versions of Cucumber-Rails.

    </Tab>
</Tabs>



================================================
FILE: docs/cucumber/cucumber-expressions.md
================================================
---
sidebar_position: 4
description: "Using variables in your step definitions"
---

# Cucumber Expressions

The [docs for Cucumber Expressions](https://github.com/cucumber/cucumber-expressions#readme) have moved to GitHub.



================================================
FILE: docs/cucumber/debugging.mdx
================================================
---
sidebar_position: 5
description: "How to debug failing Cucumber steps"
---

# Debugging

<Tabs>
    <Tab lang="java,kotlin,scala">

In order to debug your scenarios on the JVM, you can step through the steps of each scenario in debug mode.

1. Set a breakpoint on the part of the code you want to debug. This might be the line you are currently getting an Exception (see your stacktrace).
2. Run your [RunCucumberTest](https://github.com/cucumber/cucumber-java-skeleton/blob/main/maven/src/test/java/io/cucumber/skeleton/RunCucumberTest.java) in debug mode
3. The execution will stop at your breakpoint.
4. Now you can either:
   - *Step into* to start debugging the method implementing the first step of the scenario.
   - Or *Resume* the execution to run the current step and jump to the next one.
5. And so on..

For more details on how to set a breakpoint in your IDE, see [Breakpoints (IntelliJ IDEA)](https://www.jetbrains.com/help/idea/breakpoints.html) and [Debugging (Eclipse)](https://www.eclipse.org/community/eclipse_newsletter/2017/june/article1.php).

    </Tab>
    <Tab lang="ruby">

(The code given below calls on [the logging facilities of Ruby on Rails](https://guides.rubyonrails.org/debugging_rails_applications.html#the-logger). If you're not using Rails, replace those calls with `puts` or `warn`.)

Adding the following as the contents of `features/support/debugging.rb` can be helpful in debugging failing steps:

```ruby
# rubocop:disable Lint/Debugger
class CucumberCounters
  @error_counter = 0
  @step_counter = 0
  @screenshot_counter = 0
  class << self
    attr_accessor :error_counter, :step_counter, :screenshot_counter
  end
end

# `LAUNCHY=1 cucumber` to open save screenshot after every step
After do |scenario|
  next unless (ENV['LAUNCHY'] || ENV['CI']) && scenario.failed?
  puts "Opening snapshot for #{scenario.name}"
  begin
    save_and_open_screenshot
  rescue StandardError
    puts "Can't save screenshot"
  end
  begin
    save_and_open_page
  rescue StandardError
    puts "Can't save page"
  end
end

# `FAST=1 cucumber` to stop on first failure
After do |scenario|
  Cucumber.wants_to_quit = ENV['FAST'] && scenario.failed?
end

# `DEBUG=1 cucumber` to drop into debugger on failure
Cucumber::Core::Test::Action.class_eval do
  ## first make sure we don't lose original accept method
  unless instance_methods.include?(:orig_failed)
    alias_method :orig_failed, :failed
  end

  ## wrap original accept method to catch errors in executed step
  def failed(*args)
    begin
      CucumberCounters.error_counter += 1
      file_name = format('tmp/capybara/error_%03d.png',
                         CucumberCounters.error_counter)
      Capybara.page.save_screenshot(file_name, full: true)
    rescue
      Rails.logger.info('[Cucumber] Can not make screenshot of failure')
    end
    binding.pry if ENV['DEBUG']
    orig_failed(*args)
  end
end

# Store the current scenario name as an instance variable, to make it
# available to the other hooks.
Before do |scenario|
  case scenario
  when Cucumber::Ast::Scenario
    @scenario_name = scenario.name
  when Cucumber::Ast::OutlineTable::ExampleRow
    @scenario_name = scenario.scenario_outline.name
  end
  Rails.logger.info("[Cucumber] starting the #{@scenario_name}")
end

# `STEP=1 cucumber` to pause after each step
AfterStep do |scenario|
  next unless ENV['STEP']
  unless defined?(@counter)
    puts "Stepping through #{@scenario_name}"
    @counter = 0
  end
  @counter += 1
  print "After step ##{@counter}/#{scenario.send(:steps).try(:count)}: "\
        "#{scenario.send(:steps).to_a[@counter].try(:name) ||
        '[RETURN to continue]'}..."
  STDIN.getc
end

AfterStep do |scenario|
  CucumberCounters.step_counter += 1
  step = CucumberCounters.step_counter
  file_name = format('tmp/capybara/step_%03d.png', step)
  Rails.logger.info("[Cucumber] after step: #{@scenario_name}, step: #{step}")
  next unless scenario.source_tag_names.include?('@intermittent')
  begin
    Capybara.page.save_screenshot(file_name, full: true)
    Rails.logger.info("[Cucumber] Screenshot #{step} saved")
  rescue
    Rails.logger.info("[Cucumber] Can not make screenshot of #{step}")
  end
end

AfterStep do
  begin
    execute_script "$(window).unbind('beforeunload')"
  rescue => e
    Rails.logger.error("An error was encountered and rescued")
    Rails.logger.error(e.backtrace)
  end
end

def dismiss_nav_warning
  execute_script "$(window).unbind('beforeunload')"
  wait_until_jquery_inactive
end

def wait_until_jquery_inactive
  Capybara.using_wait_time(Capybara.default_max_wait_time) do
    page.evaluate_script('jQuery.active').zero?
  end
end
```

By setting an environment variable, you can tell Cucumber to use various debugging tools, and you can combine them by setting multiple environment variables.

    </Tab>
</Tabs>



================================================
FILE: docs/cucumber/environment-variables.md
================================================
---
sidebar_position: 6
description: "How to define Environment Variables"
---

# Environment variables

Cucumber uses [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to enable
certain features, such as publishing [Cucumber Reports](https://reports.cucumber.io).

There are many different ways to define environment variables, depending on your environment.
This guide describes how to define the `CUCUMBER_PUBLISH_TOKEN` environment variable with
value `some-secret-token`.

For security reasons you should *not* define environment variables containing secrets globally.

For MacOS and Linux users this means you should *not* define them in `~/.bashrc`,
`~/.bash_profile`, `~/.zshrc`, `/etc.profile` or similar.

For Windows users this means you should *not* define them via System/Control Panel or `setx.exe`.

## Terminal

If you are using a terminal to run Cucumber, you should define environment variables in the
same terminal.

This also applies to terminals embedded in an editor such as Visual Studio Code or IntelliJ IDEA.

### Windows

```shell
setx /M CUCUMBER_PUBLISH_TOKEN "some-secret-token"
```

### Bash / Zsh

```shell
export CUCUMBER_PUBLISH_TOKEN=some-secret-token
```

## Editor / IDE

If you are using an editor or IDE to run Cucumber via a menu or shortcut, you should
define environment variables in the editor.

If you are using a terminal embedded in the IDE, see the [Terminal](#terminal) section above.

### IntelliJ IDEA / WebStorm / RubyMine

Click the *Run/Debug Configuration* dropdown in the toolbar:

![Run/Debug Configuration](/img/docs/run-debug-configuration.png)

Click on the *Environment Variables* field.

![Environment Variabled Field](/img/docs/environment-variables-field.png)

Enter the environment variable and its value into the dialog.

![Run/Debug Configuration](/img/docs/enter-environment-variable.png)

### Other editors

Check the documentation for your editor, or help us improving this documentation by editing this page (link at the bottom of the page).

## Continuous Integration Servers

Every Continuous Integration server has a different mechanism for defining environment variables.
Please consult the documentation for your CI server about how to do this.



================================================
FILE: docs/cucumber/index.mdx
================================================
---
pagination_prev: installation/index
---

import DocCardList from '@theme/DocCardList';

# Cucumber

<DocCardList />



================================================
FILE: docs/cucumber/mocking-and-stubbing-with-cucumber.md
================================================
---
sidebar_position: 7
description: "Decoupling your scenarios from infrastructure"
---

# Mocking and stubbing

Mocking is usually discouraged when using Cucumber; ideally you would exercise as much of your stack as possible.
There are cases when using mocking can come in handy. For example, if your system depends on a third party.
If you have a dependency on an external system, we recommend using [stubs instead of mocks](https://martinfowler.com/articles/mocksArentStubs.html).
You **can** set up mocks with expectations in your [step definitions](/docs/cucumber/step-definitions).

## Java

Different mocking frameworks may serve different purposes:

- [Mockito](https://site.mockito.org/) is a framework for the creation of [test doubles](https://www.martinfowler.com/bliki/TestDouble.html) in automated unit tests for the purpose of TDD or BDD.
- You can use [MockServer](https://www.mock-server.com/) for mocking any system you integrate with via HTTP or HTTPS (i.e. services, web sites, etc).
- [WireMock](http://wiremock.org/) is a simulator for HTTP-based APIs, similar to MockServer.

## JavaScript

If you are using cucumber-js, there are many test frameworks to choose from. Which one you use, may depend on other JavaScript frameworks your project is using and / or personal preference.

## Ruby

### RSpec 2.x

Starting with Cucumber 0.8.4, you can use all of RSpec's supported mocking frameworks (RSpec, Mocha, RR, Flexmock).
Use `require 'cucumber/rspec/doubles'` ([test-double](https://www.martinfowler.com/bliki/TestDouble.html) is a more generic term than mocks and stubs).

Perhaps place your stub action within a block as below:

```ruby
require 'cucumber/rspec/doubles'

RSpec::Mocks.with_temporary_scope do
stub_resp = {"city"=>"San Francisco", "state_abbreviation"=>"CA", "state"=>"California", "mailable_city"=>true}
SmartyStreets.stub(:get_city_state).with("94109").and_return(stub_resp)

click_button "check zip"
end
```


================================================
FILE: docs/cucumber/reporting.md
================================================
---
sidebar_position: 8
description: "Built-in reporter plugins, custom formatters, third-party plugins"
---

# Reporting

Cucumber uses reporter plugins to produce reports that contain information about
what scenarios have passed or failed.

Some plugins are built-in, others have to be installed separately. You can also
build your own.

This page documents built-in formatter plugins, custom formatters and some common third-party plugins.
Available plugins may vary per programming language.

## Cucumber Reports service

The easiest way to get started with reporting is to use the [Cucumber Reports](https://reports.cucumber.io/) service.

Watch [this video](https://smartbear.wistia.com/medias/nrgptu7825) for a quick introduction.

Publishing to the Cucumber Reports service is currently supported in:

* Cucumber-JVM `6.7.0` and above
* Cucumber-Ruby `5.1.1` and above
* Cucumber-JS `7.0.0` and above

## Built-in reporter plugins

If you don't want to publish your reports to the [Cucumber Reports](https://reports.cucumber.io/) service, you can
generate local reports using one of the following built-in reporter plugins (also known as "formatters"):

* `message`
* `progress`
* `pretty`
* `html`
* `json`
* `rerun`
* `junit`
* `testng` (JVM only)

## Custom formatters

Cucumber implementations are extensible so that you can write and use your own formatter, or use a third-party one published by someone else. This involves creating a class that implements/extends the standard formatter interface.

### Formatter API

Cucumber uses an event-based API for its formatters. These formatters respond to several defined events, which are common across all official implementations under the [Cucumber Messages](https://github.com/cucumber/messages) standard.

## Third-party plugins
There are also many third-party plugins:

* Masterthought
* TeamCity - prints Cucumber results in a format for interpretation by a [TeamCity](https://www.jetbrains.com/teamcity/index.html) build agent.
   * [teamcity_formatter](https://github.com/kevinrood/teamcity_formatter) - Compatible with Cucumber 2.
   * [cucumber_teamcity](https://github.com/ankurcha/cucumber_teamcity/) - Tested with Cucumber 1.3.18 and TeamCity 8.x.
* [TextmateFormatter](https://github.com/raldred/cucumber_textmate/) prints Cucumber results as HTML with enhanced styling and Javascript for Textmate (Included in the Cucumber core since 0.4.5)
* [SlowHandCuke](https://github.com/moredip/SlowHandCuke) - A tweak to the Pretty formatter to display the currently running Step as it is running
* [timestamped-scenarios](https://github.com/moredip/timestamped-scenarios) - Append test run timestamps to each Scenario name as it is being output.
* [Fivemat](https://github.com/tpope/fivemat) - Cucumber formatter that gives each test file its own line of dots.
* [Fuubar](https://github.com/martinciu/fuubar-cucumber) - The insta-failing progress bar formatter
* [cucumber_timing_presenter](https://github.com/distributedlife/cucumber_timing_presenter) - formatter that calculates timing metrics as well as two graphs showing impact of Step time on overall build time.
* [ReportPortal.io adapter](https://github.com/reportportal/agent-js-cucumber) - agent for real-time reporting of CucumberJS tests into [ReportPortal](https://reportportal.io/) test-automation dashboard.
* [Bilgerat](https://github.com/mdsol/bilgerat) - formatter that sends failure messages to [HipChat](https://www.hipchat.com/) rooms.
* [cucumber_statistics](https://github.com/alienfast/cucumber_statistics) - Tracks timing and displays results in a single HTML page with outliers highlighted in a table sortable by various metrics.
* [cucumber_characteristics](https://github.com/singram/cucumber_characteristics) - Generates HTML/JSON reports on overall test timings, as well as timings and usage of Steps, Features, and Examples. Also lists unused and ambiguous (Cucumber 1.x) Steps. Compatible with Cucumber 1.x and 2.1+ and Ruby 1.9+.
* [allure-cucumber](https://github.com/allure-framework/allure-cucumber) - [Allure](https://github.com/allure-framework) adaptor for Cucumber. This formatter generates the XML files for Allure reporting framework.
* [Cluecumber](https://github.com/trivago/cluecumber-report-plugin) - Maven plugin for clear and concise Cucumber reporting.
* [Cucelastic](https://github.com/AshisRaj/cucelastic-maven-plugin) - Maven plugin to push test report data into Elastic Search to enable users to plugin UI agnostic tools like Kibana to visualize a dynamic and easy sharable report/dashboard with the possibility to filter and analyze the data, extend and share it across teams.
* [cucumber-reporting-plugin](https://gitlab.com/jamietanna/cucumber-reporting-plugin) - A Cucumber plugin which produces pretty HTML reports using [cucumber-reporting](https://github.com/damianszczepanik/cucumber-reporting)
* [Serenity/JS](https://serenity-js.org/handbook/integration/serenityjs-and-cucumber.html) - An acceptance testing and reporting framework with in-depth HTML reports, Screenplay Pattern APIs, and support for every single version of Cucumber.js
* [Lippia Test Manager](https://lippia.io) - Lippia Test Manager combines the use of Gherkin to support manual and automated test runs using Cucumber. It allows users to write tests in the Gherkin language without needing an integrated development environment (IDE) and to store them in code repositories, eliminating the need for mapping between manual and automated scenarios since it utilizes the .feature files. See samples of ingesting automated tests results here: [https://github.com/lippia-io/](https://github.com/lippia-io/)



================================================
FILE: docs/cucumber/state.mdx
================================================
---
sidebar_position: 9
description: "Sharing state, isolated state, dependency injection"
---

# State

## Sharing state between scenarios

Don't do it.

Scenarios must be independent of one other so it is important that state is not shared between scenarios.
Accidentally leaking state from one scenario into others makes your scenarios brittle and also difficult to run in isolation.

To prevent accidentally leaking state between scenarios:

* Avoid using global or static variables.
* Make sure you clean your database in a `Before` hook.
* If you share a browser between scenarios, delete cookies in a `Before` hook.

## Sharing state between steps

Within your scenarios, you might want to share state between steps.

It's possible to store state in variables inside your step definitions.

:::warning[Be careful with state]
State can make your steps more tightly coupled and harder to reuse.
:::

<Tabs>
    <Tab lang="java,kotlin,scala">

Cucumber will create a new instance of each of your glue code classes before each scenario
so your steps will not leak state.

When using Spring there is [an annotation `ScenarioScope`](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-spring#sharing-state)
that may be used on any spring beans that have been employed to share step state; this annotation ensures that these
beans do not persist across scenarios and so do not leak state.

Similarly, when using Guice there is [a scope `ScenarioScoped`](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-guice#using-scope-annotations)
that should always be used on step definition classes.

    </Tab>
    <Tab lang="javascript">

Cucumber-JS uses a `World` as an isolated context for each scenario. You can find more information in the
[docs on GitHub](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/world.md).

    </Tab>
    <Tab lang="ruby">

In Ruby, Cucumber runs scenarios in a `World`. By default, the `World` is an instance of `Object`.

All [step definitions](/docs/cucumber/step-definitions) will run in the context of the current `World` instance; a new instance
is created for each scenario. This means that `self` in a step definition block will be the `World` instance. Any `@instance_variable`
instantiated in a step definition will be assigned to the `World`, and can be accessed from other step definitions.

If you want to add any behaviour to the world, like helper methods, or logging, you can do this in `support/env.rb`:

```ruby
module CustomWorld
  def a_helper
    ...
  end
end

World(CustomWorld)
```

Now you can call `a_helper` from your step definitions.

Note that every scenario is run in a separate instance of the world,
so there is no implicit state-sharing from scenario to scenario.

You can also include modules in your `World`:

```ruby
module MyHelper
  def some_other_helper
    ...
  end
end

module CustomWorld
  include MyHelper

  def a_helper
    ...
  end
end

World(CustomWorld)
```

Several other frameworks such as Rspec or Webrat have modules that provide special methods that you can include in your `World` this way.

If you don't want to define your own `World` class (and just use the default `Object` instances), you can still include modules
in your `World` instances without polluting `Object` with a global include:

```ruby
module MyHelper
  def some_other_helper
    ...
  end
end

module MyOtherHelpers
  def helper_b
    ...
  end
end

World(MyHelper, MyOtherHelpers)
```

This will `extend` each new `World` object with those modules.

If you use [Ruby on Rails](/docs/tools/ruby#ruby-on-rails), there is already a `World` set up for you, so you will get
an instance of `Cucumber::Rails::World`, which is a subclass of `ActionDispatch::IntegrationTest`. This gives you access
to a lot of Rails' helper methods.

    </Tab>
</Tabs>

## Dependency injection

:::info[JVM only]
This section is only applicable to JVM-based implementations of Cucumber.
:::

If your programming language is a JVM language, you will be writing glue code
([step definitions](/docs/cucumber/step-definitions) and [hooks](/docs/cucumber/api/#hooks)) in classes.

Cucumber will create a new instance of each of your glue code classes before each scenario.

If all of your glue code classes have an empty constructor, you don’t need anything else.
However, most projects will benefit from a dependency injection (DI) module to organize your code better and to share state between step definitions.

The available dependency injection modules are:

- [PicoContainer](#picocontainer) (the recommended one if your application doesn't use another DI module)
- [Spring](#spring)
- [Guice](#guice)
- [OpenEJB](#openejb)
- [Weld](#weld)
- [Needle](#needle)
- [Quarkus](#quarkus)

### PicoContainer

To use PicoContainer, add the following dependency to your `pom.xml`:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-picocontainer</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

Or, if you are using Gradle, add:

```kotlin
testImplementation("io.cucumber:cucumber-picocontainer:{{% version "cucumberjvm" %}}")
```

There is no documentation yet, but the code is on [GitHub](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-picocontainer).
For more information, please see [sharing state using PicoContainer](http://www.thinkcode.se/blog/2017/04/01/sharing-state-between-steps-in-cucumberjvm-using-picocontainer).

### Spring

To use Spring, add the following dependency to your `pom.xml`:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-spring</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

Or, if you are using Gradle, add:

```kotlin
testImplementation("io.cucumber:cucumber-spring:{{% version "cucumberjvm" %}}")
```

There is no documentation yet, but the code is on [GitHub](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-spring).

### Guice

To use Guice, add the following dependency to your `pom.xml`:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-guice</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

Or, if you are using Gradle, add:

```kotlin
testImplementation("io.cucumber:cucumber-guice:{{% version "cucumberjvm" %}}")
```

There is no documentation yet, but the code is on [GitHub](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-guice).
For more information, please see [sharing state using Guice](http://www.thinkcode.se/blog/2017/08/16/sharing-state-between-steps-in-cucumberjvm-using-guice).

### OpenEJB

To use OpenEJB, add the following dependency to your `pom.xml`:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-openejb</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

Or, if you are using Gradle, add:

```kotlin
testImplementation("io.cucumber:cucumber-openejb:{{% version "cucumberjvm" %}}")
```

There is no documentation yet, but the code is on [GitHub](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-openejb).

### Weld

To use Weld, add the following dependency to your `pom.xml`:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-weld</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

Or, if you are using Gradle, add:

```kotlin
testImplementation("io.cucumber:cucumber-weld:{{% version "cucumberjvm" %}}")
```

There is no documentation yet, but the code is on [GitHub](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-weld).

### Needle

To use Needle, add the following dependency to your `pom.xml`:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-needle</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

Or, if you are using Gradle, add:

```kotlin
testImplementation("io.cucumber:cucumber-needle:{{% version "cucumberjvm" %}}")
```

There is no documentation yet, but the code is on [GitHub](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-needle).


### Quarkus

To use Quarkus, add the following dependency to your `pom.xml`:

```xml
<dependency>
    <groupId>io.quarkiverse.cucumber</groupId>
    <artifactId>quarkus-cucumber</artifactId>
    <version>{quarkus-cucumber.version}</version>
    <scope>test</scope>
</dependency>
```

The documentation can be found on [Quarkiverse - Cucumber](https://docs.quarkiverse.io/quarkus-cucumber/dev/index.html).

### How to use DI

When using a DI framework all your step definitions, hooks, transformers, etc. will be created by the frameworks instance injector.

#### Using a custom injector

Cucumber example tests are typically small and have no dependencies. In real life, though,
tests often need access to application specific object instances which also need to be supplied by the injector. These
instances need to be made available to your step definitions so that actions can be applied on them and delivered
results can be tested.

The reason using Cucumber with a DI framework typically originates from the fact that the tested application also uses
the same framework. So we need to configure a custom injector to be used with Cucumber.
This injector ties tests and application instances together.

Here is an example of a typical step definition using [Google Guice](/docs/cucumber/state/#guice). Using the
Cucumber provided Guice injector will fail to instantiate the required `appService` member.

```java
package com.example.app;

import static org.junit.Assert.assertTrue;

import io.cucumber.java.en.When;
import io.cucumber.java.en.Then;
import io.cucumber.guice.ScenarioScoped;
import com.example.app.service.AppService;
import java.util.Objects;
import javax.inject.Inject;

@ScenarioScoped
public final class StepDefinition {

    private final AppService appService;

    @Inject
    public StepDefinition( AppService appService ) {
        this.appService = Objects.requireNonNull( appService, "appService must not be null" );
    }

    @When("the application services are started")
    public void startServices() {
        this.appService.startServices();
    }

    @Then("all application services should be running")
    public void checkThatApplicationServicesAreRunning() {
        assertTrue( this.appService.servicesAreRunning() );
    }
}
```

The implementation of the AppService may need further arguments and configuration that typically
has to be provided by a Guice module. Guice modules are used to configure an injector and might look like this:

```java
package com.example.app.service.impl;

import com.example.app.service.AppService;
import com.google.inject.AbstractModule;

public final class ServiceModule extends AbstractModule {
    @Override
    protected void configure() {
        bind( AppService.class ).to( AppServiceImpl.class );
        // ... (further bindings)
    }
}
```

The actual injector is then created like this: `injector = Guice.createInjector( new ServiceModule() );`

This means we need to create our own injector and tell Cucumber to use it.

#### The Cucumber object factory

Whenever Cucumber needs a specific object, it uses an object factory.
Cucumber has a default object factory that (in case of Guice) creates a default injector and
delegates object creation to that injector.
If you want to customize the injector we need to provide our own object factory and tell Cucumber to use it instead.

```java
package com.example.app;

import io.cucumber.core.backend.ObjectFactory;
import io.cucumber.guice.CucumberModules;
import io.cucumber.guice.ScenarioScope;
import com.example.app.service.impl.ServiceModule;
import com.google.inject.Guice;
import com.google.inject.Injector;
import com.google.inject.Stage;

public final class CustomObjectFactory implements ObjectFactory {

    private Injector injector;

    public CustomObjectFactory() {
        // Create an injector with our service module
        this.injector =
          Guice.createInjector( Stage.PRODUCTION, CucumberModules.createScenarioModule(), new ServiceModule());
    }

    @Override
    public boolean addClass( Class< ? > clazz ) {
        return true;
    }

    @Override
    public void start() {
        this.injector.getInstance( ScenarioScope.class ).enterScope();
    }

    @Override
    public void stop() {
        this.injector.getInstance( ScenarioScope.class ).exitScope();
    }

    @Override
    public < T > T getInstance( Class< T > clazz ) {
        return this.injector.getInstance( clazz );
    }
}
```

This is the default object factory for Guice except that we have added our own bindings to the injector.
Cucumber loads the object factory through the `java.util.ServiceLoader`. In order for the ServiceLoader to be able
to pick up our custom implementation we need to provide the file `META-INF/services/io.cucumber.core.backend.ObjectFactory`.

```
com.example.app.CustomObjectFactory
#
# ... additional custom object factories could be added here
#
```

Now we have to tell Cucumber to use our custom object factory. There are several ways how this could be accomplished.

##### Using the Cucumber object factory from the command line

When Cucumber is run from the command line, the custom object factory can be specified as argument.

```shell
java io.cucumber.core.cli.Main --object-factory com.example.app.CustomObjectFactory
```

##### Using the Cucumber object factory a property file

Cucumber makes use of a properties file (`cucumber.properties`) if it exists. The custom
object factory can be specified in this file and will be picked up when Cucumber is running. The following entry needs
to be available in the `cucumber.properties` file:

```
cucumber.object-factory=com.example.app.CustomObjectFactory
```

##### Using the Cucumber object factory with a test runner (JUnit 5/JUnit 4/TestNG)

The Cucumber modules for [JUnit 4](/docs/cucumber/api/#junit) and [TestNG](/docs/cucumber/checking-assertions/#testng) allow to run Cucumber through a JUnit/TestNG test.
The custom object factory can be configured using the `@CucumberOptions` annotation. For JUnit 5 see the [cucumber-junit-platform-engine](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine) documentation.

## The event bus

:::info[JVM only]
This section is only applicable to JVM-based implementations of Cucumber.
:::

Cucumber emits events on an event bus in many cases, e.g.:

- during the feature file parsing
- when the test scenarios are executed

### Configuring the UUID generator

Each event has a UUID as unique identifier. The UUID generator can be configured using the `cucumber.uuid-generator` property:

| UUID generator                                        | Features                                                                                                                                                                                                                       | Performance [Millions UUID/second] | Typical usage example                                                                                                                                                                                                                                                          |
|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `io.cucumber.core.eventbus.RandomUuidGenerator`       | <ul><li>Thread-safe</li><li>Collision-free in single-jvm/multi-jvm</li></ul>                                                                                                                                                   | ~1                                 | Reports may be generated on different JVMs at the same time. A typical example would be one suite that tests against Firefox and another against Safari. The exact browser is configured through a property. These are then executed concurrently on different Gitlab runners. |
| `io.cucumber.core.eventbus.IncrementingUuidGenerator` | <ul><li>Thread-safe</li><li>Collision-free in the same classloader</li><li>Almost collision-free in different classloaders / JVMs</li><li>UUIDs generated using the instances from the same classloader are sortable</li></ul> | ~130                               | For developers wanting high performance and accepting potential UUID collisions when running in different classloaders / JVMs setups.                                                                                                                                          |

The performance gain on real project depend on the feature size.

When the generator is not specified, the `RandomUuidGenerator` is used.

### Defining your own UUID generator

When neither the `RandomUuidGenerator` nor the `IncrementingUuidGenerator` suits the project needs, a custom UUID generator can be defined. This is done using the following method:

1. Creates a UUID class generator, e.g.:
```java
package mypackage.mysubpackage;
import io.cucumber.core.eventbus.UuidGenerator;
public class MyUuidGenerator implements UuidGenerator {
  @Override
  public UUID generateId() {
      return ...
  }
}
```
2. Define the UUID generator as SPI using a file `META-INF/services/io.cucumber.code.eventbus.UuidGenerator` on the classpath (e.g. Maven `resources` directory) containing the generator class name:
```java
mypackage.mysubpackage.MyUuidGenerator
```

This UUID generator will override the default `RandomUuidGenerator`.

When the `META-INF/services/...` file contains more than one UUID generator or when there are multiple `META-INF/services/...` on the classpath, the `cucumber.uuid-generator` property must be configured to select the desired generator.



================================================
FILE: docs/cucumber/step-definitions.mdx
================================================
---
sidebar_position: 1
description: "Connecting Gherkin steps to code"
---

# Step definitions

A Step Definition is a <Term>stepdef-body</Term> with an [expression](#expressions) that links it to one or more [Gherkin steps](/docs/gherkin/reference#steps).
When Cucumber executes a [Gherkin step](/docs/gherkin/reference#steps) in a scenario, it will look for a matching *step definition* to execute.

To illustrate how this works, look at the following Gherkin Scenario:

```gherkin
Scenario: Some cukes
  Given I have 48 cukes in my belly
```

The `I have 48 cukes in my belly` part of the step (the text following the `Given` keyword) will match the following step definition:

<Tabs>
    <Tab lang="java">

```java
package com.example;
import io.cucumber.java.en.Given;

public class StepDefinitions {
    @Given("I have {int} cukes in my belly")
    public void i_have_n_cukes_in_my_belly(int cukes) {
        System.out.format("Cukes: %n\n", cukes);
    }
}
```

Or, using Java8 lambdas:

```java
package com.example;
import io.cucumber.java8.En;

public class StepDefinitions implements En {
    public StepDefinitions() {
        Given("I have {int} cukes in my belly", (Integer cukes) -> {
            System.out.format("Cukes: %n\n", cukes);
        });
    }
}
```

    </Tab>
    <Tab lang="kotlin">

```kotlin
package com.example
import io.cucumber.java8.En

class StepDefinitions : En {

    init {
        Given("I have {int} cukes in my belly") { cukes: Int ->
                println("Cukes: $cukes")
        }
    }

}
```

    </Tab>
    <Tab lang="scala">

```scala
package com.example
import io.cucumber.scala.{ScalaDsl, EN}

class StepDefinitions extends ScalaDsl with EN {

    Given("I have {int} cukes in my belly") { cukes: Int =>
        println(s"Cukes: $cukes")
    }

}
```

    </Tab>
    <Tab lang="ruby">

```ruby
Given('I have {int} cukes in my belly') do |cukes|
  puts "Cukes: #{cukes}"
end
```

    </Tab>
    <Tab lang="javascript">

```javascript
const { Given } = require('cucumber')

Given('I have {int} cukes in my belly', function (cukes) {
  console.log(`Cukes: ${cukes}`)
});
```

    </Tab>
</Tabs>

## Expressions

A step definition's *expression* can either be a [Regular Expression](https://en.wikipedia.org/wiki/Regular_expression)
or a [Cucumber Expression](/docs/cucumber/cucumber-expressions). The examples in this section use Cucumber Expressions.
If you prefer to use Regular Expressions, each <Term>expression-parameter</Term> from the match will be passed as arguments to the step
definition's <Term>stepdef-body</Term>.

<Tabs>
    <Tab lang="java">

```java
@Given("I have {int} cukes in my belly")
public void i_have_n_cukes_in_my_belly(int cukes) {
}
```

    </Tab>
    <Tab lang="kotlin">

```kotlin
Given("I have {int} cukes in my belly") { cukes: Int ->
        println("Cukes: $cukes")
}
```

    </Tab>
    <Tab lang="scala">

```scala
Given("I have {int} cukes in my belly") { cukes: Int =>
    println(s"Cukes: $cukes")
}
```

    </Tab>
    <Tab lang="ruby">

```ruby
Given(/I have {int} cukes in my belly/) do |cukes|
end
```

    </Tab>
    <Tab lang="javascript">

```javascript
Given(/I have {int} cukes in my belly/, function (cukes) {
});
```

    </Tab>
</Tabs>

If the <Term>expression-parameter</Term> expression is identical to one of the registered
[parameter types](/docs/cucumber/cucumber-expressions#parameter-types)'s `regexp`,
the captured string will be transformed before it is passed to the
step definition's <Term>stepdef-body</Term>. In the example above, the `cukes`
argument will be an integer, because the built-in `int` parameter type's
`regexp` is `\d+` .



================================================
FILE: docs/gherkin/_category_.json
================================================
{
  "position": 3,
  "label": "Gherkin"
}



================================================
FILE: docs/gherkin/index.mdx
================================================
import DocCardList from '@theme/DocCardList';

# Gherkin

<DocCardList />



================================================
FILE: docs/gherkin/languages.mdx
================================================
---
sidebar_position: 1
---

import { GherkinLanguages } from "@site/src/components/GherkinLanguages";

# Localisation

In order to allow Gherkin to be written in a number of languages, the keywords have been translated into multiple languages. To improve readability and flow, some languages may have more than one translation for any given keyword.

You can find all translation of Gherkin [on GitHub](https://github.com/cucumber/gherkin).
This is also the place to add or update translations.

A list of the currently supported languages and their keywords can be found below.

<GherkinLanguages/>



================================================
FILE: docs/gherkin/reference.md
================================================
---
sidebar_position: 0
---

# Reference

Gherkin uses a set of special [keywords](#keywords) to give structure and meaning to
executable specifications. Each keyword is translated to many spoken languages;
in this reference we'll use English.

Most lines in a Gherkin document start with one of the [keywords](#keywords).

Comments are only permitted at the start of a new line, anywhere in the feature file. They begin with zero or more spaces,
followed by a hash sign (`#`) and some text.

Block comments are currently not supported by Gherkin.

Either spaces or tabs may be used for indentation. The recommended indentation
level is two spaces. Here is an example:

```gherkin
Feature: Guess the word

  # The first example has two steps
  Scenario: Maker starts a game
    When the Maker starts a game
    Then the Maker waits for a Breaker to join

  # The second example has three steps
  Scenario: Breaker joins a game
    Given the Maker has started a game with the word "silky"
    When the Breaker joins the Maker's game
    Then the Breaker must guess a word with 5 characters
```

The trailing portion (after the keyword) of each step is matched to
a code block, called a [step definition](/docs/cucumber/step-definitions).

Please note that some keywords *are* followed by a colon (`:`) and some *are not*. If you add a colon after a keyword
that should not be followed by one, your test(s) will be ignored.

## Keywords

Each line that isn't a blank line has to start with a Gherkin *keyword*, followed by any text you like. The only exceptions are the free-form descriptions placed underneath `Example`/`Scenario`, `Background`, `Scenario Outline` and `Rule` lines.

The primary keywords are:

- [`Feature`](#feature)
- [`Rule`](#rule) (as of Gherkin 6)
- [`Example`](#example) (or `Scenario`)
- [`Given`](#given), [`When`](#when), [`Then`](#then), [`And`](#and-but), [`But`](#and-but) for steps (or [`*`](#*))
- [`Background`](#background)
- [`Scenario Outline`](#scenario-outline) (or [`Scenario Template`](#scenario-outline))
- [`Examples`](#examples) (or [`Scenarios`](#examples))

There are a few secondary keywords as well:

- `"""` (Doc Strings)
- `|` (Data Tables)
- `@` (Tags)
- `#` (Comments)

:::info[Localisation]
Gherkin is localised for many [spoken languages](#spoken-languages); each has their own localised equivalent of these keywords.
:::

### Feature

The purpose of the `Feature` keyword is to provide a high-level description
of a software feature, and to group related scenarios.

The first primary keyword in a Gherkin document must always be `Feature`, followed
by a `:` and a short text that describes the feature.

You can add free-form text underneath `Feature` to add more description.

These description lines are ignored by Cucumber at runtime, but are available for reporting (they are included by reporting tools like the official HTML formatter).

```gherkin
Feature: Guess the word

  The word guess game is a turn-based game for two players.
  The Maker makes a word for the Breaker to guess. The game
  is over when the Breaker guesses the Maker's word.

  Example: Maker starts a game
```

The name and the optional description have no special meaning to Cucumber. Their purpose is to provide
a place for you to document important aspects of the feature, such as a brief explanation
and a list of business rules (general acceptance criteria).

The free format description for `Feature` ends when you start a line with the keyword `Background`, `Rule`, `Example` or `Scenario Outline` (or their alias keywords).

You can place [tags](/docs/cucumber/api/#tags) above `Feature` to group related features,
independent of your file and directory structure.

You can only have a single `Feature` in a `.feature` file.

### Descriptions

Free-form descriptions (as described above for `Feature`) can also be placed underneath
`Example`/`Scenario`, `Background`, `Scenario Outline` and `Rule`.

You can write anything you like, as long as no line starts with a keyword.

Descriptions can be in the form of Markdown - formatters including the official HTML formatter support this.

### Rule

The (optional) `Rule` keyword has been part of Gherkin since v6.

The purpose of the `Rule` keyword is to represent one *business rule* that should be implemented.
It provides additional information for a feature.
A `Rule` is used to group together several scenarios
that belong to this *business rule*. A `Rule` should contain one or more scenarios that illustrate the particular rule.

For example:

```gherkin
# -- FILE: features/gherkin.rule_example.feature
Feature: Highlander

  Rule: There can be only One

    Example: Only One -- More than one alive
      Given there are 3 ninjas
      And there are more than one ninja alive
      When 2 ninjas meet, they will fight
      Then one ninja dies (but not me)
      And there is one ninja less alive

    Example: Only One -- One alive
      Given there is only 1 ninja alive
      Then they will live forever ;-)

  Rule: There can be Two (in some cases)

    Example: Two -- Dead and Reborn as Phoenix
      ...
```

### Example

This is a *concrete example* that *illustrates* a business rule. It consists of
a list of [steps](#steps).

The keyword `Scenario` is a synonym of the keyword `Example`.

You can have as many steps as you like, but we recommend 3-5 steps per example. Having too many steps will cause the example to lose its expressive power as a specification and documentation.

In addition to being a specification and documentation, an example is also a *test*. As a whole, your examples are an
*executable specification* of the system.

Examples follow this same pattern:

- Describe an initial context (`Given` steps)
- Describe an event (`When` steps)
- Describe an expected outcome (`Then` steps)

### Steps

Each step starts with `Given`, `When`, `Then`, `And`, or `But`.

Cucumber executes each step in a scenario one at a time, in the sequence you’ve written them in.
When Cucumber tries to execute a step, it looks for a matching step definition to execute.

Keywords are not taken into account when looking for a step definition. This means you cannot have a
`Given`, `When`, `Then`, `And` or `But` step with the same text as another step.

Cucumber considers the following steps duplicates:

```gherkin
Given there is money in my account
Then there is money in my account
```

This might seem like a limitation, but it forces you to come up with a less ambiguous, more clear
domain language:

```gherkin
Given my account has a balance of £430
Then my account should have a balance of £430
```

#### Given

`Given` steps are used to describe the initial context of the system - the *scene* of the scenario.
It is typically something that happened in the *past*.

When Cucumber executes a `Given` step, it will configure the system to be in a well-defined state,
such as creating and configuring objects or adding data to a test database.

The purpose of `Given` steps is to **put the system in a known state** before the user (or external system) starts interacting with the system (in the `When` steps).
Avoid talking about user interaction in `Given`'s. If you were creating use cases, `Given`'s would be your preconditions.

It's okay to have several `Given` steps (use `And` or `But` for number 2 and upwards to make it more readable).

Examples:

- Mickey and Minnie have started a game
- I am logged in
- Joe has a balance of £42

#### When

`When` steps are used to describe an event, or an *action*. This can be a person interacting with the system, or it can be an event triggered by another system.

Examples:

- Guess a word
- Invite a friend
- Withdraw money

:::info[Imagine it's 1922]
Most software does something people could do manually (just not as efficiently).

Try hard to come up with examples that don't make any assumptions about
technology or user interface. Imagine it's 1922, when there were no computers.

Implementation details should be hidden in the [step definitions](/docs/cucumber/step-definitions).
:::

#### Then

`Then` steps are used to describe an *expected* outcome, or result.

The [step definition](/docs/cucumber/step-definitions) of a `Then` step should use an *assertion* to
compare the *actual* outcome (what the system actually does) to the *expected* outcome
(what the step says the system is supposed to do).

An outcome *should* be on an **observable** output. That is, something that comes *out* of the system (report, user interface, message), and not a behaviour deeply buried inside the system (like a record in a database).

Examples:

- See that the guessed word was wrong
- Receive an invitation
- Card should be swallowed

While it might be tempting to implement `Then` steps to look in the database - resist that temptation!

You should only verify an outcome that is observable for the user (or external system), and changes to a database are usually not.

#### And, But

If you have successive `Given`'s or `Then`'s, you *could* write:

```gherkin
Example: Multiple Givens
  Given one thing
  Given another thing
  Given yet another thing
  When I open my eyes
  Then I should see something
  Then I shouldn't see something else
```

Or, you could make the example more fluidly structured by replacing the successive `Given`'s or `Then`'s with `And`'s and `But`'s:

```gherkin
Example: Multiple Givens
  Given one thing
  And another thing
  And yet another thing
  When I open my eyes
  Then I should see something
  But I shouldn't see something else
```

#### \*

Gherkin also supports using an asterisk (`*`) in place of any of the normal step keywords. This can be helpful when you have some steps that are effectively a _list of things_, so you can express it more like bullet points where otherwise the natural language of `And` etc might not read so elegantly.

For example:

```gherkin
Scenario: All done
  Given I am out shopping
  And I have eggs
  And I have milk
  And I have butter
  When I check my list
  Then I don't need anything
```

Could be expressed as:

```gherkin
Scenario: All done
  Given I am out shopping
  * I have eggs
  * I have milk
  * I have butter
  When I check my list
  Then I don't need anything
```

### Background

Occasionally you'll find yourself repeating the same `Given` steps in all of the scenarios in a `Feature`.

Since it is repeated in every scenario, this is an indication that those steps
are not *essential* to describe the scenarios; they are *incidental details*. You can literally move such `Given` steps to the background, by grouping them under a `Background` section.

A `Background` allows you to add some context to the scenarios that follow it. It can contain one or more `Given` steps, which are run before *each* scenario, but after any [Before hooks](/docs/cucumber/api/#hooks).

A `Background` is placed before the first `Scenario`/`Example`, at the same level of indentation.

For example:

```gherkin
Feature: Multiple site support
  Only blog owners can post to a blog, except administrators,
  who can post to all blogs.

  Background:
    Given a global administrator named "Greg"
    And a blog named "Greg's anti-tax rants"
    And a customer named "Dr. Bill"
    And a blog named "Expensive Therapy" owned by "Dr. Bill"

  Scenario: Dr. Bill posts to his own blog
    Given I am logged in as Dr. Bill
    When I try to post to "Expensive Therapy"
    Then I should see "Your article was published."

  Scenario: Dr. Bill tries to post to somebody else's blog, and fails
    Given I am logged in as Dr. Bill
    When I try to post to "Greg's anti-tax rants"
    Then I should see "Hey! That's not your blog!"

  Scenario: Greg posts to a client's blog
    Given I am logged in as Greg
    When I try to post to "Expensive Therapy"
    Then I should see "Your article was published."
```

`Background` is also supported at the `Rule` level, for example:

```gherkin
Feature: Overdue tasks
  Let users know when tasks are overdue, even when using other
  features of the app

  Rule: Users are notified about overdue tasks on first use of the day
    Background:
      Given I have overdue tasks

    Example: First use of the day
      Given I last used the app yesterday
      When I use the app
      Then I am notified about overdue tasks

    Example: Already used today
      Given I last used the app earlier today
      When I use the app
      Then I am not notified about overdue tasks
  ...
```

You can only have one set of `Background` steps per `Feature` or `Rule`. If you need different `Background` steps for different scenarios, consider breaking up your set of scenarios into more `Rule`s or more `Feature`s.

For a less explicit alternative to `Background`, check out [conditional hooks](/docs/cucumber/api/#conditional-hooks).

#### Tips for using Background

* Don't use `Background` to set up **complicated states**, unless that state is actually something the client needs to know.
    * For example, if the user and site names don't matter to the client, use a higher-level step such as
      `Given I am logged in as a site owner`.
* Keep your `Background` section **short**.
    * The client needs to actually remember this stuff when reading the scenarios. If the `Background` is more than 4 lines long, consider moving some of the irrelevant details into higher-level steps.
* Make your `Background` section **vivid**.
    * Use colourful names, and try to tell a story. The human brain keeps track of stories much better than it keeps track of names like `"User A"`, `"User B"`, `"Site 1"`, and so on.
* Keep your scenarios **short**, and don't have too many.
    * If the `Background` section has scrolled off the screen, the reader no longer has a full overview of what's happening.
      Think about using higher-level steps, or splitting the `*.feature` file.

### Scenario Outline

The `Scenario Outline` keyword can be used to run the same `Scenario` multiple times,
with different combinations of values.

The keyword `Scenario Template` is a synonym of the keyword `Scenario Outline`.

Copying and pasting scenarios to use different values quickly becomes tedious and repetitive:

```gherkin
Scenario: eat 5 out of 12
  Given there are 12 cucumbers
  When I eat 5 cucumbers
  Then I should have 7 cucumbers

Scenario: eat 5 out of 20
  Given there are 20 cucumbers
  When I eat 5 cucumbers
  Then I should have 15 cucumbers
```

We can collapse these two similar scenarios into a `Scenario Outline`.

Scenario outlines allow us to more concisely express these scenarios through the use
of a template with `< >`-delimited parameters:

```gherkin
Scenario Outline: eating
  Given there are <start> cucumbers
  When I eat <eat> cucumbers
  Then I should have <left> cucumbers

  Examples:
    | start | eat | left |
    |    12 |   5 |    7 |
    |    20 |   5 |   15 |
```

### Examples

A `Scenario Outline` must contain one or more `Examples` (or `Scenarios`) section(s). Its steps are interpreted as a
template
which is never directly run. Instead, the `Scenario Outline` is run *once for each row* in
the `Examples` section beneath it (not counting the first header row).

The steps can use `<>` delimited *parameters* that reference headers in the examples table.
Cucumber will replace these parameters with values from the table *before* it tries
to match the step against a step definition.

You can use parameters in `Scenario Outline` descriptions as well.

You can also use parameters in [multiline step arguments](#step-arguments).

## Step Arguments

In some cases you might want to pass more data to a step than fits on a single line.
For this purpose Gherkin has `Doc Strings` and `Data Tables`.

### Doc Strings

`Doc Strings` are handy for passing a larger piece of text to a step definition.

The text should be offset by delimiters consisting of three double-quote marks on lines of their own:
```gherkin
Given a blog post named "Random" with Markdown body
  """
  Some Title, Eh?
  ===============
  Here is the first paragraph of my blog post. Lorem ipsum dolor sit amet,
  consectetur adipiscing elit.
  """
```
In your step definition, there’s no need to find this text and match it in your pattern.
It will automatically be passed as the last argument in the step definition.

Indentation of the opening `"""` is unimportant, although common practice is two spaces in from the enclosing step.
The indentation inside the triple quotes, however, is significant. Each line of the Doc String will be dedented according to the opening `"""`. Indentation beyond the column of the opening `"""` will therefore be preserved.

Doc strings also support using three backticks as the delimiter:

~~~gherkin
Given a blog post named "Random" with Markdown body
  ```
  Some Title, Eh?
  ===============
  Here is the first paragraph of my blog post. Lorem ipsum dolor sit amet,
  consectetur adipiscing elit.
  ```
~~~

This might be familiar for those used to writing with Markdown.

:::warning[Tool support for backticks]
Whilst all current versions of Cucumber support backticks as the delimiter, many tools like text editors don't (yet).
:::

It's possible to annotate the DocString with the type of content it contains. You specify the content type after the
triple quote, as follows:

```gherkin
Given a blog post named "Random" with Markdown body
  """markdown
  Some Title, Eh?
  ===============
  Here is the first paragraph of my blog post. Lorem ipsum dolor sit amet,
  consectetur adipiscing elit.
  """
```

:::warning[Tool support for content types]
Whilst all current versions of Cucumber support content types as the
delimiter, many tools like text editors don't (yet).
:::

### Data Tables

`Data Tables` are handy for passing a list of values to a step definition:

```gherkin
Given the following users exist:
  | name   | email              | twitter         |
  | Aslak  | aslak@cucumber.io  | @aslak_hellesoy |
  | Julien | julien@cucumber.io | @jbpros         |
  | Matt   | matt@cucumber.io   | @mattwynne      |
```
Just like `Doc Strings`, `Data Tables` will be passed to the step definition as the last argument.

#### Table Cell Escaping

If you want to use a newline character in a table cell, you can write this
as `\n`. If you need a `|` as part of the cell, you can escape it as `\|`. And
finally, if you need a `\`, you can escape that with `\\`.

#### Data Table API

Cucumber provides a rich API for manipulating tables from within step definitions.
See the [Data Table API reference](https://github.com/cucumber/cucumber-jvm/tree/main/datatable) reference for
more details.

## Spoken Languages

The language you choose for Gherkin should be the same language your users and
domain experts use when they talk about the domain. Translating between
two languages should be avoided.

This is why Gherkin has been translated to [over 70 languages](/docs/gherkin/languages) .

Here is a Gherkin scenario written in Norwegian:

```gherkin
# language: no
Funksjonalitet: Gjett et ord

  Eksempel: Ordmaker starter et spill
    Når Ordmaker starter et spill
    Så må Ordmaker vente på at Gjetter blir med

  Eksempel: Gjetter blir med
    Gitt at Ordmaker har startet et spill med ordet "bløtt"
    Når Gjetter blir med på Ordmakers spill
    Så må Gjetter gjette et ord på 5 bokstaver
```

A `# language:` header on the first line of a feature file tells Cucumber what
spoken language to use - for example `# language: fr` for French.
If you omit this header, Cucumber will default to English (`en`).

Some Cucumber implementations also let you set the default language in the
configuration, so you don't need to place the `# language` header in every file.



================================================
FILE: docs/gherkin/step-organization.mdx
================================================
---
sidebar_position: 2
---

# Step organization

You can have all of your step definitions in one file, or in multiple files. When you start with your project, all your step definitions will probably be in one file.
As your project grows, you should split your step definitions into meaningful groups in different files.
This will make your project more logical and easier to maintain.

## How Cucumber finds your features and step definitions

Be aware that, regardless of the directory structure employed, Cucumber effectively flattens the `features/` directory tree when running tests.
This means that anything ending in <Term>file-extension</Term> inside the directory in which Cucumber is run is treated as a step definition. In the same directory, Cucumber will search for a `Feature` corresponding to that step definition.
This is either the default case or the location specified with the relevant option.

## Grouping step definitions

Technically it doesn't matter how you name your step definition files, or which step definitions you put in a file.
You *could* have one giant file containing all your step definitions. However, as the project grows, the file can become messy and hard to maintain.
Instead, we recommend creating a separate <Term>steps-file-pattern</Term> file for each domain concept.

A good rule of thumb is to have one file for each major <Term>domain-object</Term>.

For example, in a Curriculum Vitae application, we might have:

<Tabs>
    <Tab lang="java">
        <ul>
            <li>`EmployeeStepDefinitions.java`</li>
            <li>`EducationStepDefinitions.java`</li>
            <li>`ExperienceStepDefinitions.java`</li>
            <li>`AuthenticationStepDefinitions.java`</li>
        </ul>
    </Tab>
    <Tab lang="kotlin">
        <ul>
            <li>`EmployeeStepDefinitions.kt`</li>
            <li>`EducationStepDefinitions.kt`</li>
            <li>`ExperienceStepDefinitions.kt`</li>
            <li>`AuthenticationStepDefinitions.kt`</li>
        </ul>
    </Tab>
    <Tab lang="ruby">
        <ul>
            <li>`employee_steps.rb`</li>
            <li>`education_steps.rb`</li>
            <li>`experience_steps.rb`</li>
            <li>`authentication_steps.rb`</li>
        </ul>
    </Tab>
    <Tab lang="javascript">
        <ul>
            <li>`employee_steps.js`</li>
            <li>`education_steps.js`</li>
            <li>`experience_steps.js`</li>
            <li>`authentication_steps.js`</li>
        </ul>
    </Tab>
    <Tab lang="golang">
        <ul>
            <li>`employee_steps.go`</li>
            <li>`education_steps.go`</li>
            <li>`experience_steps.go`</li>
            <li>`authentication_steps.go`</li>
        </ul>
    </Tab>
</Tabs>

The first three files would define all the `Given`, `When`, and `Then` step definitions related to creating, reading, updating, and deleting the various <Term>types-of-objects</Term>
The last file would define step definitions related to logging in and out, and the different things a certain user is allowed to do in the system.

If you follow this pattern, you also avoid the
[Feature-coupled step definitions](/docs/guides/anti-patterns#feature-coupled-step-definitions) anti-pattern.

Of course, how you group your step definitions is really up to you and your team. They should be grouped in a way that
is meaningful to *your* project.

## Writing step definitions

Don't write step definitions for steps that are not present in one of your scenarios. These might end up as unused
[cruft](https://en.wikipedia.org/wiki/Cruft) that will need to be cleaned up later. Only implement step definitions that
you actually need. You can always refactor your code as your project grows.

## Avoid duplication

Avoid writing similar step definitions, as they can lead to clutter. While documenting your steps helps, making use of
[helper methods](#helper-methods) to abstract them can do wonders.

For example, take the following steps:

```gherkin
Given I go to the home page
Given I check the about page of the website
Given I get the contact details
```

If all of these steps open their respective web pages, you might be writing *redundant steps*. While the underlying code
for these steps could be different, their **behaviour** is essentially the same, i.e. *to open the Home, About or
Contact page*.

As such, you can use abstract helper methods to reduce them into a single step:

```gherkin
Given I go to the {} page
```

And the following step definition:

<Tabs>
    <Tab lang="java">

```java
@Given("I go to the {string} page")
public void i_want_to_open_page(String webpage) {
    webpageFactory.openPage(webpage);
}
```

    </Tab>
    <Tab lang="kotlin">

```kotlin
@Given("I go to the {string} page")
fun `I want to open page`(webpage: String) {
    webpageFactory.openPage(webpage)
}
```

    </Tab>
    <Tab lang="javascript">

```javascript
Given("I go to the {string} page", function (webpage) {
    webpageFactory.openPage(webpage)
}
```

    </Tab>
    <Tab lang="ruby">

```ruby
Given 'I go to the {string} page' do |page|
    open_web_page page
end
```

    </Tab>
    <Tab lang="golang">

```go
s.Step(`^I go to the "([^"]*)" page$`, goToPage)

func goToPage(webpage string) error {
    return webpageFactory.Open(webpage)
}
```

    </Tab>
</Tabs>

Your step definitions are the glue to the actual code (in this example, a factory method to decide which page to open).
They can also be used to hide implementation details by calling several reusable helper methods from one step
definition.

This helps in a number of ways:

* Increased maintainability.
* Increased scalability with reusable steps.
* More understandable tests.

You can handle other behaviours, like *validating a web page, clicking a button, etc.*, the same way.

Also, using [Data Tables](/docs/cucumber/api/#data-tables) for providing inputs to steps helps increase maintainability and understandability.

## Helper methods

Always keep in mind that Cucumber is a DSL wrapper around the programming language whose full expressiveness
remains available to you in the step definition files (*but not in feature files*).
On the other hand, do not lose sight that every step called as such in a step definition file is first parsed by
[Gherkin](/docs/gherkin/) and therefore must conform to the same syntax as used in feature files.

In fact, it is recommended to refactor step definitions into helper methods for greater modularity and reuse.
The method can reside in the same <Term>file-extension</Term> file as the step definition.

This makes your project more understandable for people who join your project at a later date; which also makes your project easier to maintain.



================================================
FILE: docs/guides/10-minute-tutorial.mdx
================================================
---
slug: 10-minute-tutorial
description: "Get started in 10 minutes"
---

# 10-minute tutorial

<Tabs once="java,kotlin,javascript,ruby" />

In this quick tutorial you will learn how to:

* Install Cucumber
* Write your first scenario using the Gherkin syntax
* Write your first step definition in <Term>language</Term>
* Run Cucumber
* Learn the basic workflow of Behaviour-Driven Development (BDD)

We'll use Cucumber to develop a small library that can figure out whether it's
Friday yet.

* A basic understanding of your chosen programming language and its standard tooling
* Some experience using a terminal
* Some experience using a text editor

Before we begin, you'll need the following:

<Content lang="java">
    - [Java SE](https://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.html)
    - A build tool. You can choose between:
    - [Maven](https://maven.apache.org/index.html) - version 3.3.1 or higher
    - [IntelliJ IDEA](https://www.jetbrains.com/idea/) (which will be used in this tutorial)
    - [IntelliJ IDEA Cucumber for Java plugin](https://plugins.jetbrains.com/plugin/7212-cucumber-for-java)
    - [Eclipse](https://www.eclipse.org/) (a good alternative if you don't use IntelliJ IDEA)
    - [Cucumber Eclipse](https://cucumber.github.io/cucumber-eclipse/)
</Content>
<Content lang="kotlin">
    - [Java SE](https://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.html) (Java 9 and higher are not yet supported by Cucumber)
    - [Maven](https://maven.apache.org/index.html) - version 3.3.1 or higher
    - [IntelliJ IDEA](https://www.jetbrains.com/idea/) (which will be used in this tutorial)
    - [IntelliJ IDEA Cucumber for Java plugin](https://plugins.jetbrains.com/plugin/7212-cucumber-for-java)
    - [IntelliJ IDEA Kotlin plugin](https://plugins.jetbrains.com/plugin/6954-kotlin)
    - [Eclipse](https://www.eclipse.org/) (a good alternative if you don't use IntelliJ IDEA)
    - [Cucumber Eclipse](https://cucumber.github.io/cucumber-eclipse/)
    - [Kotlin Eclipse](https://github.com/JetBrains/kotlin-eclipse)
</Content>
<Content lang="javascript">
    - [Node.js](https://nodejs.org/)
    - A text editor

    Open a terminal to verify that Node.js is installed properly:

    ```shell
    node -v
    npm -v
    ```

    Both of these commands should print a version number.
</Content>
<Content lang="ruby">
    - [Ruby](https://www.ruby-lang.org/)
    - [Bundler](https://bundler.io/)
    - A text editor

    Open a terminal to verify that Ruby is installed properly:

    ```shell
    ruby -v
    bundle -v
    ```

    Both of these commands should print a version number.
</Content>

## Create an empty Cucumber project

<Content lang="java,kotlin">
    We'll start by creating a new project directory with the `cucumber-archetype`
    Maven plugin. Open a terminal, go to the directory where you want to create your project,
    and run the following command:

    ```shell
    mvn archetype:generate                     \
    "-DarchetypeGroupId=io.cucumber"           \
    "-DarchetypeArtifactId=cucumber-archetype" \
    "-DarchetypeVersion={{% version "cucumberjvm" %}}"                \
    "-DgroupId=hellocucumber"                  \
    "-DartifactId=hellocucumber"               \
    "-Dpackage=hellocucumber"                  \
    "-Dversion=1.0.0-SNAPSHOT"                 \
    "-DinteractiveMode=false"
    ```

    You should get something like the following result:
    ```shell
    [INFO] Project created from Archetype in dir: [directory where you created the project]/cucumber
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    ```

    Change into the directory that was just created by running the following command:

    ```shell
    cd hellocucumber
    ```

    Open the project in IntelliJ IDEA:

    * **File -> Open... -> (Select the pom.xml)**
    * Select **Open as Project**
</Content>
<Content lang="kotlin">
    To use Kotlin, we need to add it to our project:

    * Add a directory named `kotlin` in your `src/test` directory and mark it as `Test Sources Root`.
    In IntelliJ IDEA, you can do so by right-clicking on the `kotlin` directory and selecting **"Mark Directory as" > "Test Sources Root"**.
    * Create the `hellocucumber` package inside the `kotlin` directory.
    * Create a Kotlin class called `RunCucumberTest` inside the `hellocucumber` package. IntelliJ IDEA might tell you that Kotlin is not configured; click **"Configure"**.
    Your `pom.xml` should now look like this:

    ```xml
    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns="http://maven.apache.org/POM/4.0.0"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>

        <groupId>hellocucumber</groupId>
        <artifactId>hellocucumber</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <packaging>jar</packaging>

        <properties>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <kotlin.version>1.8.10</kotlin.version>
        </properties>

        <dependencyManagement>
            <dependencies>
                <dependency>
                    <groupId>io.cucumber</groupId>
                    <artifactId>cucumber-bom</artifactId>
                    <version>7.11.2</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                <dependency>
                    <groupId>org.junit</groupId>
                    <artifactId>junit-bom</artifactId>
                    <version>5.9.2</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>

        <dependencies>
            <dependency>
                <groupId>io.cucumber</groupId>
                <artifactId>cucumber-java</artifactId>
                <scope>test</scope>
            </dependency>

            <dependency>
                <groupId>io.cucumber</groupId>
                <artifactId>cucumber-junit-platform-engine</artifactId>
                <scope>test</scope>
            </dependency>

            <dependency>
                <groupId>org.junit.platform</groupId>
                <artifactId>junit-platform-suite</artifactId>
                <scope>test</scope>
            </dependency>

            <dependency>
                <groupId>org.junit.jupiter</groupId>
                <artifactId>junit-jupiter</artifactId>
                <scope>test</scope>
            </dependency>
            <dependency>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-stdlib-jdk8</artifactId>
                <version>${kotlin.version}</version>
            </dependency>
            <dependency>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-test</artifactId>
                <version>${kotlin.version}</version>
                <scope>test</scope>
            </dependency>
        </dependencies>

        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-surefire-plugin</artifactId>
                    <version>3.0.0</version>
                </plugin>
                <plugin>
                    <groupId>org.jetbrains.kotlin</groupId>
                    <artifactId>kotlin-maven-plugin</artifactId>
                    <version>${kotlin.version}</version>
                    <executions>
                        <execution>
                            <id>compile</id>
                            <phase>compile</phase>
                            <goals>
                                <goal>compile</goal>
                            </goals>
                        </execution>
                        <execution>
                            <id>test-compile</id>
                            <phase>test-compile</phase>
                            <goals>
                                <goal>test-compile</goal>
                            </goals>
                            <configuration>
                                <sourceDirs>
                                    <source>src/test/java</source>
                                    <source>src/test/kotlin</source>
                                </sourceDirs>
                            </configuration>
                        </execution>
                    </executions>
                    <configuration>
                        <jvmTarget>1.8</jvmTarget>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.11.0</version>
                    <executions>
                        <execution>
                            <id>compile</id>
                            <phase>compile</phase>
                            <goals>
                                <goal>compile</goal>
                            </goals>
                        </execution>
                        <execution>
                            <id>testCompile</id>
                            <phase>test-compile</phase>
                            <goals>
                                <goal>testCompile</goal>
                            </goals>
                        </execution>
                    </executions>
                    <configuration>
                        <encoding>UTF-8</encoding>
                        <source>1.8</source>
                        <target>1.8</target>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </project>
    ```
    * Copy the annotations from the `RunCucumberTest.java` class to the `RunCucumberTest.kt` class.
    If you are using IntelliJ IDEA, it will offer to translate the Java code to Kotlin code. Otherwise, you'll have to write your own.

    Your `RunCucumberTest.kt` class should now look like this:
    ```kotlin
    package hellocucumber

    import io.cucumber.junit.platform.engine.Constants
    import org.junit.platform.suite.api.ConfigurationParameter
    import org.junit.platform.suite.api.IncludeEngines
    import org.junit.platform.suite.api.SelectClasspathResource
    import org.junit.platform.suite.api.Suite

    @Suite
    @IncludeEngines("cucumber")
    @SelectClasspathResource("hellocucumber")
    @ConfigurationParameter(key = Constants.PLUGIN_PROPERTY_NAME, value = "pretty")
    class RunCucumberTest
    ```

    * Now you can delete the `RunCucumberTest.java` class.
    * Create a Kotlin class called `StepDefs` inside the `hellocucumber` package.
    * Copy the import statements from `StepDefinitions.java` to `StepDefs.kt`; you'll need them later.
    * Finally, delete the `StepDefinitions.java` class (or even the `java` directory).
</Content>
<Content lang="javascript">
    We'll start by creating a new directory and an empty Node.js project.

    ```shell
    mkdir hellocucumber
    cd hellocucumber
    npm init --yes
    ```

    Add Cucumber as a development dependency:

    ```shell
    npm install --save-dev @cucumber/cucumber
    ```

    Open `package.json` in a text editor and change the `test` section so it looks like this:

    ```json
    {
        "name": "hellocucumber",
        "version": "1.0.0",
        "description": "",
        "main": "index.js",
        "scripts": {
            "test": "cucumber-js"
        },
        "keywords": [],
        "author": "",
        "license": "ISC",
        "devDependencies": {
            "@cucumber/cucumber": "^{{% version "cucumberjs" %}}"
        }
    }
    ```

    Prepare the file structure:

    ```shell
    mkdir features
    mkdir features/step_definitions
    ```

    Create a file called `cucumber.json` at the root of your project and add the following
    content:

    ```json
    {
        "default": {
            "formatOptions": {
                "snippetInterface": "synchronous"
            }
        }
    }
    ```

    Also, create a file called `features/step_definitions/stepdefs.js` with the
    following content:

    ```javascript
    const assert = require('assert');
    const { Given, When, Then } = require('@cucumber/cucumber');
    ```
</Content>
<Content lang="ruby">
    We'll start by creating a new directory and an empty Ruby project.

    ```shell
    mkdir hellocucumber
    cd hellocucumber
    ```

    Create a `Gemfile` with the following content:

    ```ruby
    source "https://rubygems.org"

    group :test do
        gem 'cucumber', '~> {{% version "cucumberruby" %}}'
        gem 'rspec', '~> {{% version "rspec" %}}'
    end
    ```

    Install Cucumber and prepare the file structure:

    ```shell
    bundle install
    cucumber --init
    ```
</Content>

You now have a small project with Cucumber installed.

## Verify your installation

To make sure everything works together correctly, let's run Cucumber.

<Content lang="java,kotlin">
    ```shell
    mvn test
    ```
</Content>
<Content lang="javascript">
    ```shell
    npm test
    ```
</Content>
<Content lang="ruby">
    ```shell
    cucumber
    ```
</Content>

You should see something like the following:

<Content lang="java,kotlin">
    ```shell
    -------------------------------------------------------
    T E S T S
    -------------------------------------------------------

    Tests run: 0, Failures: 0, Errors: 0, Skipped: 0

    Results :

    Tests run: 0, Failures: 0, Errors: 0, Skipped: 0

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    ```
</Content>
<Content lang="javascript">
    ```shell
    0 scenarios
    0 steps
    0m00.000s
    ```
</Content>
<Content lang="ruby">
    ```shell
    0 scenarios
    0 steps
    0m0.000s
    ```
</Content>

Cucumber's output is telling us that it didn't find anything to run.

## Write a scenario

When we do Behaviour-Driven Development with Cucumber we use *concrete examples*
to specify *what* we want the software to do. Scenarios are written *before*
production code. They start their life as an *executable specification*. As
the production code emerges, scenarios take on a role as *living documentation* and
*automated tests*.

:::tip[Example Mapping]
Try running an [Example Mapping](/docs/bdd/example-mapping) workshop in your team to
design examples together.
:::

In Cucumber, an example is called a [scenario](/docs/gherkin/reference#example).
Scenarios are defined in `.feature` files, which are stored in the
<Content lang="java,kotlin">`src/test/resources/hellocucumber`</Content>
<Content lang="javascript,ruby">`features`</Content>
directory (or a subdirectory).

One concrete example would be that *Sunday isn't Friday*.

Create an empty file called
<Content lang="java,kotlin">`src/test/resources/hellocucumber/is_it_friday_yet.feature`</Content>
<Content lang="javascript,ruby">`features/is_it_friday_yet.feature`</Content>
with the following content:

```gherkin
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"
```

The first line of this file starts with the keyword `Feature:` followed by a name.
It's a good idea to use a name similar to the file name.

The second line is a brief description of the feature. Cucumber does not
execute this line because it's documentation.

The fourth line, `Scenario: Sunday is not Friday` is a
[scenario](../gherkin/reference.md#example), which is a *concrete example* illustrating how
the software should behave.

The last three lines starting with `Given`, `When` and `Then` are the
[steps](../gherkin/reference.md#steps) of our scenario. This is what Cucumber will execute.

## See scenario reported as undefined

Now that we have a scenario, we can ask Cucumber to execute it.

<Content lang="java,kotlin">
    ```shell
    mvn test
    ```
</Content>
<Content lang="javascript">
    ```shell
    npm test
    ```
</Content>
<Content lang="ruby">
    ```shell
    cucumber
    ```
</Content>

Cucumber is telling us we have one `undefined` scenario and three `undefined`
steps. It's also suggesting some snippets of code that we can use to
*define* these steps:

<Content lang="java,kotlin">
```shell
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running hellocucumber.RunCucumberTest

Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
  Given today is Sunday
  When I ask whether it's Friday yet
  Then I should be told "Nope"
[ERROR] Tests run: 1, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 0.15 s <<< FAILURE! - in hellocucumber.RunCucumberTest
[ERROR] Is it Friday yet?.Sunday isn't Friday  Time elapsed: 0.062 s  <<< ERROR!
io.cucumber.junit.platform.engine.UndefinedStepException:
The step 'today is Sunday' and 2 other step(s) are undefined.
You can implement these steps using the snippet(s) below:

@Given("today is Sunday")
public void today_is_sunday() {
    // Write code here that turns the phrase above into concrete actions
    throw new io.cucumber.java.PendingException();
}
@When("I ask whether it's Friday yet")
public void i_ask_whether_it_s_friday_yet() {
    // Write code here that turns the phrase above into concrete actions
    throw new io.cucumber.java.PendingException();
}
@Then("I should be told {string}")
public void i_should_be_told(String string) {
    // Write code here that turns the phrase above into concrete actions
    throw new io.cucumber.java.PendingException();
}
```
</Content>
<Content lang="javascript">
    ```shell
    UUU

    Warnings:

    1) Scenario: Sunday is not Friday # features/is_it_friday_yet.feature:4
       ? Given today is Sunday
           Undefined. Implement with the following snippet:

             Given('today is Sunday', function () {
               // Write code here that turns the phrase above into concrete actions
               return 'pending';
             });

       ? When I ask whether it's Friday yet
           Undefined. Implement with the following snippet:

             When('I ask whether it\'s Friday yet', function () {
               // Write code here that turns the phrase above into concrete actions
               return 'pending';
             });

       ? Then I should be told "Nope"
           Undefined. Implement with the following snippet:

             Then('I should be told {string}', function (string) {
               // Write code here that turns the phrase above into concrete actions
               return 'pending';
             });


    1 scenario (1 undefined)
    3 steps (3 undefined)
    0m00.000s
    ```
</Content>
<Content lang="ruby">
    ```shell
    Feature: Is it Friday yet?
    Everybody wants to know when it's Friday

    Scenario: Sunday is not Friday       # features/is_it_friday_yet.feature:4
      Given today is Sunday              # features/is_it_friday_yet.feature:5
      When I ask whether it's Friday yet # features/is_it_friday_yet.feature:6
      Then I should be told "Nope"       # features/is_it_friday_yet.feature:7

    1 scenario (1 undefined)
    3 steps (3 undefined)
    0m0.052s

    You can implement step definitions for undefined steps with these snippets:

    Given("today is Sunday") do
      pending # Write code here that turns the phrase above into concrete actions
    end

    When("I ask whether it's Friday yet") do
      pending # Write code here that turns the phrase above into concrete actions
    end

    Then("I should be told {string}") do |string|
      pending # Write code here that turns the phrase above into concrete actions
    end
    ```
</Content>

Copy each of the three snippets for the undefined steps and paste them into
<Content lang="java">`src/test/java/hellocucumber/StepDefinitions.java`</Content>
<Content lang="kotlin">`src/test/kotlin/hellocucumber/Stepdefs.kt`</Content>
<Content lang="javascript">`features/step_definitions/stepdefs.js`</Content>
<Content lang="ruby">`features/step_definitions/stepdefs.rb`</Content>.

<Content lang="kotlin">
    Unfortunately, Cucumber does not generate snippets in Kotlin. But fortunately IDEA can convert the Java code to Kotlin code for you. You might need to improve the translated code, to make it more idiomatic.
    You might also need to add the following import statements (if you hadn't already).

    Your `StepDefs.kt` file should now look like this:

    ```kotlin
    package hellocucumber

    import io.cucumber.java.PendingException
    import io.cucumber.java.en.Given
    import io.cucumber.java.en.When
    import io.cucumber.java.en.Then
    import static org.assertj.core.api.Assertions.assertThat;

    class StepDefs {
        @Given("today is Sunday")
        @Throws(Exception::class)
        fun today_is_Sunday() {
            // Write code here that turns the phrase above into concrete actions
            throw PendingException()
        }

        @When("I ask whether it's Friday yet")
        @Throws(Exception::class)
        fun i_ask_whether_it_s_Friday_yet() {
            // Write code here that turns the phrase above into concrete actions
            throw PendingException()
        }

        @Then("I should be told {string}")
        @Throws(Exception::class)
        fun i_should_be_told(arg1: String) {
            // Write code here that turns the phrase above into concrete actions
            throw PendingException()
        }
    }
    ```
</Content>

## See scenario reported as pending

Run Cucumber again. This time the output is a little different:

<Content lang="java">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # StepDefinitions.today_is_Sunday()
          io.cucumber.java.PendingException: TODO: implement me
        at hellocucumber.StepDefinitions.today_is_Sunday(StepDefinitions.java:14)
        at ?.today is Sunday(classpath:hellocucumber/is_it_friday_yet.feature:5)

        When I ask whether it's Friday yet # StepDefinitions.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefinitions.i_should_be_told(String)

    Pending scenarios:
    hellocucumber/is_it_friday_yet.feature:4 # Sunday isn't Friday

    1 Scenarios (1 pending)
    3 Steps (2 skipped, 1 pending)
    0m0.188s

    io.cucumber.java.PendingException: TODO: implement me
        at hellocucumber.StepDefinitions.today_is_Sunday(StepDefinitions.java:13)
        at ?.today is Sunday(classpath:hellocucumber/is_it_friday_yet.feature:5)
    ```
</Content>
<Content lang="kotlin">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # StepDefs.today_is_Sunday()
          io.cucumber.java.PendingException: TODO: implement me
            at hellocucumber.StepDefs.today_is_Sunday(StepDefs.kt:14)
            at ✽.today is Sunday(hellocucumber/is_it_friday_yet.feature:5)

        When I ask whether it's Friday yet # StepDefs.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefs.i_should_be_told(String)

    1 Scenarios (1 pending)
    3 Steps (2 skipped, 1 pending)
    0m0.107s

    io.cucumber.java.PendingException: TODO: implement me
            at hellocucumber.StepDefs.today_is_Sunday(StepDefs.kt:14)
            at ✽.today is Sunday(hellocucumber/is_it_friday_yet.feature:5)

    Tests run: 1, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 0.351 sec
    ```
</Content>
<Content lang="javascript">
    ```shell
    P--

    Warnings:

    1) Scenario: Sunday is not Friday # features/is_it_friday_yet.feature:4
       ? Given today is Sunday # features/step_definitions/stepdefs.js:3
           Pending
       - When I ask whether it's Friday yet # features/step_definitions/stepdefs.js:8
       - Then I should be told "Nope" # features/step_definitions/stepdefs.js:13

    1 Scenario (1 pending)
    3 steps (1 pending, 2 skipped)
    0m00.001s
    ```
</Content>
<Content lang="ruby">
    ```shell
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday is not Friday       # features/is_it_friday_yet.feature:4
        Given today is Sunday              # features/step_definitions/stepdefs.rb:1
          TODO (Cucumber::Pending)
          ./features/step_definitions/stepdefs.rb:2:in `"today is Sunday"'
          features/is_it_friday_yet.feature:5:in `Given today is Sunday'
        When I ask whether it's Friday yet # features/step_definitions/stepdefs.rb:5
        Then I should be told "Nope"       # features/step_definitions/stepdefs.rb:9

    1 scenario (1 pending)
    3 steps (2 skipped, 1 pending)
    0m0.073s
    ```
</Content>

Cucumber found our step definitions and executed them. They are currently marked as
*pending*, which means we need to make them do something useful.

## See scenario reported as failing

The next step is to do what the comments in the step definitions is telling us to do:

> Write code here that turns the phrase above into concrete actions

Try to use the same words in the code as in the steps.

:::tip[Ubiquitous language]
If the words in your steps originated from conversations during an
[Example Mapping](/docs/bdd/example-mapping) session, you're building a
[Ubiquitous Language](https://martinfowler.com/bliki/UbiquitousLanguage.html),
which we believe is a great way to make your production code and tests more understandable and easier to maintain.
:::

Change your step definition code to this:

<Content lang="java">
    ```java
    package hellocucumber;

    import io.cucumber.java.en.Given;
    import io.cucumber.java.en.When;
    import io.cucumber.java.en.Then;
    import static org.assertj.core.api.Assertions.assertThat;

    class IsItFriday {
        static String isItFriday(String today) {
            return null;
        }
    }

    public class StepDefinitions {
        private String today;
        private String actualAnswer;

        @Given("today is Sunday")
        public void today_is_Sunday() {
            today = "Sunday";
        }

        @When("I ask whether it's Friday yet")
        public void i_ask_whether_it_s_Friday_yet() {
            actualAnswer = IsItFriday.isItFriday(today);
        }

        @Then("I should be told {string}")
        public void i_should_be_told(String expectedAnswer) {
            assertThat(actualAnswer).isEqualTo(expectedAnswer);
        }
    }
    ```
</Content>
<Content lang="kotlin">
    ```kotlin
    package hellocucumber

    import io.cucumber.java.en.Then
    import io.cucumber.java.en.Given
    import io.cucumber.java.en.When
    import static org.assertj.core.api.Assertions.assertThat;


    fun isItFriday(today: String) = ""


    class StepDefs {
        private lateinit var today: String
        private lateinit var actualAnswer: String

        @Given("today is Sunday")
        fun today_is_Sunday() {
            today = "Sunday"
        }

        @When("I ask whether it's Friday yet")
        fun i_ask_whether_it_s_Friday_yet() {
            actualAnswer = isItFriday(today)
        }

        @Then("I should be told {string}")
        fun i_should_be_told(expectedAnswer: String) {
            assertThat(actualAnswer).isEqualTo(expectedAnswer)
        }
    }
    ```
</Content>
<Content lang="javascript">
    ```javascript
    const assert = require('assert');
    const { Given, When, Then } = require('@cucumber/cucumber');

    function isItFriday(today) {
      // We'll leave the implementation blank for now
    }

    Given('today is Sunday', function () {
      this.today = 'Sunday';
    });

    When('I ask whether it\'s Friday yet', function () {
      this.actualAnswer = isItFriday(this.today);
    });

    Then('I should be told {string}', function (expectedAnswer) {
      assert.strictEqual(this.actualAnswer, expectedAnswer);
    });
    ```
</Content>
<Content lang="ruby">
    ```ruby
    module FridayStepHelper
      def is_it_friday(day)
      end
    end
    World FridayStepHelper

    Given("today is Sunday") do
      @today = 'Sunday'
    end

    When("I ask whether it's Friday yet") do
      @actual_answer = is_it_friday(@today)
    end

    Then("I should be told {string}") do |expected_answer|
      expect(@actual_answer).to eq(expected_answer)
    end
    ```
</Content>

Run Cucumber again:

<Content lang="java">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # StepDefinitions.today_is_Sunday()
        When I ask whether it's Friday yet # StepDefinitions.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefinitions.i_should_be_told(String)
          org.opentest4j.AssertionFailedError:
          expected: "Nope"
           but was: null
              at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
              at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:77)
              at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
              at java.base/java.lang.reflect.Constructor.newInstanceWithCaller(Constructor.java:499)
              at io.cucumber.skeleton.StepDefinitions.I_have_cukes_in_my_belly(StepDefinitions.java:12)
              at ✽.I have 42 cukes in my belly(classpath:io/cucumber/skeleton/belly.feature:4)


    Failed scenarios:
    hellocucumber/is_it_friday_yet.feature:4 # Sunday isn't Friday

    1 Scenarios (1 failed)
    3 Steps (1 failed, 2 passed)
    0m0.404s
    ```
</Content>
<Content lang="kotlin">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # StepDefs.today_is_Sunday()
        When I ask whether it's Friday yet # StepDefs.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefs.i_should_be_told(String)
          org.opentest4j.AssertionFailedError:
          expected: "Nope"
           but was: null
              at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
              at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:77)
              at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
              at java.base/java.lang.reflect.Constructor.newInstanceWithCaller(Constructor.java:499)
              at io.cucumber.skeleton.StepDefinitions.I_have_cukes_in_my_belly(StepDefinitions.java:12)
              at ✽.I have 42 cukes in my belly(classpath:io/cucumber/skeleton/belly.feature:4)
    ```
</Content>
<Content lang="javascript">
    ```shell
    ..F

    Failures:

    1) Scenario: Sunday is not Friday # features/is_it_friday_yet.feature:4
       ✔ Given today is Sunday # features/step_definitions/stepdefs.js:8
       ✔ When I ask whether it's Friday yet # features/step_definitions/stepdefs.js:12
       ✖ Then I should be told "Nope" # features/step_definitions/stepdefs.js:16
           AssertionError [ERR_ASSERTION]: undefined == 'Nope'
               at World.<anonymous> (/private/tmp/tutorial/hellocucumber/features/step_definitions/stepdefs.js:17:10)

    1 Scenario (1 failed)
    3 steps (1 failed, 2 passed)
    ```
</Content>
<Content lang="ruby">
    ```shell
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday is not Friday       # features/is_it_friday_yet.feature:4
        Given today is Sunday              # features/step_definitions/stepdefs.rb:4
        When I ask whether it's Friday yet # features/step_definitions/stepdefs.rb:8
        Then I should be told "Nope"       # features/step_definitions/stepdefs.rb:12

          expected: "Nope"
               got: nil

          (compared using ==)
           (RSpec::Expectations::ExpectationNotMetError)
          ./features/step_definitions/stepdefs.rb:13:in `"I should be told {string}"'
          features/is_it_friday_yet.feature:7:in `Then I should be told "Nope"'

    Failing Scenarios:
    cucumber features/is_it_friday_yet.feature:4 # Scenario: Sunday is not Friday

    1 scenario (1 failed)
    3 steps (1 failed, 2 passed)
    0m0.092s
    ```
</Content>

That's progress! The first two steps are passing, but the last one is failing.

## See scenario reported as passing

Let's do the minimum we need to make the scenario pass. In this case, that means making our <Term>stepdef-body</Term> return `Nope`:

<Content lang="java">
    ```java
    static String isItFriday(String today) {
        return "Nope";
    }
    ```
</Content>
<Content lang="kotlin">
    ```kotlin
    fun isItFriday(today: String) = "Nope"
    ```
</Content>
<Content lang="javascript">
    ```javascript
    function isItFriday(today) {
        return 'Nope';
    }
    ```
</Content>
<Content lang="ruby">
    ```ruby
    def is_it_friday(day)
      'Nope'
    end
    ```
</Content>

Run Cucumber again:

<Content lang="java">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # StepDefinitions.today_is_Sunday()
        When I ask whether it's Friday yet # StepDefinitions.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefinitions.i_should_be_told(String)

    1 Scenarios (1 passed)
    3 Steps (3 passed)
    0m0.255s
    ```
</Content>
<Content lang="kotlin">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # Stepdefs.today_is_Sunday()
        When I ask whether it's Friday yet # Stepdefs.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # Stepdefs.i_should_be_told(String)

    1 Scenarios (1 passed)
    3 Steps (3 passed)
    0m0.255s
    ```
</Content>
<Content lang="javascript">
    ```shell
    ...

    1 scenario (1 passed)
    3 steps (3 passed)
    0m00.003s
    ```
</Content>
<Content lang="ruby">
    ```shell
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday is not Friday       # features/is_it_friday_yet.feature:4
        Given today is Sunday              # features/step_definitions/stepdefs.rb:5
        When I ask whether it's Friday yet # features/step_definitions/stepdefs.rb:9
        Then I should be told "Nope"       # features/step_definitions/stepdefs.rb:13

    1 scenario (1 passed)
    3 steps (3 passed)
    0m0.066s
    ```
</Content>

Congratulations! You've got your first green Cucumber scenario.

## Add another failing test

The next thing to test for would be that we also get the correct result when it *is* Friday.

Update the `is_it_friday_yet.feature` file:

```gherkin
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"

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

We'll need to add a step definition to set `today` to "Friday":

<Content lang="java">
    ```java
    @Given("today is Friday")
    public void today_is_Friday() {
        today = "Friday";
    }
    ```
</Content>
<Content lang="kotlin">
    ```kotlin
    @Given("today is Friday")
    fun today_is_Friday() {
        today = "Friday"
    }
    ```
</Content>
<Content lang="javascript">
    ```javascript
    Given('today is Friday', function () {
      this.today = 'Friday';
    });
    ```
</Content>
<Content lang="ruby">
    ```ruby
    Given("today is Friday") do
      @today = 'Friday'
    end
    ```
</Content>

When we run this test, it will fail.

<Content lang="java">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # StepDefinitions.today_is_Sunday()
        When I ask whether it's Friday yet # StepDefinitions.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefinitions.i_should_be_told(String)

      Scenario: Friday is Friday           # hellocucumber/is_it_friday_yet.feature:9
        Given today is Friday              # StepDefinitions.today_is_Friday()
        When I ask whether it's Friday yet # StepDefinitions.i_ask_whether_it_s_Friday_yet()
        Then I should be told "TGIF"       # StepDefinitions.i_should_be_told(String)
          org.opentest4j.AssertionFailedError:
            expected: "TGIF"
             but was: "Nope"
                at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
                at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:77)
                at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
                at java.base/java.lang.reflect.Constructor.newInstanceWithCaller(Constructor.java:499)
                at io.cucumber.skeleton.StepDefinitions.I_have_cukes_in_my_belly(StepDefinitions.java:12)
                at ✽.I have 42 cukes in my belly(classpath:io/cucumber/skeleton/belly.feature:4)


    Failed scenarios:
    hellocucumber/is_it_friday_yet.feature:9 # Friday is Friday

    2 Scenarios (1 failed, 1 passed)
    6 Steps (1 failed, 5 passed)
    0m0.085s

    org.opentest4j.AssertionFailedError:
      expected: "TGIF"
       but was: "Nope"
          at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
          at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:77)
          at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
          at java.base/java.lang.reflect.Constructor.newInstanceWithCaller(Constructor.java:499)
          at io.cucumber.skeleton.StepDefinitions.I_have_cukes_in_my_belly(StepDefinitions.java:12)
          at ✽.I have 42 cukes in my belly(classpath:io/cucumber/skeleton/belly.feature:4)
    ```
</Content>
<Content lang="kotlin">
    ```shell
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/isitfriday.feature:4
        Given today is Sunday              # StepDefs.today_is_Sunday()
        When I ask whether it's Friday yet # StepDefs.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefs.i_should_be_told(String)

      Scenario: Friday is Friday           # hellocucumber/isitfriday.feature:9
        Given today is Friday              # StepDefs.today_is_Friday()
        When I ask whether it's Friday yet # StepDefs.i_ask_whether_it_s_Friday_yet()
        Then I should be told "TGIF"       # StepDefs.i_should_be_told(String)
          org.opentest4j.AssertionFailedError:
            expected: "TGIF"
             but was: "Nope"
                at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
                at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:77)
                at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
                at java.base/java.lang.reflect.Constructor.newInstanceWithCaller(Constructor.java:499)
                at io.cucumber.skeleton.StepDefinitions.I_have_cukes_in_my_belly(StepDefinitions.java:12)
                at ✽.I have 42 cukes in my belly(classpath:io/cucumber/skeleton/belly.feature:4)

    Failed scenarios:
    hellocucumber/isitfriday.feature:9 # Friday is Friday

    2 Scenarios (1 failed, 1 passed)
    6 Steps (1 failed, 5 passed)
    0m0.100s

    org.opentest4j.AssertionFailedError:
      expected: "TGIF"
       but was: "Nope"
          at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
          at java.base/jdk.internal.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:77)
          at java.base/jdk.internal.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
          at java.base/java.lang.reflect.Constructor.newInstanceWithCaller(Constructor.java:499)
          at io.cucumber.skeleton.StepDefinitions.I_have_cukes_in_my_belly(StepDefinitions.java:12)
          at ✽.I have 42 cukes in my belly(classpath:io/cucumber/skeleton/belly.feature:4)

    ```
</Content>
<Content lang="javascript">
    ```shell
    .....F

    Failures:

    1) Scenario: Friday is Friday # features/is_it_friday_yet.feature:9
       ✔ Given today is Friday # features/step_definitions/stepdefs.js:8
       ✔ When I ask whether it's Friday yet # features/step_definitions/stepdefs.js:16
       ✖ Then I should be told "TGIF" # features/step_definitions/stepdefs.js:20
           AssertionError [ERR_ASSERTION]: 'Nope' == 'TGIF'
               + expected - actual

               -Nope
               +TGIF

               at World.<anonymous> (/private/tmp/tutorial/hellocucumber/features/step_definitions/stepdefs.js:21:10)

    2 scenarios (1 failed, 1 passed)
    6 steps (1 failed, 5 passed)
    ```
</Content>
<Content lang="ruby">
    ```shell
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # features/is_it_friday_yet.feature:4
        Given today is Sunday              # features/step_definitions/stepdefs.rb:12
        When I ask whether it's Friday yet # features/step_definitions/stepdefs.rb:16
        Then I should be told "Nope"       # features/step_definitions/stepdefs.rb:20

      Scenario: Friday is Friday           # features/is_it_friday_yet.feature:9
        Given today is Friday              # features/step_definitions/stepdefs.rb:8
        When I ask whether it's Friday yet # features/step_definitions/stepdefs.rb:16
        Then I should be told "TGIF"       # features/step_definitions/stepdefs.rb:20

          expected: "TGIF"
               got: "Nope"

          (compared using ==)
           (RSpec::Expectations::ExpectationNotMetError)
          ./features/step_definitions/stepdefs.rb:21:in `"I should be told {string}"'
          features/is_it_friday_yet.feature:12:in `Then I should be told "TGIF"'

    Failing Scenarios:
    cucumber features/is_it_friday_yet.feature:9 # Scenario: Friday is Friday

    2 scenarios (1 failed, 1 passed)
    6 steps (1 failed, 5 passed)
    ```
</Content>

That is because we haven't implemented the logic yet! Let's do that next.

## Make it pass

We should update our statement to actually evaluate whether or not `today` is equal to `"Friday"`.

<Content lang="java">
    ```java
    static String isItFriday(String today) {
        return "Friday".equals(today) ? "TGIF" : "Nope";
    }
    ```
</Content>
<Content lang="kotlin">
    ```kotlin
    fun isItFriday(today: String) = if (today == "Friday") "TGIF" else "Nope"
    ```
</Content>
<Content lang="javascript">
    ```javascript
    function isItFriday(today) {
      if (today === "Friday") {
        return "TGIF";
      } else {
        return "Nope";
      }
    }
    ```
</Content>
<Content lang="ruby">
    ```ruby
    def is_it_friday(day)
      if day == 'Friday'
        'TGIF'
      else
        'Nope'
      end
    end
    ```
</Content>

Run Cucumber again:

<Content lang="java">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # StepDefinitions.today_is_Sunday()
        When I ask whether it's Friday yet # StepDefinitions.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # StepDefinitions.i_should_be_told(String)

      Scenario: Friday is Friday           # hellocucumber/is_it_friday_yet.feature:9
        Given today is Friday              # StepDefinitions.today_is_Friday()
        When I ask whether it's Friday yet # StepDefinitions.i_ask_whether_it_s_Friday_yet()
        Then I should be told "TGIF"       # StepDefinitions.i_should_be_told(String)

    2 Scenarios (2 passed)
    6 Steps (6 passed)
    0m0.255s
    ```
</Content>
<Content lang="kotlin">
    ```shell
    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    Running hellocucumber.RunCucumberTest
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # hellocucumber/is_it_friday_yet.feature:4
        Given today is Sunday              # Stepdefs.today_is_Sunday()
        When I ask whether it's Friday yet # Stepdefs.i_ask_whether_it_s_Friday_yet()
        Then I should be told "Nope"       # Stepdefs.i_should_be_told(String)

      Scenario: Friday is Friday           # hellocucumber/is_it_friday_yet.feature:9
        Given today is Friday              # Stepdefs.today_is_Friday()
        When I ask whether it's Friday yet # Stepdefs.i_ask_whether_it_s_Friday_yet()
        Then I should be told "TGIF"       # Stepdefs.i_should_be_told(String)

    2 Scenarios (2 passed)
    6 Steps (6 passed)
    0m0.255s
    ```
</Content>
<Content lang="javascript">
    ```shell
    ......
    2 scenarios (2 passed)
    6 steps (6 passed)
    0m00.002s
    ```
</Content>
<Content lang="ruby">
    ```shell
    Feature: Is it Friday yet?
      Everybody wants to know when it's Friday

      Scenario: Sunday isn't Friday        # features/is_it_friday_yet.feature:4
        Given today is Sunday              # features/step_definitions/stepdefs.rb:8
        When I ask whether it's Friday yet # features/step_definitions/stepdefs.rb:17
        Then I should be told "Nope"       # features/step_definitions/stepdefs.rb:22

      Scenario: Friday is Friday           # features/is_it_friday_yet.feature:9
        Given today is Friday              # features/step_definitions/stepdefs.rb:12
        When I ask whether it's Friday yet # features/step_definitions/stepdefs.rb:17
        Then I should be told "TGIF"       # features/step_definitions/stepdefs.rb:22

    2 scenarios (2 passed)
    6 steps (6 passed)
    0m0.040s
    ```
</Content>

## Using variables and examples

So, we all know that there are more days in the week than just Sunday and Friday. Let's update our scenario to use variables and evaluate more possibilities. We'll use variables and examples to evaluate Friday, Sunday, and anything else!

Update the `is_it_friday_yet.feature` file. Notice how we go from `Scenario` to `Scenario Outline` when we start using multiple `Examples`.

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

  Scenario Outline: Today is or is not Friday
    Given today is "<day>"
    When I ask whether it's Friday yet
    Then I should be told "<answer>"

  Examples:
    | day            | answer |
    | Friday         | TGIF   |
    | Sunday         | Nope   |
    | anything else! | Nope   |
```

We need to replace the step definitions for `today is Sunday` and `today is Friday` with one step definition that takes the value of `<day>` as a String.
Update the step definitions as follows:

<Content lang="java">
```java
package hellocucumber;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.When;
import io.cucumber.java.en.Then;
import static org.assertj.core.api.Assertions.assertThat;

class IsItFriday {
    static String isItFriday(String today) {
        return "Friday".equals(today) ? "TGIF" : "Nope";
    }
}

public class Stepdefs {
    private String today;
    private String actualAnswer;

    @Given("today is {string}")
    public void today_is(String today) {
        this.today = today;
    }

    @When("I ask whether it's Friday yet")
    public void i_ask_whether_it_s_Friday_yet() {
        actualAnswer = IsItFriday.isItFriday(today);
    }

    @Then("I should be told {string}")
    public void i_should_be_told(String expectedAnswer) {
        assertThat(actualAnswer).isEqualTo(expectedAnswer);
    }
}
```
</Content>
<Content lang="kotlin">
```kotlin
package hellocucumber

import io.cucumber.java.en.Then
import io.cucumber.java.en.Given
import io.cucumber.java.en.When
import static org.assertj.core.api.Assertions.assertThat

fun isItFriday(today: String) = if (today == "Friday") "TGIF" else "Nope"


class StepDefs {
    private lateinit var today: String
    private lateinit var actualAnswer: String

    @Given("today is {string}")
    fun today_is(today: String) {
        this.today = today
    }

    @When("I ask whether it's Friday yet")
    fun i_ask_whether_it_s_Friday_yet() {
        actualAnswer = isItFriday(today)
    }

    @Then("I should be told {string}")
    fun i_should_be_told(expectedAnswer: String) {
        assertThat(actualAnswer).isEqualTo(expectedAnswer)
    }
}
```
</Content>
<Content lang="javascript">
```javascript
const assert = require('assert');
const { Given, When, Then } = require('@cucumber/cucumber');

function isItFriday(today) {
  if (today === "Friday") {
    return "TGIF";
  } else {
    return "Nope";
  }
}

Given('today is {string}', function (givenDay) {
  this.today = givenDay;
});

When('I ask whether it\'s Friday yet', function () {
  this.actualAnswer = isItFriday(this.today);
});

Then('I should be told {string}', function (expectedAnswer) {
  assert.strictEqual(this.actualAnswer, expectedAnswer);
});
```
</Content>
<Content lang="ruby">
```ruby
module FridayStepHelper
  def is_it_friday(day)
    if day == 'Friday'
      'TGIF'
    else
      'Nope'
    end
  end
end

World FridayStepHelper

Given("today is {string}") do |given_day|
  @today = given_day
end

When("I ask whether it's Friday yet") do
  @actual_answer = is_it_friday(@today)
end

Then("I should be told {string}") do |expected_answer|
  expect(@actual_answer).to eq(expected_answer)
end
```
</Content>

Run Cucumber again:

<Content lang="java,kotlin">
```shell
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running hellocucumber.RunCucumberTest
Feature: Is it Friday yet?
  Everybody wants to know when it's Friday

  Scenario Outline: Today is or is not Friday # hellocucumber/is_it_friday_yet.feature:4
    Given today is "<day>"
    When I ask whether it's Friday yet
    Then I should be told "<answer>"

    Examples:

  Scenario Outline: Today is or is not Friday # hellocucumber/is_it_friday_yet.feature:11
    Given today is "Friday"                   # StepDefinitions.today_is(String)
    When I ask whether it's Friday yet        # StepDefinitions.i_ask_whether_it_s_Friday_yet()
    Then I should be told "TGIF"              # StepDefinitions.i_should_be_told(String)

  Scenario Outline: Today is or is not Friday # hellocucumber/is_it_friday_yet.feature:12
    Given today is "Sunday"                   # StepDefinitions.today_is(String)
    When I ask whether it's Friday yet        # StepDefinitions.i_ask_whether_it_s_Friday_yet()
    Then I should be told "Nope"              # StepDefinitions.i_should_be_told(String)

  Scenario Outline: Today is or is not Friday # hellocucumber/is_it_friday_yet.feature:13
    Given today is "anything else!"           # StepDefinitions.today_is(String)
    When I ask whether it's Friday yet        # StepDefinitions.i_ask_whether_it_s_Friday_yet()
    Then I should be told "Nope"              # StepDefinitions.i_should_be_told(String)

3 Scenarios (3 passed)
9 Steps (9 passed)
0m0.255s
```
</Content>
<Content lang="javascript">
```shell
.........

3 scenarios (3 passed)
9 steps (9 passed)
0m00.001s
```
</Content>
<Content lang="ruby">
```shell
Feature: Is it Friday yet?
  Everybody wants to know when it's Friday

  Scenario Outline: Today is or is not Friday # features/is_it_friday_yet.feature:4
    Given today is <day>                      # features/is_it_friday_yet.feature:5
    When I ask whether it's Friday yet        # features/is_it_friday_yet.feature:6
    Then I should be told <answer>            # features/is_it_friday_yet.feature:7

    Examples:
      | day              | answer |
      | "Friday"         | "TGIF" |
      | "Sunday"         | "Nope" |
      | "anything else!" | "Nope" |

3 scenarios (3 passed)
9 steps (9 passed)
0m0.021s
```
</Content>

## Refactoring

Now that we have working code, we should do some refactoring:

* We should move the `isItFriday` <Term>stepdef-body</Term> out from the test code into production code.
* We could at some point extract helper methods from our step definition, for <Term>stepdef-body</Term>s we use in several places.

## Summary

In this brief tutorial you've seen how to install Cucumber, how to follow
the BDD process to develop a <Term>stepdef-body</Term>, and how to use that <Term>stepdef-body</Term> to evaluate multiple scenarios!



================================================
FILE: docs/guides/_category_.json
================================================
{
  "position": 1,
  "label": "Guides"
}



================================================
FILE: docs/guides/anti-patterns.mdx
================================================
---
description: "Avoid common mistakes and pitfalls"
---

# Anti-patterns

There are several anti-patterns, which we will describe here. We will also give you hints on how to avoid them!

## Feature-coupled step definitions

Feature-coupled step definitions are step definitions that **can't be reused** across features or scenarios.

This may lead to an explosion of step definitions, code duplication, and high maintenance costs.

### Example

An imaginary résumé application could have the following feature and step definition files:

<Tabs>
    <Tab lang="java">
```java
features/
+--edit_work_experience.feature
+--edit_languages.feature
+--edit_education.feature
+--steps/
   +--edit_work_experience_steps.java
   +--edit_languages_steps.java
   +--edit_education_steps.java
```
    </Tab>
    <Tab lang="kotlin">
```kotlin
features/
+--edit_work_experience.feature
+--edit_languages.feature
+--edit_education.feature
+--steps/
   +--edit_work_experience_steps.kt
   +--edit_languages_steps.kt
   +--edit_education_steps.kt
```
    </Tab>
    <Tab lang="javascript">
```javascript
features/
+--edit_work_experience.feature
+--edit_languages.feature
+--edit_education.feature
+--steps/
   +--edit_work_experience_steps.js
   +--edit_languages_steps.js
   +--edit_education_steps.js
```
    </Tab>
    <Tab lang="ruby">
```ruby
features/
+--edit_work_experience.feature
+--edit_languages.feature
+--edit_education.feature
+--steps/
   +--edit_work_experience_steps.rb
   +--edit_languages_steps.rb
   +--edit_education_steps.rb
```
    </Tab>
</Tabs>

The `edit_work_experience.feature` could have the following scenario:

```gherkin
Scenario: add description
  Given I have a CV and I'm on the edit description page
  And I fill in "Description" with "Cucumber BDD tool"
  When I press "Save"
  Then I should see "Cucumber BDD tool" under "Descriptions"
```

<Tabs>
    <Tab lang="java">
`edit_work_experience_steps.java` could be implemented like this:

```java
    @Given("I have a CV and I'm on the edit description page")
    public void I_have_a_CV_and_Im_on_the_edit_description_page() {
        Employee employee = new Employee("Sally");
        employee.createCV();
    }
```
    </Tab>
    <Tab lang="kotlin">
`edit_work_experience_steps.kt` could be implemented like this:

```kotlin
@Given("I have a CV and I'm on the edit description page")
fun I_have_a_CV_and_Im_on_the_edit_description_page() {
    val employee = Employee("Sally")
    employee.createCV()
}
```
    </Tab>
    <Tab lang="javascript">
`edit_work_experience_steps.js` could be implemented like this:

```javascript
var { Given } = require('cucumber');

Given(/^I have a CV and I'm on the edit description page$/, function () {
  this.employee = new Employee('Sally');
  this.employee.createCV();
});
```
    </Tab>
    <Tab lang="ruby">
`edit_work_experience_steps.rb` could be implemented like this:

```ruby
Given /I have a CV and I'm on the edit description page/ do
  @employee = Employee.create!(name: 'Sally')
  @employee.create_cv
  visits("/employees/#{@employee.id}/descriptions/new")
end
```
    </Tab>
</Tabs>

### How to decouple steps & step definitions

* Organise your steps by domain concept.
* Use domain-related names (rather than feature- or scenario-related names) for your step & step definition files.

## Conjunction steps

From the online Merriam-Webster dictionary:

> **con·junc·tion**: an uninflected linguistic form that joins together sentences, clauses, phrases, or words.

Don't use steps that combine a bunch of different things. This makes steps too specialised, and hard to reuse.
Cucumber has built-in support for conjunctions (`And`, `But`) for a reason!

**Example**

```gherkin
Given I have shades and a brand new Mustang
```

### How to split conjunction steps

```gherkin
Given I have shades
And I have a brand new Mustang
```

### Support for conjunction steps

Sometimes you may want to combine several steps into one, to make your scenarios easier to read.
For instance, if you need to set up several preconditions in your `Given` state.

:::warning[Support in Cucumber-Ruby]
While it is possible to call steps from step definitions in Cucumber-Ruby, this is not recommended.
:::

The best way to achieve composition and reuse, is to use the features of your programming language. If you want to combine
several actions into one step, extract individual (helper) methods and call these methods from your step definition.

You want to strive to keep your steps atomic as much as possible.

## More information

For more information on anti-patterns, see [Cucumber Anti-Patterns (blog post)](http://www.thinkcode.se/blog/2016/06/22/cucumber-antipatterns).



================================================
FILE: docs/guides/api-automation.md
================================================
---
description: "RestAssured, Karate and more"
---

# API automation

Cucumber is not an API automation tool, but it works well with other API automation tools.

Using API's for your automation, can make your tests faster and less flaky than going through the UI.
In general, API's change less frequently than the UI; keeping your automation up to date for longer.

## For JVM

- [RestAssured](http://rest-assured.io/) is an API automation tool for Java. You can use RestAssured in your step definitions to make API calls and verify responses.

## For JavaScript

- [PactumJS](https://pactumjs.github.io/) is a REST API Testing Tool for all levels in a Test Pyramid. For more information see the [official docs](https://pactumjs.github.io/) and [boilerplate code](https://github.com/pactumjs/pactum-cucumber-boilerplate).

## For Ruby

- [HTTParty](https://github.com/jnunemaker/httparty) can be used to make HTTP calls. For more information, see the [HTTParty docs](https://github.com/jnunemaker/httparty/tree/master/docs).
- [Net::HTTP](https://docs.ruby-lang.org/en/2.0.0/Net/HTTP.html) is an HTTP client API for Ruby.
- [Faraday](https://github.com/lostisland/faraday) is a HTTP client library for Ruby.
- [RubyMine](https://www.jetbrains.com/help/ruby/meet-rubymine.html) is a Ruby and Rails IDE providing a range of developer tools for Ruby. RubyMine can be used to [test RESTful Web Services](https://www.jetbrains.com/help/ruby/testing-restful-web-services.html).
- [curb](https://rubygems.org/gems/curb) provides Ruby-language bindings for the libcurl(3), a fully-featured client-side URL transfer library.
- [Typhoeus](https://github.com/typhoeus/typhoeus) is a Ruby tool that wraps libcurl in order to make fast and reliable requests. For more information, see the [Typhoeus Ruby docs](https://www.rubydoc.info/github/typhoeus/typhoeus).



================================================
FILE: docs/guides/browser-automation.mdx
================================================
---
description: "Selenium WebDriver, Capybara and more"
---

# Browser automation

Cucumber is not a browser automation tool, but it works well with the following browser automation tools.

## Selenium WebDriver

WebDriver is designed to provide a simpler, more concise programming interface than some other tools. Selenium WebDriver better supports dynamic web pages where elements of a page may change without the page itself being reloaded. WebDriver's goal is to supply a well-designed object-oriented API that provides improved support for modern advanced web-app testing problems.

[Selenium-WebDriver](https://www.selenium.dev/documentation/webdriver/) can be used in multiple programming languages, including Java, JavaScript, Ruby and Kotlin.

Let us look at an example of Cucumber using Selenium WebDriver in UI testing, by converting the [Selenium WebDriver Getting Started](https://www.selenium.dev/documentation/webdriver/getting_started/).

We can express the example as the following scenario:

```gherkin
Scenario: Finding some cheese
   Given I am on the Google search page
   When I search for "Cheese!"
   Then the page title should start with "cheese"
```

<Tabs>
    <Tab lang="java">
```java
package com.example;

import io.cucumber.java.After;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.support.ui.ExpectedCondition;
import org.openqa.selenium.support.ui.WebDriverWait;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;

public class ExampleSteps {

    private final WebDriver driver = new FirefoxDriver();

    @Given("I am on the Google search page")
    public void I_visit_google() {
        driver.get("https://www.google.com");
    }

    @When("I search for {string}")
    public void search_for(String query) {
        WebElement element = driver.findElement(By.name("q"));
        // Enter something to search for
        element.sendKeys(query);
        // Now submit the form. WebDriver will find the form for us from the element
        element.submit();
   }

   @Then("the page title should start with {string}")
   public void checkTitle(String titleStartsWith) {
       // Google's search is rendered dynamically with JavaScript
       // Wait for the page to load timeout after ten seconds
       new WebDriverWait(driver,10L).until(new ExpectedCondition<Boolean>() {
           public Boolean apply(WebDriver d) {
               return d.getTitle().toLowerCase().startsWith(titleStartsWith);
           }
       });
   }

   @After()
   public void closeBrowser() {
       driver.quit();
   }
}
```
    </Tab>
    <Tab lang="kotlin">
```kotlin
package com.example

import io.cucumber.java8.Scenario
import io.cucumber.java8.En
import org.openqa.selenium.By
import org.openqa.selenium.WebDriver
import org.openqa.selenium.WebElement
import org.openqa.selenium.support.ui.WebDriverWait

class ExampleSteps: En {

    lateinit var driver: WebDriver

    init {
        Given("I am on the Google search page") {
            driver.get("https:\\www.google.com")
        }

        When("I search for {string}") { query: String ->
            val element: WebElement = driver.findElement(By.name("q"))
            // Enter something to search for
            element.sendKeys(query)
            // Now submit the form. WebDriver will find the form for us from the element
            element.submit()
        }

        Then("the page title should start with {string}") { titleStartsWith: String ->
            // Google's search is rendered dynamically with JavaScript
            // Wait for the page to load timeout after ten seconds
            WebDriverWait(driver, 10L).until { d ->
                d.title.toLowerCase().startsWith(titleStartsWith)
            }
        }

        After { scenario: Scenario ->
            driver.quit()
        }
    }
}
```
    </Tab>
    <Tab lang="javascript">
```javascript
const { Given, When, Then, AfterAll } = require('cucumber');
const { Builder, By, Capabilities, Key } = require('selenium-webdriver');
const { expect } = require('chai');

require("chromedriver");

// driver setup
const capabilities = Capabilities.chrome();
capabilities.set('chromeOptions', { "w3c": false });
const driver = new Builder().withCapabilities(capabilities).build();

Given('I am on the Google search page', async function () {
    await driver.get('http://www.google.com');
});

When('I search for {string}', async function (searchTerm) {
    const element = await driver.findElement(By.name('q'));
    element.sendKeys(searchTerm, Key.RETURN);
    element.submit();
});

Then('the page title should start with {string}', {timeout: 60 * 1000}, async function (searchTerm) {
    const title = await driver.getTitle();
    const isTitleStartWithCheese = title.toLowerCase().lastIndexOf(`${searchTerm}`, 0) === 0;
    expect(isTitleStartWithCheese).to.equal(true);
});

AfterAll(async function(){
    await driver.quit();
});
```
    </Tab>
    <Tab lang="ruby">
```ruby
require 'rubygems'
require 'selenium-webdriver'

Given(/^I am on the Google search page$/) do
  driver = Selenium::WebDriver.for :firefox
  driver.get "http://google.com"
end

When(/^I search for "([^"]*)"$/) do
  element = driver.find_element(name: "q")
  element.send_keys "Cheese!"
  element.submit
end

Then(/^the page title should start with "([^"]*)"$/) do
  wait = Selenium::WebDriver::Wait.new(timeout: 10)
  wait.until { driver.title.downcase.start_with? "cheese!" }
  puts "Page title is #{driver.title}"
    browser.close
end
```
    </Tab>
</Tabs>

More information on [Selenium Webdriver](http://docs.seleniumhq.org/projects/webdriver/).

## Other tools

### Serenity BDD

Serenity BDD is an open source reporting library for the **JVM** that helps you write better
structured, more maintainable automated acceptance criteria. Serenity also produces
rich meaningful test reports (or "living documentation") that report not only the
test results, but also which features have been tested.

A detailed tutorial on using Cucumber-JVM with Serenity can be found
[here](https://serenity-bdd.info/docs/articles/an-introduction-to-serenity-bdd-with-cucumber.html), and more information on Serenity can be found on their [official website](http://serenity-bdd.info).

### Watir

Watir (pronounced _water_), is an open-source (BSD), family of **Ruby** libraries for automating web browsers. It allows you to write tests that are easier to read and maintain. It is straightforward and flexible.

Watir drives browsers the same way people do. It clicks links, fills in forms, presses buttons. Watir also checks results, such as whether expected text appears on the page.

Watir is a family of Ruby libraries but it supports your application no matter which technology it is developed in. While Watir supports only Internet Explorer on Windows; Watir-WebDriver solves single browser testing and support Chrome, Firefox, Internet Explorer, Opera and also running in headless mode (HTMLUnit).

Now let's jump in to a sample UI testing program using Watir:

```ruby
require "rubygems"
require "rspec"
require "watir"

describe "google.com" do
  let(:browser) { @browser ||= Watir::Browser.new :firefox }
  before { browser.goto "http://google.com" }
  browser.text_field(name: "q").set "watir"
  browser.button.click
  browser.div(id: "resultStats").wait_until
  browser.title.should == "watir - Google Search"
  after { browser.close }
end
```

Now let us incorporate Cucumber to this test:

```gherkin
Feature: Search In order to use Google users must be able to search for content
  Scenario: Search for a term
    Given I have entered "watir" into the query
    When I click "search"
    Then I should see some results
```

```ruby
require "watir"
require "rspec/expectations"

Given(/^I have entered "([^"]*)" into the query$/) do |term|
  @browser ||= Watir::Browser.new :firefox
  @browser.goto "google.com"
  @browser.text_field(name: "q").set term
end

When(/^I click "([^"]*)"$/) do
 @browser.button.click
end

Then(/^I should see some results$/) do
  @browser.div(id: "resultStats").wait_until_present
  @browser.close
end
```
More information on [Watir](http://watir.com).

### Capybara

Cucumber-Rails is pre-configured with support for view integration testing using [Capybara](https://github.com/jnicklas/capybara)
(`script/generate cucumber --capybara`).

Unless instructed otherwise the Cucumber-Rails install generator will set up the necessary support files for Capybara.

While Capybara is the preferred testing method for HTML views in cucumber-rails it does not play well with Rails' own
built-in `MiniTest/Test::Unit`. In particular, whenever Capybara is required into a Cucumber World then the `response.body`
method of `Rails Test::Unit` is removed. Capybara depends upon Nokogiri and Nokogiri prefers to use XML rather than CSS tags.
This behaviour can be overridden in `./features/support/env.rb`.

More information on [Capybara](https://teamcapybara.github.io/capybara/).

## Tips and tricks

### Screenshot on failure

Taking a screenshot when a scenario fails, might help you to figure out what went wrong.
To take a screenshot on failure, you can configure an [`After` hook](../cucumber/api.mdx#after).

<Tabs>
    <Tab lang="java">
With [WebDriver](https://www.selenium.dev/documentation/webdriver/browser/windows/#takescreenshot):

```java
if (scenario.isFailed()) {
    byte[] screenshot = ((TakesScreenshot) webDriver).getScreenshotAs(OutputType.BYTES);
    scenario.attach(screenshot, "image/png", "name");
}
```
    </Tab>
    <Tab lang="kotlin">
With [WebDriver](https://www.selenium.dev/documentation/webdriver/browser/windows/#takescreenshot):

```kotlin
if (scenario.isFailed()) {
    val screenshot = ((TakesScreenshot) webDriver).getScreenshotAs(OutputType.BYTES)
    scenario.attach(screenshot, "image/png", "name")
}
```
    </Tab>
    <Tab lang="javascript">
With [WebDriver](https://www.selenium.dev/documentation/webdriver/browser/windows/#takescreenshot):

```javascript
After(async function (scenario) {
    if (scenario.result.status === Status.FAILED) {
        return webDriver.takeScreenshot().then((screenShot, error) => {
            if (!error) {
                this.attach(screenShot, "image/png");
            }
        });
    }
});
```
    </Tab>
    <Tab lang="ruby">
With Capybara:

```ruby
# Available scenario methods: #failed?, #passed?, and #exception
if scenario.failed?
  path = "html-report/#{scenario.__id__}.html"
  page.driver.browser.save_screenshot(path)
  attach(path, "image/png")
end
```
    </Tab>
</Tabs>

### Multiple browsers

Cucumber can run your scenarios with different browsers, based on a configuration property loaded at runtime:

<Tabs>
    <Tab lang="java,kotlin">
```java
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class WebDriverFactory {
    public static WebDriver createWebDriver() {
        String webdriver = System.getProperty("browser", "firefox");
        switch(webdriver) {
            case "firefox":
                return new FirefoxDriver();
            case "chrome":
                return new ChromeDriver();
            default:
                throw new RuntimeException("Unsupported webdriver: " + webdriver);
        }
    }
}
```

Then, define the `browser` property when you run Cucumber:

```shell
mvn test -Dbrowser=chrome
```

If you are using Serenity, pass the `driver` system property (no extra coding required):

```shell
mvn test -Ddriver=chrome
```
    </Tab>
    <Tab lang="ruby">
```ruby
Capybara.register_driver :selenium do |app|
  browser = (ENV['browser'] || 'firefox').to_sym
  Capybara::Selenium::Driver.new(app, browser: browser)
end
```

Then, define the `browser` property when you run Cucumber:

```shell
browser=chrome cucumber
```
    </Tab>
</Tabs>


================================================
FILE: docs/guides/continuous-integration.md
================================================
---
description: "Running Cucumber on a build server"
---

# Continuous Integration

Using Cucumber in a [Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html) (CI) environment is relatively straightforward.

The `cucumber` executable will exit with an [exit status](https://en.wikipedia.org/wiki/Exit_status)
different from `0` if one or more scenarios are failing. This is all your CI
server needs to know.

First, you have to make sure your CI server executes Cucumber.
Most CI setups invoke some kind of build tool. Common build tools are:

* [Rake](https://github.com/ruby/rake)
* [Ant](https://ant.apache.org)
* [Maven](https://maven.apache.org)

We recommend executing Cucumber from one of these on a CI server.

## Rake

If your CI server is using [Rake](/docs/tools/ruby#rake), make sure
that Rake executes your Cucumber task.

## JUnit output

Many CI servers can interpret XML files produced by the [Ant JUnit task](https://ant.apache.org/manual/Tasks/junit.html)
and display them as HTML. Some can even create reports over time.

If you're using such a CI server, we recommend you use Cucumber with the `JUnit` formatter.

> To get started using Cucumber in [Jenkins](https://jenkins.io/), add a build step running
> `cucumber -f junit --out WORKSPACE` and then check the
> 'Publish JUnit test result report', and enter `\*.xml` in the 'Test report XMLs' field.
> Save and run. (Later improve by using a Rake task and placing your output in a subfolder).

If you're using [Ant](https://ant.apache.org/), you can run Cucumber with the [`exec`](https://ant.apache.org/manual/Tasks/exec.html) task.

## Jenkins

A Jenkins plugin is available that produces beautiful Cucumber reports.

Follow the install instructions for [Cucumber Reports plugin](https://github.com/jenkinsci/cucumber-reports-plugin).

Overview Page:

![jenkins Cucumber report](https://github.com/masterthought/jenkins-cucumber-jvm-reports-plugin-java/raw/master/.README/feature-overview.png)

Report Page:

![jenkins Cucumber report](https://github.com/masterthought/jenkins-cucumber-jvm-reports-plugin-java/raw/master/.README/feature-passed.png)



================================================
FILE: docs/guides/index.mdx
================================================
import DocCardList from '@theme/DocCardList';

# Guides

<DocCardList />


================================================
FILE: docs/guides/parallel-execution.mdx
================================================
---
description: "Using multiple threads to reduce test times"
---

# Parallel execution

<Tabs once="java,kotlin" />

:::info[JVM only]
This page is only applicable to the JVM implementation of Cucumber.
:::

Cucumber-JVM allows parallel execution across multiple threads since version 4.0.0.

There are several options to incorporate this built-in feature in a Cucumber project. You can do so using:

- [JUnit 5](#junit-5)
- [JUnit 4](#junit-4)
- [TestNG](#testng)
- [CLI](#cli)

For each of these options, this tutorial will look at the project setup, configuration settings and execution commands.

## JUnit 5

Cucumber Scenarios can be executed in parallel using the **JUnit Platform**.

See the [cucumber-junit-platform-engine documentation](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine) for details.

## JUnit 4

Cucumber can be executed in parallel using **JUnit and Maven test execution plugins**. In JUnit the **feature files are run in parallel rather than scenarios**, which means **all the scenarios in a feature file will be executed by the same thread**. You can use either Maven Surefire or Failsafe plugin to execute the runners.

- Create a Maven project in your favorite IDE using the [cucumber-archetype](/docs/guides/10-minute-tutorial/#create-an-empty-cucumber-project) or by adding Cucumber dependencies to the POM as detailed [here](../installation/java.md#maven) and Junit dependencies [here](../cucumber/checking-assertions.md#junit).
- Create a **parallel** folder (or any other name) in `src/test/resources` path and add the two feature files (`scenarios.feature` and `scenario-outlines.feature`) inside it.

```gherkin
Feature: Scenarios feature file

  Scenario: Scenario Number One
    Given Step from 'Scenario 1' in 'scenarios' feature file

  Scenario: Scenario Number Two
    Given Step from 'Scenario 2' in 'scenarios' feature file
```

```gherkin
Feature: Scenario Outlines feature file

  Scenario Outline: <scen_out_row_num>
    Given Step from '<scen_out_row_num>' in 'scenario-outlines' feature file

    Examples: 
      | scen_out_row_num       |
      | Scenario Outline Row 1 |
      | Scenario Outline Row 2 |
```

<Content lang="java">
	- Add the **step definition class** to the `parallel` package (same name as folder above for automatic pickup by runner) in `src/test/java` folder.

	```java
	package parallel;

	import io.cucumber.java.BeforeStep;
	import io.cucumber.java.en.Given;

	public class StepDefinitions {

		@Given("Step from {string} in {string} feature file")
		public void step(String scenario, String file) {
			System.out.format("Thread ID - %2d - %s from %s feature file.\n",
			Thread.currentThread().getId(), scenario,file);
		}
	}
	```
</Content>
<Content lang="kotlin">
	- Add the **step definition class** to the `parallel` package (same name as folder above for automatic pickup by runner) in `src/test/kotlin` folder.

	```kotlin
	package parallel

	import io.cucumber.java8.En

	class StepDefs : En {	
		init {
			Given("Step from {string} in {string} feature file") { scenario: String , file: String ->
				println("Thread ID - ${Thread.currentThread().id} - $scenario from $file feature file")
			}
		}
	}
	```
</Content>

<Content lang="java">
	- Add a cucumber **runner** using the `RunWith` annotation in the `parallel` package (same name as step definition package) in the `src/test/java` folder.
</Content>
<Content lang="kotlin">
	- Add a cucumber **runner** using the `RunWith` annotation in the `parallel` package (same name as step definition package) in the `src/test/kotlin` folder.
</Content>

<Content lang="java">
	```java
	package parallel;

	import io.cucumber.junit.Cucumber;
	import org.junit.runner.RunWith;

	@RunWith(Cucumber.class)
	public class RunCucumberTest {
	}
	```
</Content>
<Content lang="kotlin">
```kotlin
package parallel

import io.cucumber.junit.Cucumber
import org.junit.runner.RunWith

@RunWith(Cucumber::class)
class RunCucumberTest
```
</Content>

- Add the **Surefire plugin configuration** to the `build` section to the `POM`.

```shell
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-surefire-plugin</artifactId>
	<version>2.22.0</version>
	<configuration>
		<parallel>methods</parallel>
		<useUnlimitedThreads>true</useUnlimitedThreads>
	</configuration>
</plugin>
```

- Use the Maven `install` or a suitable command to **execute** the `POM`. This should run in parallel threaded mode. You should see a result similar to below. It is important to note that **both the scenarios in the file (`scenarios.feature`) are executed by thread with ID 14**. Similarly **both the rows of the scenario outline in the file (`scenario-outlines.feature`) are executed by thread with ID 13**.

```shell
Thread ID - 13 - Scenario Outline Row 1 from scenario-outlines feature file.
Thread ID - 13 - Scenario Outline Row 2 from scenario-outlines feature file.
Thread ID - 14 - Scenario 1 from scenarios feature file.
Thread ID - 14 - Scenario 2 from scenarios feature file.
```

- To execute using a Maven **Failsafe plugin include the below configuration** in the `build` section to the `POM`. Rename the runner class to `RunCucumberIT`.

<Content lang="kotlin">
:::note
For Failsafe to find your step definitions, make sure they are in src/test/**java**.
:::
</Content>

```shell
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-failsafe-plugin</artifactId>
	<version>2.22.0</version>
	<executions>
		<execution>
			<goals>
				<goal>integration-test</goal>
				<goal>verify</goal>
			</goals>
			<configuration>
				<parallel>methods</parallel>
				<useUnlimitedThreads>true</useUnlimitedThreads>
			</configuration>
		</execution>
	</executions>
</plugin>
```

To set the thread count to a **specific number** instead of `useUnlimitedThreads` use the below setting.
```shell
<configuration>
	<parallel>methods</parallel>
	<threadCount>4</threadCount>
</configuration>
```

The thread count in the above setting is **4 threads per core**. If you want this to be **4 threads across all cores** set the `perCoreThreadCount` to **false**.
```shell
<configuration>
	<parallel>methods</parallel>
	<threadCount>4</threadCount>
	<perCoreThreadCount>false</perCoreThreadCount>
</configuration>
```

In case of **multiple runners** one can also set the parallel option to `classesAndMethods` or `classes` in addition to `methods`.
```shell
<configuration>
	<parallel>classesAndMethods</parallel>
	useUnlimitedThreads>true</useUnlimitedThreads>
</configuration>
```

## TestNG

Cucumber can be executed in parallel using **TestNG and Maven test execution plugins** by setting the **dataprovider parallel option to true**. In TestNG the **scenarios and rows in a scenario outline are executed in multiple threads**. One can use either Maven Surefire or Failsafe plugin for executing the runners.

- Create a Maven project in your favorite IDE adding Cucumber dependencies to the POM as detailed [here](../installation/java.md#maven) and TestNG dependencies [here](/docs/cucumber/checking-assertions/#testng).
- Add the two feature files (`scenarios.feature` and `scenario-outlines.feature`) and **step definition class** as described in the JUnit section.
<Content lang="java">
- Add a cucumber **runner** by **extending** the `AbstractTestNGCucumberTests` class and **overriding the scenarios method** in the `parallel` package (same name as step definition package) in `src/test/java` folder. Set the **parallel option value to true** for the DataProvider annotation.


```java
package parallel;

import org.testng.annotations.DataProvider;
import io.cucumber.testng.AbstractTestNGCucumberTests;

public class RunCucumberTest extends AbstractTestNGCucumberTests{

	@Override
	@DataProvider(parallel = true)
	public Object[][] scenarios() {
		return super.scenarios();
	}
}
```
</Content>
<Content lang="kotlin">
- Add a cucumber **runner** by **extending** the `AbstractTestNGCucumberTests` class and **overriding the scenarios method** in the `parallel` package (same name as step definition package) in `src/test/kotlin` folder. Set the **parallel option value to true** for the DataProvider annotation.

```kotlin
package parallel

import org.testng.annotations.DataProvider;
import io.cucumber.testng.AbstractTestNGCucumberTests;

class RunCucumberTest : AbstractTestNGCucumberTests() {
	
	@DataProvider(parallel = true)
	override fun scenarios(): Array<Array<(Any)>>  {
		return super.scenarios()
	}	
}
```
</Content>

- Add the Maven **Surefire plugin configuration** to the `build` section of the `POM`.

```shell
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-surefire-plugin</artifactId>
	<version>2.22.0</version>
</plugin>
```

- Use the Maven `install` or a suitable command to **execute the POM**. This should run in parallel thread mode. You should see a result similar to below. The **scenarios and rows of the scenario outlines are executed in different threads**.

```shell
Thread ID - 15 - Scenario Outline Row 2 from scenario-outlines feature file.
Thread ID - 14 - Scenario Outline Row 1 from scenario-outlines feature file.
Thread ID - 16 - Scenario 1 from scenarios feature file.
Thread ID - 17 - Scenario 2 from scenarios feature file.
```

- To execute using a Maven **Failsafe plugin**, setup the `POM` as described in the JUnit section. Remove the `parallel` and `useUnlimitedThreads` settings in the `configuration` part.

The default **thread count of the dataprovider** in parallel mode is **10**. To change this the `dataproviderthreadcount` property needs to be added to the `configuration` section of the Surefire or Failsafe plugin in the `POM`.
```shell
<configuration>
	<properties>
    	<property>
        	<name>dataproviderthreadcount</name>
        	<value>20</value>
    	</property>
	</properties>
</configuration>
```

If you have **multiple runners**, set the parallel configuration to `classes` to reduce execution times. In addition the `threadCount` can be set to to the desired value or `useUnlimitedThreads` can be set to true.
```shell
<configuration>
	<parallel>classes</parallel>
	<threadCount>4</threadCount>
</configuration>
```

## CLI

The `Main` class in the `io.cucumber.core.cli` package is used to execute the feature files. You can run this class directly from the command line; in that case, there is no need to create any runner class. The usage options for this class are mentioned [here](https://github.com/cucumber/cucumber-jvm/blob/main/cucumber-core/src/main/resources/io/cucumber/core/options/USAGE.txt). The `--threads` option needs to be set to a value **greater than 1** to run in parallel. When the parallel mode is used, the scenarios and rows in a scenario outline will be run in multiple threads.

Follow the steps below to **execute the command from a terminal**.	

- Add the two feature files (`scenarios.feature` and `scenario-outlines.feature`) and **step definition class** as described in the JUnit section.
- Open up a **terminal window** and navigate to the source folder of the project, in this case **parallel**.
<Content lang="java">
- Compile the step definition class. Add the **path to the folder containing cucumber jars to the classpath** using the **-cp** option.

```shell
javac -cp .;<path to cucumber jar folder>/* ./parallel/StepDefs.java
```
</Content>
<Content lang="kotlin">
- Compile the step definition class. Add **path to each of the downloaded cucumber jars to the classpath** using the **-cp** option.

```shell
kotlinc -cp .;<path to each cucumber jar> -jvm-target 1.8 ./parallel/StepDefs.kt
```
</Content>

- Execute using the below command.

<Content lang="java">
```shell
java -cp .;<path to cucumber jar folder>/* io.cucumber.core.cli.Main --threads 4 -g parallel parallel
```
</Content>
<Content lang="kotlin">
```shell
java -cp .;<path to cucumber jar folder>/*;<path to kotlin lib folder>/* io.cucumber.core.cli.Main --threads 4 -g parallel parallel
```
</Content>

- You should get a console output similar to below.

```shell
Thread ID - 11 - Scenario Outline Row 1 from scenario-outlines feature file.
Thread ID - 14 - Scenario 2 from scenarios feature file.
Thread ID - 12 - Scenario Outline Row 2 from scenario-outlines feature file.
Thread ID - 13 - Scenario 1 from scenarios feature file.
```

## Timeline formatter

For a **visual representation** of threads, add the **timeline report** using the `plugin` option of `CucumberOptions` annotation on a JUnit or TestNG runner. 

<Content lang="java">
```java
@CucumberOptions(plugin= {"timeline:<report folder>"})
```
</Content>
<Content lang="kotlin">
```kotlin
@CucumberOptions(plugin = ["timeline:<report folder>"])
```
</Content>

In case of CLI, the below command can be used.

```shell
java -cp <classpath> io.cucumber.core.cli.Main -p timeline:<report folder> --threads <thread count> -g <steps package> <path to feature files>
```

Below is a sample report.

![Timeline report](/img/docs/parallel-timeline-report.png)




================================================
FILE: docs/guides/testable-architecture.md
================================================
---
description: "How to have fast and reliable tests"
---

# Testable architecture

Automated tests and executable specifications can only work with software that has a testable architecture.
A testable architecture enables fast and reliable tests that are easy to write, execute and maintain.

## Fast feedback

Fast tests enable the developers to run them frequently to obtain fast feedback on what they are building, without
losing focus or flow.

## Testability

When designing for testability, make sure that your products and services are composed of loosely-coupled,
well-encapsulated components or modules.

Decoupling your business logic from your infrastructure (the often slow and brittle components),
makes it possible to test at different levels, with maximum confidence and minimum cost.

* Ensure that you can run your tests without going through the user interface (UI). They are slow, brittle, expensive,
and hard to fix. Do not depend solely on UI tests.
* Running tests against a database makes tests slow. We need to make sure the database is in the expected state before
each test in order to make the tests behave consistently.
This will ensure that tests don't interfere with each other and can be executed in any order.

We want most of our tests to use some kind of in-memory stub implementation, instead of an actual database.
From the perspective of the domain logic, the behavior looks exactly the same.
To make sure that the stub works in the same way as the real thing, we need to have confidence, which we can obtain using [contract tests](https://martinfowler.com/bliki/IntegrationContractTest.html).

## Ports and adapters

We can think of our database and our stub as two things that can be plugged into the **port**.
The application containing the business logic doesn't need to know if it's talking to a stub or the actual database. This is because it's talking to this port
and storing and retrieving data. We can run our tests using both the stub and the real implementation. This gives us confidence that the stub behaves like the real thing.

The business logic is at the core of the application, completely decoupled
from external devices and services. It doesn’t know anything about databases, message queues,
or web services, because we have isolated them through these ports. Often,
these ports are connected to adapters that interact with the real implementation.
There will be an adapter for the database, an adapter for the queue, and an adapter for the web service.
The user interface defines how we can interact with our system. It will also have an adapter, such as
a web server that plugs into a port to display a UI in a browser. All the IO tends to happen outside of these ports.
By testing the core business logic directly though the ports, we can eliminate a lot of slow and brittle IO.

This architectural patterns is called **ports and adapters pattern** (or [hexagonal architecture](https://en.wikipedia.org/wiki/Hexagonal_architecture_(software))).
It enables you to connect your scenarios and unit tests at a lower level, while the contract tests give you the confidence to do that.

## Full stack

You’ll want to run *some* tests that go through the whole depth of your stack, to get complete confidence.
Diagnosing where the problem is in a full-stack, end-to-end test is really hard, because it can be anywhere.
These tests are brittle because one change can break all of them. They are also slow,
as there is IO involved when going through a browser, web service or database.

## Test pyramid

Focus on having different kinds of tests: lots and lots of unit tests,
a few tests that don’t go through all the heavy infrastructure components and just a few tests that go through the UI.
This is called the [test pyramid](https://martinfowler.com/bliki/TestPyramid.html).

## More information

For an example of how to implement fast tests (in Node.js), see [subsecondtdd on GitHub](https://github.com/subsecondtdd/todo-subsecond).

Or have a look at Aslak's [talk at Devlin 2017](https://skillsmatter.com/skillscasts/9971-testable-software-architecture-with-aslak-hellesoy) - or the [slides](https://speakerdeck.com/aslakhellesoy/testable-architecture-devlin-2017) - about this subject.



================================================
FILE: docs/guides/upgrading.md
================================================
---
description: "Versioning, changes per version"
---

# Upgrading

We add new features to Cucumber periodically. This means you may want to upgrade to a newer version to take advantage of these new features, as well as any bug fixes.

## Versioning

Cucumber follows the [SemVer](http://semver.org/) specification for release numbers.
Essentially, this means that:

* If only the right-hand (patch) number in the release changes, you don't need to worry.
* If the middle number (minor) number in the release changes, you don't need to worry.
* If the left-hand (major) number changes, you can expect that things might break.

## Release 

You can read the history file to learn about the changes in every release, and see advice on upgrading across major versions where applicable:

- Cucumber-JVM
  - Changelog https://github.com/cucumber/cucumber-jvm/blob/main/CHANGELOG.md
  - Release notes https://github.com/cucumber/cucumber-jvm/tree/main/release-notes
- Cucumber-JVM-Scala
  - Changelog https://github.com/cucumber/cucumber-jvm-scala/blob/main/CHANGELOG.md
  - Upgrade notes https://github.com/cucumber/cucumber-jvm-scala/tree/main?tab=readme-ov-file#getting-started
- Cucumber-JS
  - Changelog https://github.com/cucumber/cucumber-js/blob/main/CHANGELOG.md
  - Upgrading https://github.com/cucumber/cucumber-js/blob/main/UPGRADING.md
- Cucumber-Ruby
  - Changelog https://github.com/cucumber/cucumber-ruby/blob/main/CHANGELOG.md



================================================
FILE: docs/installation/_category_.json
================================================
{
  "position": 0,
  "label": "Installation",
  "collapsed": true,
  "className": "closed-category-hack"
}



================================================
FILE: docs/installation/amp-cucumber-cpp-runner.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: C++
  status: unofficial
  icon: cplusplus.svg
---

# amp-cucumber-cpp-runner

Please see the [amp-cucumber-cpp-runner website](https://github.com/philips-software/amp-cucumber-cpp-runner).



================================================
FILE: docs/installation/android.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Java
  status: official
  icon: android.svg
---

# Android™

Please see the [Cucumber-Android project on GitHub](https://github.com/cucumber/cucumber-android).



================================================
FILE: docs/installation/clojure.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Clojure
  status: unmaintained
  icon: clojure.svg
---

# Cucumber-Clojure

**This package is currently in need of new maintainers.**

Please see [Cucumber-Clojure](https://github.com/cucumber/cucumber-jvm-clojure).



================================================
FILE: docs/installation/cplusplus.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: C++
  status: official
  icon: cplusplus.svg
---

# Cucumber.cpp

Please see the [Cucumber.cpp website](https://github.com/cucumber/cucumber-cpp).



================================================
FILE: docs/installation/cwt-cucumber.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: C++
  status: unofficial
  icon: cplusplus.svg
---

# cwt-cucumber

Please see the [CWT Cucumber on GitHub](https://github.com/ThoSe1990/cwt-cucumber).



================================================
FILE: docs/installation/d.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: D
  status: unofficial
  icon: d.svg
---

# Unencumbered

Please see the [Unencumbered website](https://github.com/atilaneves/unencumbered).



================================================
FILE: docs/installation/gobdd.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Go
  status: unofficial
  icon: golang.svg
---

# GoBDD

Please see the [GoBDD repo](https://github.com/go-bdd/gobdd).



================================================
FILE: docs/installation/gocuke.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Go
  status: semi-official
  icon: golang.svg
---

# gocuke

Please see the [gocuke repo](https://github.com/regen-network/gocuke).



================================================
FILE: docs/installation/golang.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Go
  status: unmaintained
  icon: golang.svg
---

# Godog

Please see the [godog repo](https://github.com/cucumber/godog).



================================================
FILE: docs/installation/gosu.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Gosu
  status: unmaintained
  icon: gosu.png
---

# Cucumber-Gosu

**This package is currently in need of new maintainers.**

Please see [Cucumber-Gosu](https://github.com/cucumber/cucumber-jvm-gosu).



================================================
FILE: docs/installation/groovy.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Groovy
  status: unmaintained
  icon: groovy.svg
---

# Cucumber-Groovy

**This package is currently in need of new maintainers.**

Please see [Cucumber-Groovy](https://github.com/cucumber/cucumber-jvm-groovy).



================================================
FILE: docs/installation/index.mdx
================================================
---
hide_table_of_contents: true
pagination_next: guides/index
---

import {Implementations, StatusBadge} from '@site/src/components/Installation';

# Installation

Cucumber is available for most mainstream programming languages.
We recommend choosing an implementation for the same platform or
programming language as the production code.

* <StatusBadge status="official"/> implementations are hosted under [cucumber](https://github.com/cucumber).
* <StatusBadge status="semi-official"/> implementations are hosted elsewhere, but use components from [cucumber](https://github.com/cucumber).
* <StatusBadge status="unofficial"/> implementations are hosted elsewhere and don't use any components from [cucumber](https://github.com/cucumber).
* <StatusBadge status="unmaintained"/> implementations are official, but unmaintained and in need of new maintainers.

<Implementations />


================================================
FILE: docs/installation/ios.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: iOS (Swift/ObjC)
  status: semi-official
  icon: ios.svg
---

# Cucumberish

Please see the [Cucumberish website](https://github.com/Ahmed-Ali/Cucumberish).



================================================
FILE: docs/installation/java.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  bigThree: true
  language: Java
  status: official
  icon: java.svg
---

# Cucumber-JVM

Cucumber-JVM is published in the central Maven repository.
You can install it by adding dependencies to your project.

:::note[Dependencies]
Make sure the Cucumber version is the same for all Cucumber dependencies.
:::

## Maven

Add the following dependency to your  `pom.xml`:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>{{% version "cucumberjvm" %}}</version>
    <scope>test</scope>
</dependency>
```

You can now run Cucumber [from the command line](/docs/cucumber/api/#from-the-command-line) or [run Cucumber with Maven](/docs/tools/java#maven).

## Gradle

If you are using Gradle **4.10.3 or older** add the following dependencies to `build.gradle`:

```groovy
dependencies {
    testCompile 'io.cucumber:cucumber-java:{{% version "cucumberjvm" %}}'
    testCompile 'io.cucumber:cucumber-junit:{{% version "cucumberjvm" %}}'
}

repositories {
    mavenCentral()
}
```

Similarly, if you want to use Gradle **5.0 or more recent** add the following dependencies to `build.gradle` or `build.gradle.kts`:

```kotlin
dependencies {
    testImplementation("io.cucumber:cucumber-java:{{% version "cucumberjvm" %}}")
    testImplementation("io.cucumber:cucumber-junit:{{% version "cucumberjvm" %}}")
}

repositories {
    mavenCentral()
}
```

You can now run Cucumber [from the command line](/docs/cucumber/api/#from-the-command-line) to execute by [adding a cucumber task](/docs/tools/java#gradle) to `build.gradle` or `build.gradle.kts`.

## JUnit 5 integration

It is also possible to use [cucumber-junit-platform-engine](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine) to run your Cucumber test suite.

## JUnit 4 integration

It is also possible to use [cucumber-junit](/docs/cucumber/api/#junit) to run your Cucumber test suite.

## Assertions

Cucumber does not come with an assertion library. Instead, use the assertion methods
from a [unit testing tool](/docs/cucumber/checking-assertions/#java).

## Dependency Injection

While it's not required, we strongly recommend you include one of the
[dependency injection](/docs/cucumber/state/#dependency-injection) modules as well. This allows
you to share state between [step definitions](/docs/cucumber/step-definitions)
without resorting to static variables (a common source of flickering scenarios).




================================================
FILE: docs/installation/javascript.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  bigThree: true
  language: JavaScript
  status: official
  icon: javascript.svg
---

# Cucumber-JS

Cucumber-JS is available as an [npm package](https://www.npmjs.com/package/@cucumber/cucumber) for use in Node.js.

Add `@cucumber/cucumber` as a development dependency:

```shell npm2yarn
npm install --save-dev @cucumber/cucumber
```


================================================
FILE: docs/installation/jruby.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: JRuby
  status: unmaintained
  icon: jruby.png
---

# Cucumber-JRuby

**This package is currently in need of new maintainers.**

Please see [Cucumber-JRuby](https://github.com/cucumber/cucumber-jvm-jruby).



================================================
FILE: docs/installation/jython.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Jython
  status: unmaintained
  icon: jython.png
---

# Cucumber-Jython

**This package is currently in need of new maintainers.**

Please see [Cucumber-Jython](https://github.com/cucumber/cucumber-jvm-jython).



================================================
FILE: docs/installation/kotlin.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Kotlin
  status: official
  icon: kotlin.svg
---

# Cucumber-JVM

There is no native Kotlin implementation of Cucumber, but you can use [Cucumber-JVM](/docs/installation/java) to write Cucumber tests in Kotlin.

For examples, please see the [kotlin-java8](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-kotlin-java8) examples on GitHub.

To get started, have a look at this [blog post](https://medium.com/@mlvandijk/kukumber-getting-started-with-cucumber-in-kotlin-e55112e7309b).



================================================
FILE: docs/installation/lua.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Lua
  status: unmaintained
  icon: lua.svg
---

# Cucumber-Lua

Please see the [Cucumber-Lua website](https://github.com/cucumber/cucumber-lua).



================================================
FILE: docs/installation/ocaml.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: OCaml
  status: unmaintained
  icon: ocaml.svg
---

# Cucumber.ml

[Cucumber.ml](https://github.com/cucumber/cucumber.ml) is an
implementation written in and useful for
[OCaml](https://ocaml.org/) projects.

## Prerequisites

There are a few prerequisites before you can use
Cucumber.ml:

* Compile and install
  [gherkin-c](https://github.com/cucumber/cucumber/tree/master/gherkin/c)
  as a shared object on your system
* Install [Opam package manager](https://opam.ocaml.org/) for OCaml
* Install [Dune build system](https://github.com/ocaml/dune) via Opam

Cucumber.ml delegates its Gherkin parsing to the
[gherkin-c](https://github.com/cucumber/cucumber/tree/master/gherkin/c)
implementation using OCaml's foreign function interface. This means
that, before you can use Cucumber.ml, you will need to compile and
install gherkin-c as a shared library with its header files on your
system.

Next, check out the
[Cucumber.ml project](https://github.com/cucumber/cucumber.ml) and do the following:

```shell
dune build && dune install
```

This will install the `cucumber` Opam package into your local Opam
repository.  For more information, please read the
[README file](https://github.com/cucumber/cucumber.ml/blob/master/README.md).

:::note
Cucumber.ml assumes that
once you start executing your step definitions it will control
the command line arguments. This can be surprising, so please be aware
of it. Basically, the executable created by the compilation process is
the Cucumber runner and it is that executable which will run your step
definitions.
:::

Please see the [Cucumber OCaml
website](https://github.com/cucumber/cucumber.ml) for more information
and usage instructions.



================================================
FILE: docs/installation/perl.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Perl
  status: semi-official
  icon: perl.png
---

# Test::BDD-Cucumber

Please see the [Cucumber-Perl website](https://github.com/pherkin/test-bdd-cucumber-perl).



================================================
FILE: docs/installation/php.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: PHP
  status: semi-official
  icon: php.svg
---

# Behat

Please see the [Behat website](https://behat.org/).



================================================
FILE: docs/installation/pytest-bdd.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Python
  status: semi-official
  icon: python.png
---

# Pytest-BDD

Please see [Pytest-BDD on GitHub](https://github.com/pytest-dev/pytest-bdd).



================================================
FILE: docs/installation/python.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Python
  status: semi-official
  icon: python.png
---

# Behave

Please see the [Behave website](http://behave.readthedocs.io/).



================================================
FILE: docs/installation/r.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: R
  status: unofficial
  icon: r.svg
---

# Cucumber-R

See more [on GitHub](https://github.com/jakubsob/cucumber).

## From CRAN

```r
install.packages("cucumber")
```

## From GitHub

```r
remotes::install_github("jakubsob/cucumber")
```



================================================
FILE: docs/installation/reqnroll.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: .NET (C#, F#, VB)
  status: semi-official
  icon: dotnet.svg
---

# Reqnroll

Please see the [Reqnroll website](https://reqnroll.net/).

(Reqnroll is a reboot of the now-retired SpecFlow project.)



================================================
FILE: docs/installation/ruby.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  bigThree: true
  language: Ruby
  status: official
  icon: ruby.svg
---

# Cucumber-Ruby

Cucumber for Ruby is a Ruby gem. Depending on your project structure there are several ways to install it:

## Rubygems

Install from the command line:

```shell
gem install cucumber
```

## Bundler (without Rails)

Add `cucumber` to your `Gemfile`:

```ruby
gem 'cucumber'
```

Install the gem:

```shell
bundle
```

Try it out:

```shell
cucumber --help
```

Then, initialize a `features/` directory:

```shell
cucumber --init
```

[Bundler](https://bundler.io/) is a utility gem that manages project specific RubyGem dependencies such that each
Rails project is unaffected by the gem requirements of another.
If you use Bundler to support multiple gem versions in multiple Rails projects on a single development host then you must
run Cucumber using the preface `bundle exec`. For example: `bundle exec cucumber -pnone features`.

## Ruby on Rails

[Cucumber-Rails](https://github.com/cucumber/cucumber-rails) is a gem that Rails projects can use to install cucumber and create its configuration.

Add `cucumber-rails` to your `Gemfile`:
(*Note*: you do not need to add Cucumber)

```ruby
group :test do
  gem 'cucumber-rails', require: false
  # database_cleaner is not mandatory, but highly recommended
  gem 'database_cleaner'
end
```

Install the gem:

```shell
bundle
```

Learn about the various options:

```shell
rails generate cucumber:install --help
```

Run the generator:

```shell
rails generate cucumber:install
```

Cucumber-Rails will detect whether the RSpec gems are installed. If so, then the rails generator builds the environment files to suit.
If not, it ignores RSpec and configures for test-unit instead.



================================================
FILE: docs/installation/rust.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Rust
  status: unofficial
  icon: rust.svg
---

# Cucumber-Rust

Please see the [Cucumber-Rust website](https://github.com/bbqsrc/cucumber-rust).



================================================
FILE: docs/installation/scala.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Scala
  status: official
  icon: scala.svg
---

# Cucumber-Scala

Cucumber-Scala is published in the central Maven repository.
You can install it by adding dependencies to your project.

:::note[Dependencies]
Make sure the Cucumber version is the same for all Cucumber dependencies.
:::

## Maven

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-scala_2.13</artifactId>
    <version>{{% version "cucumberscala" %}}</version>
    <scope>test</scope>
</dependency>
```

You can now run Cucumber [from the command line](/docs/cucumber/api/#from-the-command-line) or [run Cucumber with Maven](/docs/tools/java#maven).

## Sbt

```scala
libraryDependencies += "io.cucumber" %% "cucumber-scala" % "{{% version "cucumberscala" %}}" % Test
```

## JUnit 5 integration

It is also possible to use [cucumber-junit-platform-engine](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine) to run your Cucumber test suite.

## JUnit 4 integration

It is also possible to use [cucumber-junit](/docs/cucumber/api/#junit) to run your Cucumber test suite.

## Assertions

Cucumber does not come with an assertion library. Instead, use the assertion methods
from a [unit testing tool](/docs/cucumber/checking-assertions/#java).




================================================
FILE: docs/installation/tcl.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: Tcl
  status: unmaintained
  icon: tcl.svg
---

# Cucumber-Tcl

Please see the [Cucumber-Tcl website](https://github.com/cucumber/cucumber-ruby-tcl).



================================================
FILE: docs/installation/xunit-gherkin-quick.md
================================================
---
pagination_prev: installation/index
pagination_next: guides/index
sidebar_custom_props:
  language: .NET (C#, F#, VB)
  status: semi-official
  icon: dotnet.svg
---

# Xunit.Gherkin.Quick

Please see the [Xunit.Gherkin.Quick website](https://github.com/ttutisani/Xunit.Gherkin.Quick).



================================================
FILE: docs/terms/_category_.json
================================================
{
  "position": 6,
  "label": "Terminology"
}



================================================
FILE: docs/terms/index.mdx
================================================
import DocCardList from '@theme/DocCardList';

# Terminology

There's loads of new terminology and jargon to learn as you learn about Cucumber and BDD. Here you'll find definitions of the common terms.

<DocCardList />



================================================
FILE: docs/terms/user-story.md
================================================
---
description: "Small increments of value used in planning agile development work"
---

# User story

A *User story* is a small piece of valuable functionality used for planning and prioritising work on an agile team.

A good *User story* should:

- Deliver a demonstrable piece of functionality
- Have testable acceptance criteria

and be

- **I**ndependent
- **N**egotiable
- **V**aluable
- **E**stimatible
- **S**mall
- **T**estable

## Story format

A good *User Story* should describe the **Who** (`<actor>`), **What** (`<feature>`) and **Why** (`<benefit>`).

```
As an <actor>
I want a <feature>
So that <benefit>
```

Example:

```
As an mobile bank customer
I want to see balance on my accounts
So that I can make better informed decisions about my spending
```

## Acceptance criteria using Cucumber language

Acceptance Criteria are conditions that a (software) product must satisfy to be accepted by a user, customer or other stakeholder.

These are best written using the Cucumber language and [Gherkin syntax](../gherkin/index.mdx).

```gherkin
Feature: Some important feature

  Scenario: Get something
    Given I have something
    When I do something
    Then I get something else

  Scenario: Get something different
    Given I have something
    And I have also some other thing
    When I do something different
    Then I get something different
```

… etc., with more scenarios as required.

Example:

```gherkin
Feature: Some important feature

  Scenario: Do not show balance if not logged in
    Given I am not logged on to the mobile banking app
    When I open the mobile banking app
    Then I can see a login page
    And I do not see account balance

  Scenario: Show balance on the accounts page after logging in
    Given I have just logged on to the mobile banking app
    When I load the accounts page
    Then I can see account balance for each of my accounts
```

## Further reading

- [Gherkin reference](../gherkin/reference.md)
- https://ronjeffries.com/xprog/articles/expcardconversationconfirmation/



================================================
FILE: docs/tools/_category_.json
================================================
{
  "position": 5,
  "label": "Tools"
}


================================================
FILE: docs/tools/index.mdx
================================================
import DocCardList from '@theme/DocCardList';

# Tools

Using Cucumber in your project is more manageable with the right tools.

## Editors

Most popular text editors support Gherkin syntax highlighting.

Some IDEs also have advanced support for Cucumber, such as running Cucumber
from within the IDE, displaying results, navigating between Gherkin steps and
step definitions and so on.

### Atom

[Atom](https://github.com/atom/atom) is a text editor for macOS, Windows or Linux.

It offers several [packages](https://atom.io/packages/search?q=cucumber) you can use with Cucumber.

### TextMate

[TextMate](https://macromates.com/) is a text editor for macOS.
See the [`Cucumber.tmbundle`](https://github.com/cucumber/cucumber-tmbundle) documentation.

### Visual Studio Code

[Visual Studio Code](https://code.visualstudio.com/) is a code editor for Windows, Linux, or macOS.

You can use it with these extensions:
 * [Cucumber for VSCode](https://marketplace.visualstudio.com/items?itemName=CucumberOpen.cucumber-official) by the Cucumber Team ([maintainers wanted](https://github.com/cucumber/vscode/issues/205)!)
 * [Cucumber (Gherkin) Full Support](https://marketplace.visualstudio.com/items?itemName=alexkrechik.cucumberautocomplete) by Alexander Krechik.

### Nova

[Nova](https://nova.app) is a text editor for macOS.

See the [Cucumber extension](https://extensions.panic.com/extensions/com.rpowell/com.rpowell.Cucumber/) for Gherkin language support.

## IDEs

* [Java IDEs](./java.md#ides)
* [Ruby IDEs](./ruby.md#ides)
* [CukeTest](http://cuketest.com) is a Gherkin editor and Cucumber.js development tool.
* [testjam.io](https://testjam.io) is an online IDE for running and sharing Cucumber.js snippets.

## Build tools

You can run Cucumber using build tools, rather than from the command line.

* [Java build tools](./java.md#build-tools)
* [Ruby build tools](./ruby.md#build-tools)

## More

<DocCardList />


================================================
FILE: docs/tools/java.md
================================================
---
sidebar_position: 1
---

# Java

This page describes tools commonly used with Java.

## IDEs

### IntelliJ IDEA

- [IntelliJ IDEA](https://www.jetbrains.com/idea/) has the [IntelliJ IDEA Cucumber for Java plugin](https://plugins.jetbrains.com/plugin/7212-cucumber-for-java)

You can find more information on using Cucumber with IntelliJ IDEA in the [IntelliJ IDEA Cucumber help pages](https://www.jetbrains.com/idea/help/cucumber.html)

### Eclipse

- [Eclipse](https://www.eclipse.org/) has the [Cucumber Eclipse plugin](https://cucumber.github.io/cucumber-eclipse/)

## Build tools

The most widely used build tools for Java are [Maven](#maven) and [Gradle](#gradle).

### Maven

To run Cucumber with [Maven](https://maven.apache.org/), make sure that:

- Maven is installed
- The environment variable `MAVEN_HOME` is correctly configured
- The IDE is configured with the latest Maven installation

Clone the [cucumber-jvm-starter-maven-java](https://github.com/cucumber/cucumber-jvm-starter-maven-java) to get started.

### Gradle

To run Cucumber with [Gradle](https://gradle.org/), make sure that:

- Gradle is installed
- The environment variable `GRADLE_HOME` is correctly configured
- The IDE is configured with the latest Gradle installation

Clone the [cucumber-jvm-starter-gradle-java](https://github.com/cucumber/cucumber-jvm-starter-gradle-java) to get started.



================================================
FILE: docs/tools/javascript.md
================================================
---
sidebar_position: 1
---

# JavaScript

This page describes tools commonly used with JavaScript.

## Build tools

The most widely used build tools for JavaScript are [npm](#npm) and [Yarn](#yarn).

### npm

To use Cucumber with [npm](https://www.npmjs.com/), make sure that:

- Node.js is installed
- npm is installed

Cucumber.js is available as an npm module.

Add `@cucumber/cucumber` as a development dependency:

```shell
npm install --save-dev @cucumber/cucumber
```

### Yarn

To run Cucumber with [Yarn](https://yarnpkg.com/en/), make sure that:

- Node.js is installed
- Yarn is installed

Add `@cucumber/cucumber` as a development dependency:

```shell
yarn add --dev @cucumber/cucumber
```



================================================
FILE: docs/tools/related-tools.md
================================================
# Related tools

People have written tools on top of Cucumber. These are the known third-party tools that work together with Cucumber:


| Tool                                                                                                            | Description                                                                                                                                                                                                                                                                                  |
|:----------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Aruba](https://github.com/cucumber/aruba)                                                                      | Generic Step Definitions for command-line programs                                                                                                                                                                                                                                           |
| [AssertThat BDD & Test Management in Jira](https://marketplace.atlassian.com/apps/1219033/assertthat-bdd-test-management-in-jira?hosting=cloud&tab=overview)  | Combines feature/scenario management as well as built in test automation reporting in Jira. Website [AssertThat](https://www.assertthat.com/)   |
| [Backyard](https://github.com/senny/backyard)                                                                   | Name the models in your Cucumbers with ease                                                                                                                                                                                                                                                  |
| [BDD Generator](https://davertmik.github.io/bdd-generator/) | Generates random BDD scenarios in Gherkin format for testing purposes. By [@DavertMik](https://github.com/DavertMik) |
| [Bermuda](https://github.com/jfirebaugh/bermuda)                                                                | Capybara Step library for jQuery UI widgets                                                                                                                                                                                                                                                  |
| [Capybara](https://github.com/jnicklas/capybara)                                                                | Webrat alternative which aims to support all browser simulators                                                                                                                                                                                                                              |
| [Clearance](https://github.com/thoughtbot/clearance/wiki/cucumber-features)                                     | Rails Authentication System with Cucumber Feature generator                                                                                                                                                                                                                                  |
| [Cluecumber](https://github.com/trivago/cluecumber-report-plugin)                                               | Maven plugin for clear and concise Cucumber reporting.                                                                                                                                                                                                                                  |
| [Courgette](https://github.com/jnicklas/courgette)                                                              | Browse your cucumber features from within your Rails app with Courgette, a Rails engine.                                                                                                                                                                                                     |
| [cql](https://github.com/enkessler/cql)                                                                         | A query language for Cucumber features                                                                                                                |
| [crb](https://github.com/maiha/crb/wiki)                                                                        | An irb console for Cucumber world. (crb = cucumber + irb)                                                                                                                                                                                                                                    |
| [Cucable](https://github.com/trivago/cucable-plugin)                                                            | Maven plugin that simplifies running Cucumber Scenarios in parallel.                                                                                                                                                                                                                                  |
| [Cucapp](https://github.com/cappuccino/cucapp)                                                                  | Cucumber integration with Cappuccino.                                                                                                                                                                                                                                                        |
| [Cucover](https://github.com/mattwynne/cucover)                                                                 | Coverage-aware lazy / selective Cucumber Feature runner                                                                                                                                                                                                                                     |
| [Cucumber-cpp](https://github.com/cucumber/cucumber-cpp)                                                        | Cucumber for C                                                                                                                                                                                                                                                                               |
| [Cucumber.el](https://github.com/michaelklishin/cucumber.el)                                                    | [Emacs](https://www.gnu.org/software/emacs/) mode for editing Cucumber plain text stories.                                                                                                                                                                                                    |
| [Cucumber Factory](https://github.com/makandra/cucumber_factory/tree/master)                                    | Create Rails model records without writing Step Definitions.                                                                                                                                                                                                                                 |
| [Cucumber Forge](https://github.com/cerner/cucumber-forge-desktop)                                              | Generate static Cucumber reports using the Electron app or build your own integration with the [NPM library](https://github.com/cerner/cucumber-forge-report-generator).                                                                                                                                                                                    |
| [Cucumber Growler](https://github.com/paolodona/cucumber_growler)                                               | [Growl](http://growl.info/) notifications for Cucumber.                                                                                                                                                                                                                                      |
| [Cucumber Nagios](https://auxesis.github.io/cucumber-nagios)                                                     | Web site monitoring with Cucumber and [Nagios](https://www.nagios.org/)                                                                                                                                                                                                                       |
| [Cucumber REST Gherkin library for Spring](https://github.com/Ragin-LundF/bbd-cucumber-gherkin-lib)             | Library with predefined Gherkin sentences for testing REST APIs with Spring |
| [cucumber-runner](https://plugins.gradle.org/plugin/se.thinkcode.cucumber-runner)                               | A Gradle Cucumber-JVM runner, it may simplify running Cucumber steps in parallel                                                                                                                                                                                                             |
| [cucumber-rust](https://github.com/bbqsrc/cucumber-rust) | An implementation of the Cucumber testing framework for Rust. Fully native, no external test runners or dependencies. |
| [Cucumber Scaffold](https://github.com/andyw8/cucumber_scaffold)                                                | Scaffolding gem for Cucumber Features                                                                                                                                                                                                                                                        |
| [CucumberTFS](https://github.com/mscottford/cucumbertfs)                                                        | Converts Team Foundation Server (TFS) Scenarios into Cucumber Scenarios in a single Feature file.                                                                                                                                                                                            |
| [Cucumber TM Bundle](https://github.com/bmabey/cucumber-tmbundle/tree/master)                                   | Feature syntax highlighting and other useful commands for [TextMate](https://macromates.com/.)                                                                                                                                                                                                |
| [Clucumber](https://github.com/antifuchs/clucumber)                                                             | Support for writing Cucumber Step Definitions in Common LISP, testing Common LISP code.                                                                                                                                                                                                      |
| [cuke_cataloger](https://github.com/enkessler/cuke_cataloger)                                                   | Add unique identifiers to every test case in your suite                                                                                     |
| [cuke_commander](https://github.com/enkessler/cuke_commander)                                            | Dynamically generate Cucumber command lines                                                                                                           |
| [cuke_linter](https://github.com/enkessler/cuke_linter)                                                         | Linting tool for '.feature' files                                                                                                                 |
| [cuke_modeler](https://github.com/enkessler/cuke_modeler)                                                       | Abstraction layer that sits on top of `gherkin` as a stable base upon which to build other tooling                                                 |
| [cuke_slicer](https://github.com/enkessler/cuke_slicer)                                                  | Breaks a Cucumber suite into the most granularly executable pieces for better parallelization                                                      |
| [Cuke4AS3](https://github.com/flashquartermaster/Cuke4AS3)                                                      | Actionscript                                                                                                                                                                                                                                                                                 |
| [Cuke4Nuke](https://github.com/richardlawrence/Cuke4Nuke)                                                       | Support for writing Cucumber Step Definitions in .NET.                                                                                                                                                                                                                                       |
| [Cuke4Lua](https://github.com/dgfitch/Cuke4Lua)                                                                 | Wire protocol implementation for [Lua](https://www.lua.org/)                                                                                                                                                                                                                                  |
| [Cuke4PHP](https://github.com/olbrich/cuke4php)                                                                 | Support for writing Cucumber Step Definitions in PHP, testing PHP code.                                                                                                                                                                                                                      |
| [Cuke4Vs](https://github.com/henritersteeg/cuke4vs)                                                             | Syntax highlighting, intellisense and other editing support for Feature files in Visual Studio 2008.                                                                                                                                                                                         
| [Cukedoctor](https://github.com/rmpestano/cukedoctor)                                                           | Enables [Asciidoc](https://asciidoctor.org/docs/what-is-asciidoc/) markup on Cucumber features for creating readable living documentation.
| [Cuki](https://github.com/andyw8/cuki)                                                                          | Pull Cucumber Features from a Confluence wiki into Feature files                                                                                                                                                                                                                             |
| [Culerity](https://github.com/langalex/culerity/tree/master)                                                    | Integrates Cucumber and Celerity to test Javascript in webapps.                                                                                                                                                                                                                              |
| [daml-cucumber](https://github.com/obsidiansystems/daml-cucumber/tree/main)                                                    | Native cucumber testing for daml smart contracts.                                                                                                                                                                                                                                         |
| [DatabaseCleaner](https://github.com/bmabey/database_cleaner/tree/master)                                       | Different strategies for keeping your DB clean to ensure a clean state. Has Cucumber support out of the box.                                                                                                                                                                                 |
| [Eclipse plugin](https://github.com/cucumber/cucumber-eclipse)                                                  | Eclipse plugin for Cucumber                                                                                                                                                                                                                                                                  |
| [ecucumber](https://github.com/jabberbees/ecucumber)                                                                      | An open source port of Cucumber for Erlang                                                                                                                                                                                                    |
| [Ecukes](https://github.com/ecukes/ecukes)                                                                      | Emacs package that makes it possible to write Cucumber like tests for your Emacs packages                                                                                                                                                                                                    |
| [egherkin](https://github.com/jabberbees/egherkin)                                                                      | An Erlang library for parsing Gherkin documents                                                                                                                                                                                                    |
| [EmailSpec](https://github.com/bmabey/email-spec)                                                               | Collection of [RSpec](https://rspec.info) matchers and Cucumber Steps for testing email in a Rails app                                                                                                                                                                                        |
| [fbrp](https://github.com/diabolo/fbrp/tree/master)                                                             | Sample Rails app of Cucumber showing how to use with restful-authentication.                                                                                                                                                                                                                 |
| [features2](https://www.npmjs.com/package/features2)                                                   | features2 is a simple script that creates HTML and PDF based documentation from Cucumber features. Note that the documentation is generated from the source Cucumber feature files, and NOT from the test results (there are plenty of other tools that can do that).                                                                                          |   
| [cucumber-json-2-pdf](https://www.npmjs.com/package/cucumber-json-2-pdf)                               | This project aims to generate PDF reports based on cucumber json reports                                                                                    |   
| [Features2Cards](https://github.com/brynary/features2cards)                                                     | Create PDFs from Cucumber Features and Scenarios for printing.                                                                                           | 
| [Frank](https://www.testingwithfrank.com/)                                                                       | Test iPhone/iPad applications using Cucumber                                                                                                                                                                                                                                                 |
| [Gizmo](https://github.com/icaruswings/gizmo)                                                                   | A page model testing framework                                                                                                               |
| [Gherkin Editor for Windows](https://www.microsoft.com/en-us/p/gherkin-editor/9pnskl00xc40)                     | Desktop app that has Excel-style editing for tables                                                                                                                                                                                                                          |
| [Gherkin.mode for Coda2](https://github.com/takaxi/gherkin.mode/)                                               | Plugin for Coda2 that highlights syntax keywords of `.feature` file                                                                                                                                                                                                                          |
| [Gherkin lint](https://github.com/vsiakka/gherkin-lint)                                                         | Uses Gherkin to parse feature files and runs linting against the default rules, and the optional rules you specified in your .gherkin-lintrc file. |
| [Gherkingen](https://github.com/hedhyw/gherkingen) | Behaviour Driven Development (BDD) tests generator for Golang. |
| [Ghokin](https://github.com/antham/ghokin)                                                                      | Format and apply transformation on gherkin files                                                                                            |
| [Gocure](https://gitlab.com/rodrigoodhin/gocure)                                               | Gocure is a library that offers the possibility to generate beautiful html reports and it is also possible to embed any file in your Cucumber json reports. This can be done importing in a go project, executing a binary, calling a REST API or in a frontend using our docker container.                                                                                                                                                                                                                              |
| [Groundwork](https://github.com/hectoregm/groundwork/tree/master)                                               | Rails Template using Authlogic that comes with Cucumber Features                                                                                                                                                                                                                             |
| [Guard::Cucumber](https://github.com/guard/guard-cucumber)                                                      | Guard::Cucumber automatically runs your Features (much like autotest)                                                                                                                                                                                                                        |
| [Gutkumber](https://github.com/danlucraft/gutkumber)                                                            | Integration testing for [Ruby-GNOME2](https://ruby-gnome2.osdn.jp/.)                                                                                                                                                                                                                   |
| [Gwen](https://github.com/gwen-interpreter/gwen-web/)                                                           | A Gherkin interpreter for web automation ([Selenium](https://selenium.dev/) wrapper)                                                                                                                                                                                                                                       |
| [jEdit Cucumber Mode on github](https://github.com/graza/jEditCucumberMode)                                     | jEdit mode to add multi-lingual syntax highlighting for `.feature` files                                                                                                                                                                                                                     |
| [Jeweler](https://github.com/technicalpickles/jeweler)                                                          | Craft the perfect RubyGem - with built-in Cucumber support                                                                                                                                                                                                                                   |
| [JSON_spec](https://github.com/collectiveidea/json_spec)                                                        | RSpec matchers and Cucumber `Then` Steps for validating JSON format data, especially useful for RESTful API Scenarios.                                                                                                                                                                       |
| [Melomel](https://github.com/benbjohnson/melomel)                                                               | ActionScript, Flex and Air support for Cucumber                                                                                                                                                                                                                                              |
| [NetBeans IDE (B)](https://github.com/QuBiT/cucumber-netbeans-plugin)                                           | Syntax highlighting                                                                                                                                                                                                                                                                          |
| [NewGem](https://github.com/drnic/newgem)                                                                       | Use `newgem -i cucumber` to generate a bunch of helpful Scenario Steps for gem development                                                                                                                                                                                                   |
| [OCCukes](https://github.com/royratcliffe/OCCukes)                                                              | Objective-C wire protocol implementation. Can be used for testing native iOS and Mac apps.                                                                                                                                                                                                   |
| [Online Gherkin Formatter and Validator](https://www.assertthat.com/gherkin_editor#erlang-dark)  | Free online Gherkin editor, formatter and syntax validator. Website [AssertThat](https://www.assertthat.com/)   |
| [Pickle](https://github.com/ianwhite/pickle/tree/master)                                                        | Model creation/reference in Cucumber - optionally leveraging your factories/blueprints                                                                                                                                                                                                  |
| [Pickler](https://github.com/tpope/pickler/tree/master)                                                         | Synchronize user stories in [Pivotal Tracker](https://www.pivotaltracker.com/) with Cucumber Features.                                                                                                                                                                                        |
| [Pickles Docs](https://www.picklesdoc.com/)                                                                      | Takes your specification (written in Gherkin, with Markdown descriptions) and turns them into an always up-to-date documentation of the current state of your software - in a variety of formats (HTML SPA, Static HTML, JSON, Word .docx, Excel)                                  |
| [Pitest-Cucumber-Plugin](https://github.com/alexvictoor/pitest-cucumber-plugin)                                 | Cucumber integration for mutation testing tool PIT                                                                                                      |
| [Rcumber](https://github.com/christophermoura/rcumber)                                                          | RCumber is a Rails plugin that gives your customers a web interface where they can view, edit and run Cucumber tests directly on your Rails project. No update since 2008                                                                                                                    |
| [Relish](https://relishapp.com)                                                                                  | Relish allows you to browse, search, and share your Cucumber Features on the web as living documentation. Supports public and private projects.                                                                                                                                              |
| [RSpec](https://rspec.info)                                                                                      | Use RSpec's `Object.should` and `Object.should_not` to compare values in your Step Definitions                                                                                                                                                                                               |
| [rSquery](https://github.com/caifara/rsquery)                                                                   | Using jQuery matchers and more in Selenium. Aims to reduce the difficulties involved in writing Selenium tests in Cucumber environments for webapps that use jQuery.                                                                                                                         |
| [JetBrains RubyMine](https://blog.jetbrains.com/ruby/tag/cucumber/)                                             | Syntax highlighting and Test Runner UI                                                                                                                                                                                                                                                       |
| [Schmorgurken](https://github.com/schmorgurken/schmorgurken)                                                    | Native Clojure Gherkin implementation (mostly compatible with Cucumber) that integrates with clojure-test                                                                                                                                                                                    |
| [selenium-webdriver](https://github.com/SeleniumHQ/selenium/wiki/Ruby-Bindings)                                 | Developer-focused browser automation tool for IE, Firefox, Chrome                                                                                                                                                                                                                            |
| [SpecFlow Online Gherkin Editor](https://specflow.org/gherkin-editor/)                                          | Simple Gherkin editor that enables you to quickly write, download and share feature files and scenarios – without any hassle, no content tracking                                                                                                                                     |
| [Swinger](https://github.com/demetriusnunes/swinger/tree/master)                                                | Write acceptance tests for Java/Swing Desktop apps using Cucumber!                                                                                                                                                                                                                           |
| [Testjour](https://github.com/brynary/testjour)                                                                 | Distributed test running (for Cucumber first).                                                                                                                                                                                                                                               |
| [theGardener](https://kelkoogroup.github.io/theGardener/)                                                        | A web application to retrieve features from a large number of projects, to organize them and generate proper documentation based on those BDD features.                                                                                                                                                                                                                             |
| [Tidy Gherkin](https://chrome.google.com/webstore/detail/tidy-gherkin/nobemmencanophcnicjhfhnjiimegjeo?hl=en-GB)                                                        | Google Chrome browser extension, that helps in step definition generation, Gherkin step and table formatting.                                                                                                                                                                                                                            |
| [unobtainium-cucumber](https://github.com/jfinkhaeuser/unobtainium-cucumber)                                    | Integrate Cucumber with configuration driven Selenium or Appium drivers.                                                                                                                                                                                                                     |
| [VCR](https://github.com/vcr/vcr)                                                                               | Record and replay HTTP responses for fast, deterministic, accurate tests. Cucumber integration provided through the use of Tags.                                                                                                                                                      |
| [Vim-Cucumber](https://github.com/tpope/vim-cucumber/tree/master)                                               | Feature syntax highlighting for [Vim](https://www.vim.org/.)                                                                                                                                                                                                                                  |
| [Webrat](https://github.com/brynary/webrat/wiki)                                                                | Interact with a web application from Ruby. Works with Rails, and other web frameworks.                                                                                                                     |
| [Webrat TM Bundle](https://github.com/bmabey/webrat-tmbundle/tree/master)                                       | Collection of TextMate snippets for the webrat API.                                                                                                                                                                                                                                          |
| [Watir](http://watir.com/)                                                                                      | An open source Ruby library for automating tests. Watir interacts with a browser the same way people do: clicking links, filling out forms and validating text.                                                                                                                              |
| [WatirCraft](https://github.com/bret/watircraft/wiki)                                                           | Web testing framework with Cucumber integration that builds on Watir.                                                                                                                                                                                                                        |
| [watircuke](https://github.com/richdownie/watircuke/tree/master)                                                | Cucumber and H30 (watir, safariwatir, firewatir)                                                                                                                                                                                                                                             |
| [YARD-Cucumber](https://github.com/burtlo/yard-cucumber)                                                        | Feature documentation integration with [YARD](https://yardoc.org/)                                                                                                                                                                                                                            |



================================================
FILE: docs/tools/ruby.md
================================================
---
sidebar_position: 1
---

# Ruby

This page describes tools for a Ruby or Ruby on Rails environment.

## IDEs

### RubyMine

[RubyMine](https://www.jetbrains.com/help/ruby/meet-rubymine.html) is a Ruby and Rails IDE.

## Build tools

Cucumber can be run in several ways.
Be aware that `rake cucumber`, `cucumber features`, and `autotest` with `ENV AUTOFEATURE=true` do not necessarily produce
the same results given the same features and step definitions.

### Rake

Running `rake cucumber` from the command line provides the simplest method to run Cucumber tests.

Using Rake requires a `Rakefile` with a `features` task definition. For example:

```ruby
require 'rubygems'
require 'cucumber'
require 'cucumber/rake/task'

Cucumber::Rake::Task.new(:features) do |t|
  t.cucumber_opts = "--format pretty" # Any valid command line option can go here.
end
```

This will run all the Features with the pretty formatter.

Note, how we use the `cucumber_opts` accessor to define our arguments passed to Cucumber.

If you are using [Ruby on Rails](#ruby-on-rails), this task is defined for you already.

Now you can run Cucumber with Rake:

```shell
rake features
```

The rake script provided with Cucumber performs much of the background magic required to get the test database and requisite
libraries properly loaded.
In fact, an important habit to acquire is to run Cucumber as a `rake` task immediately after performing a migration.
This ensures that the test database schema is kept in sync with the development database schema.
You can achieve the same effect by running `rake db:test:prepare` before your first Cucumber run following a migration
but developing the habit of running `rake cucumber` or `rake cucumber:wip` is probably the better course.

The Cucumber Rake task recognises the `@wip` Tag, so `rake cucumber:wip` will run only those scenarios tagged with **@wip**.

For example, given a feature file containing:

```gherkin
Feature: .  .  .

  Scenario: A

  @wip
  Scenario: B

  Scenario: C
```

Then running the command `rake cucumber:wip` will run the Steps contained inside Scenario B only,
while running `rake cucumber:ok` will run the Steps within all Scenarios other than B.

#### Using profiles in Rake tasks

For complex Feature runs that are tested often, it is nice to save the command line arguments as [Cucumber profiles](/docs/cucumber/configuration#profiles).

Once you have some profiles defined, you can use them in your Rake tasks, like so:

```ruby
require 'rubygems'
require 'cucumber'
require 'cucumber/rake/task'

namespace :features do
  Cucumber::Rake::Task.new(:non_js) do |t|
    t.profile = "webrat"
  end

  Cucumber::Rake::Task.new(:selenium) do |t|
    t.profile = "selenium"
  end
end
```

#### Guarding your production machines From Cucumber

Since Rake tasks are used on development and productions systems, it is generally a good idea to place a guard around your Cucumber task so your productions boxes don't need to install Cucumber.

Below is an example of how to do this. This example is the Rake task that Cucumber generates for Rails projects, but the same idea applies to any project using Cucumber and Rake:

```ruby
require 'rubygems'

begin
  require 'cucumber'
  require 'cucumber/rake/task'

  Cucumber::Rake::Task.new(:features) do |t|
    t.cucumber_opts = "--format pretty"
  end

  task features: 'db:test:prepare'
rescue LoadError
  desc 'Cucumber rake task not available'
  task :features do
    abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'
  end
end
```

### Ruby on Rails

#### cucumber-rails

[cucumber-rails](https://github.com/cucumber/cucumber-rails) is a RubyGem which
brings Ruby on Rails Generators for Cucumber with special support for Capybara
and DatabaseCleaner.

##### Installing

The `cucumber:install` generator sets up Cucumber in your Rails project. It
generates the necessary files in the `features/` directory. After
running this generator you will also get a new rake task called `cucumber`.

For more details, see `rails generate cucumber:install --help`.

##### Usage

By default, `cucumber-rails` runs `DatabaseCleaner.start` and
`DatabaseCleaner.clean` before and after your Cucumber scenarios. This default
behavior can be disabled. See the
[cucumber-rails README](https://github.com/cucumber/cucumber-rails) for details.

##### Resources

To learn more of the tools being integrated and assisted by `cucumber-rails`,
see the READMEs of
[DatabaseCleaner](https://github.com/DatabaseCleaner/database_cleaner) and
[Capybara](https://github.com/teamcapybara/capybara).