| Type: | Package |
| Title: | Behavior-Driven Development for R |
| Version: | 2.1.1 |
| 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. |
| License: | MIT + file LICENSE |
| URL: | https://github.com/jakubsob/cucumber, https://jakubsobolewski.com/cucumber/ |
| BugReports: | https://github.com/jakubsob/cucumber/issues |
| Encoding: | UTF-8 |
| Depends: | R (≥ 4.1.0) |
| Imports: | checkmate, cli, dplyr, fs, glue, purrr, rlang, stringr, testthat (≥ 3.0.0), tibble, withr |
| Suggests: | mockery, box, shinytest2, chromote, covr, knitr, rmarkdown, quarto, R6, pkgdown, pkgload, muttest |
| Config/testthat/edition: | 3 |
| RoxygenNote: | 7.3.2 |
| VignetteBuilder: | quarto |
| Config/Needs/website: | rmarkdown |
| NeedsCompilation: | no |
| Packaged: | 2025-07-21 07:38:35 UTC; jakubsobolewski |
| Author: | Jakub Sobolewski [aut, cre] |
| Maintainer: | Jakub Sobolewski <jakupsob@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2025-07-21 07:50:02 UTC |
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.indentRegular 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 |
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 |
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 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 If a step has a description If a table or a docstring is defined for a step, it will be passed as an argument after placeholder parameters
and before |
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
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. 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 |
stop_on_warning |
If |
... |
Additional arguments passed to |
Good Practices
Use a separate directory for your acceptance tests, e.g.
tests/acceptance.It's not prohibited to use
tests/testthatdirectory, 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
testthattests, you can usecucumber::run()in one of thetest-*.Rfiles in yourtests/testthatdirectory.Use
setup-*.Rfiles for callingstep(),define_parameter_type()andhook()to leverage testthat loading mechanism.If your
step(),define_parameter_type()andhook()are called from somewhere else, you are responsible for loading them.Read more about testthat special files in the testthat documentation.
Use
test-*.Rfiles 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 usetestthat::test_dir("tests/acceptance").
Examples
## Not run:
cucumber::test("tests/acceptance")
cucumber::test("tests/acceptance", filter = "addition|multiplication")
## End(Not run)
Validate lines read from a feature file
Description
Validate lines read from a feature file
Usage
validate_feature(lines)