Package 'cucumber'

Title: Behavior-Driven Development for R
Description: Write executable specifications in a natural language that describes how your code should behave. Write specifications in feature files using 'Gherkin' language and execute them using functions implemented in R. Use them as an extension to your 'testthat' tests to provide a high level description of how your code works.
Authors: Jakub Sobolewski [aut, cre]
Maintainer: Jakub Sobolewski <[email protected]>
License: MIT + file LICENSE
Version: 2.1.1
Built: 2026-05-17 06:58:50 UTC
Source: https://github.com/jakubsob/cucumber

Help Index

Define extra parameters to use in Cucumber steps.

Description

The following parameter types are available by default:

Type Description
{int} Matches integers, for example 71 or -19. Converts value with as.integer.
{float} Matches floats, for example 3.6, .8 or -9.2. Converts value with as.double.
{word} Matches words without whitespace, for example banana (but not ⁠banana split⁠).
{string} Matches single-quoted or double-quoted strings, for example "banana split" or 'banana split' (but not ⁠banana split⁠). Only the text between the quotes will be extracted. The quotes themselves are discarded.

To use custom parameter types, call define_parameter_type before cucumber::test is called.

Usage

define_parameter_type(name, regexp, transformer)

Arguments

name

The name of the parameter.
regexp

A regular expression that the parameter will match on. Note that if you want to escape a special character, you need to use four backslashes.
transformer

A function that will transform the parameter from a string to the desired type. Must be a function that requires only a single argument.

Value

An object of class parameter, invisibly. Function should be called for side effects.

Examples

define_parameter_type("color", "red|blue|green", as.character)
define_parameter_type(
  name = "sci_number",
  regexp = "[+-]?\\\\d*\\\\.?\\\\d+(e[+-]?\\\\d+)?",
  transform = as.double
)

## Not run: 
#' tests/testthat/test-cucumber.R
cucumber::define_parameter_type("color", "red|blue|green", as.character)
cucumber::test(".", "./steps")

## End(Not run)

Hooks

Description

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 it is run for.

If you want to run a hook only before or after a specific scenario, use it's name to execute hook only for this scenario.

Usage

before(hook)

after(hook)

Arguments

hook

A function that will be run. The function first argument is context and the scenario name is the second argument.

Before

Whatever happens in a before hook is invisible to people who only read the features. You should consider using a 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.

After

After hooks run after the last step of each scenario, even when the scenario failed or thrown an error.

Examples

## Not run: 
before(function(context, scenario_name) {
  context$session <- selenider::selenider_session()
})

after(function(context, scenario_name) {
  selenider::close_session(context$session)
})

after(function(context, scenario_name) {
  if (scenario_name == "Playing one round of the game") {
    context$game$close()
  }
})

## End(Not run)

cucumber Options

Description

Internally used, package-specific options. They allow overriding the default behavior of the package.

Details

The following options are available:

  • cucumber.indent

    Regular expression for the indent of the feature files.

    default: ⁠^\\s{2}⁠

See base::options() and base::getOption() on how to work with options.

Run Cucumber tests in a testthat context

Description

It's purpose is to be able to run Cucumber tests alongside testthat tests.

To do that, place a call to run() in one of the ⁠test-*.R⁠ files in your tests/testthat directory.

Usage

run(path = ".", filter = NULL, ...)

Arguments

path

Path to the directory containing the .feature files. If run() is placed in a ⁠tests/testthat/test-*.R⁠ file and you call testthat::test_dir or similar, it runs in the tests/testthat directory. The default value "." finds all feature files in the tests/testthat directory.
filter

If not NULL, only features with file names matching this regular expression will be executed. Matching is performed on the file name after it's stripped of ".feature".
...

Additional arguments passed to grepl().

Value

NULL, invisibly. To get result and a report, use cucumber::test(), or inspect the result of testthat function call.

Examples

## Not run: 
#' tests/testthat/test-cucumber.R
cucumber::run()

## End(Not run)

Define a step

Description

Provide a description that matches steps in feature files and the implementation function that will be run.

Usage

given(description, implementation)

when(description, implementation)

then(description, implementation)

Arguments

description

A description of the step.

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: 

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: 

Given my account has a balance of £430
Then my account should have a balance of £430

To pass arguments, description can contain placeholders in curly braces.

To match: 

Given my account has a balance of £430

use: 

given("my account has a balance of £{float}", function(balance, context) {

})

If no step definition is found an error will be thrown.

If multiple steps definitions for a single step are found an error will be thrown.
implementation

A function that will be run during test execution.

The implementation function must always have the last parameter named context. It holds the environment where test state can be stored to be passed to the next step.

If a step has a description "I have {int} cucumbers in my basket" then the implementation function should be ⁠function(n, context)⁠. The {int} value will be passed to n, this parameter can have any name.

If a table or a docstring is defined for a step, it will be passed as an argument after placeholder parameters and before context. The function should be a ⁠function(n, table, context)⁠. See an example on how to write implementation that uses tables or docstrings.

Details

Placeholders in expressions are replaced with regular expressions that match values in the feature file. Regular expressions are generated during runtime based on defined parameter types.

The expression "I have {int} cucumbers in my basket" will be converted to "I have [+-]?(?<![.])[:digit:]+(?![.]) cucumbers in my basket". The extracted value of {int} will be passed to the implementation function after being transformed with as.integer.

To define your own parameter types use define_parameter_type.

Value

A function of class step, invisibly. Function should be called for side effects.

See Also

define_parameter_type()

Examples

given("I have {int} cucumbers in my basket", function(n_cucumbers, context) {
  context$n_cucumbers <- n_cucumbers
})

given("I have {int} cucumbers in my basket and a table", function(n_cucumbers, table, context) {
  context$n_cucumbers <- n_cucumbers
  context$table <- table
})

when("I eat {int} cucumbers", function(n_cucumbers, context) {
  context$n_cucumbers <- context$n_cucumbers - n_cucumbers
})

then("I should have {int} cucumbers in my basket", function(n_cucumbers, context) {
  expect_equal(context$n_cucumbers, n_cucumbers)
})

Run Cucumber tests

Description

It runs tests from specifications in .feature files found in the path.

To run Cucumber tests alongside testthat tests, see cucumber::run().

Usage

test(
  path = "tests/acceptance",
  filter = NULL,
  reporter = NULL,
  env = NULL,
  load_helpers = TRUE,
  stop_on_failure = TRUE,
  stop_on_warning = FALSE,
  ...
)

Arguments

path

Path to directory containing tests.
filter

If not NULL, only features with file names matching this regular expression will be executed. Matching is performed on the file name after it's stripped of ".feature".
reporter

Reporter to use to summarise output. Can be supplied as a string (e.g. "summary") or as an R6 object (e.g. SummaryReporter$new()).

See Reporter for more details and a list of built-in reporters.
env

Environment in which to execute the tests. Expert use only.
load_helpers

Source helper files before running the tests?
stop_on_failure

If TRUE, throw an error if any tests fail.
stop_on_warning

If TRUE, throw an error if any tests generate warnings.
...

Additional arguments passed to grepl() to control filtering.

Good Practices

  • Use a separate directory for your acceptance tests, e.g. tests/acceptance.

    It's not prohibited to use tests/testthat directory, but it's not recommended as those tests serve a different purpose and are better run separately, especially if acceptance tests take longer to run than unit tests.

    If you want to run Cucumber tests alongside testthat tests, you can use cucumber::run() in one of the ⁠test-*.R⁠ files in your tests/testthat directory.

  • Use ⁠setup-*.R⁠ files for calling step(), define_parameter_type() and hook() to leverage testthat loading mechanism.

    If your step(), define_parameter_type() and hook() are called from somewhere else, you are responsible for loading them.

    Read more about testthat special files in the testthat documentation.

  • Use ⁠test-*.R⁠ files to test the support code you might have implemented that is used to run Cucumber tests.

    Those tests won't be run when calling test(). To run those tests use testthat::test_dir("tests/acceptance").

Examples

## Not run: 
cucumber::test("tests/acceptance")
cucumber::test("tests/acceptance", filter = "addition|multiplication")

## End(Not run)