Package {cucumber}

Progress Reporter for Cucumber

Description

A reporter that prints step-by-step progress to the console, mimicking testthat::ProgressReporter but with visibility into individual Gherkin steps.

Details

Prints each step as it executes with a status indicator, grouped under scenario and feature headers similar to testthat's output:

• ✓ for passed steps (green)

• ✗ for failed/errored steps (red)

Feature: Addition
  Scenario: Add two numbers
    [x] Given I have entered 50 into the calculator
    [x] Given I have entered 70 into the calculator
    [x] When I press add
    [x] Then the result should be 120 on the screen

Usage

Pass a reporter instance to test() or run():

# Step-level detail
cucumber::test("tests/acceptance", reporter = cucumber::CucumberProgressReporter$new())

# testthat reporters still work, reporting at the scenario level only
cucumber::test("tests/acceptance", reporter = testthat::ProgressReporter$new())

# Silent mode
cucumber::test("tests/acceptance", reporter = testthat::SilentReporter$new())

# From within a test file
cucumber::run(reporter = cucumber::CucumberProgressReporter$new())

Creating custom reporters

Extend CucumberReporter to build your own:

HTMLReporter <- R6::R6Class(
  "HTMLReporter",
  inherit = cucumber::CucumberReporter,
  public = list(
    html_output = character(),
    start_feature = function(feature_name) {
      super$start_feature(feature_name)
      self$html_output <- c(self$html_output, sprintf("<h2>%s</h2>", feature_name))
    },
    end_step = function(step) {
      super$end_step(step)
      status_class <- step$status %||% "passed"
      self$html_output <- c(
        self$html_output,
        sprintf('<div class="step %s">%s %s</div>', status_class, step$keyword, step$text)
      )
    },
    end_reporter = function() {
      if (!is.null(super$end_reporter)) super$end_reporter()
      writeLines(self$html_output, "test-report.html")
    }
  )
)

Step metadata

When end_step() is called, the step object contains:

• keyword - The step keyword (Given, When, Then, etc.)

• text - The step text

• status - One of "passed", "failed", or "error"

• error - The error object if the step failed or errored (NULL otherwise)

• duration - Execution time in seconds

• data_table - Data table if present (NULL otherwise)

• docstring - Docstring if present (NULL otherwise)

Super classes

testthat::Reporter -> cucumber::CucumberReporter -> CucumberProgressReporter

Public fields

Methods

Public methods

• CucumberProgressReporter$new()

• CucumberProgressReporter$start_feature()

• CucumberProgressReporter$end_feature()

• CucumberProgressReporter$start_test()

• CucumberProgressReporter$add_result()

• CucumberProgressReporter$start_step()

• CucumberProgressReporter$end_step()

• CucumberProgressReporter$print_step_args()

• CucumberProgressReporter$end_reporter()

• CucumberProgressReporter$clone()

Method new()

Initialize the reporter

Usage

CucumberProgressReporter$new(
  show_praise = TRUE,
  reporter_max_docstring_lines = getOption("cucumber.reporter_max_docstring_lines", Inf),
  reporter_max_table_lines = getOption("cucumber.reporter_max_table_lines", Inf),
  ...
)

Arguments

Method start_feature()

Start a feature

Usage

CucumberProgressReporter$start_feature(feature_name)

Arguments

Method end_feature()

End the current feature

Usage

CucumberProgressReporter$end_feature()

Method start_test()

Start a test (called by testthat for each scenario)

Usage

CucumberProgressReporter$start_test(context, test)

Arguments

Method add_result()

Add a result (warning, skip, failure, etc.)

Usage

CucumberProgressReporter$add_result(context, test, result)

Arguments

Method start_step()

Start a step

Usage

CucumberProgressReporter$start_step(step)

Arguments

Method end_step()

End a step and print its result

Usage

CucumberProgressReporter$end_step(step)

Arguments

Method print_step_args()

Print a step's docstring and/or data table arguments, indented and truncated to reporter_max_docstring_lines / reporter_max_table_lines

Usage

CucumberProgressReporter$print_step_args(step)

Arguments

Method end_reporter()

Print summary at the end (called by testthat)

Usage

CucumberProgressReporter$end_reporter()

Method clone()

The objects of this class are cloneable with this method.

Usage

CucumberProgressReporter$clone(deep = FALSE)

Arguments

See Also

CucumberReporter

Examples

## Not run: 
# Use with cucumber::test()
cucumber::test(
  "tests/acceptance",
  reporter = cucumber::CucumberProgressReporter$new()
)

# Or without praise messages
cucumber::test(
  "tests/acceptance",
  reporter = cucumber::CucumberProgressReporter$new(show_praise = FALSE)
)

## End(Not run)

Cucumber Reporter Base Class

Description

Base class for cucumber reporters that extends testthat::Reporter. Adds step-level and feature-level reporting hooks while maintaining full compatibility with testthat reporters.

Details

CucumberReporter extends testthat's Reporter class to add: - Feature-level hooks: 'start_feature()', 'end_feature()' - Step-level hooks: 'start_step()', 'end_step()'

These additional hooks are called during cucumber test execution to provide visibility into individual step execution. Standard testthat reporters will continue to work unchanged, reporting only at the scenario (test) level.

Methods

'start_feature(feature_name)'

Called before executing a feature's scenarios

'end_feature()'

Called after all scenarios in a feature complete

'start_step(step)'

Called before executing a step

'end_step(step)'

Called after a step completes, with status/error/duration populated

Super class

testthat::Reporter -> CucumberReporter

Public fields

Methods

Public methods

• CucumberReporter$start_feature()

• CucumberReporter$end_feature()

• CucumberReporter$start_step()

• CucumberReporter$end_step()

• CucumberReporter$clone()

Method start_feature()

Start a feature

Usage

CucumberReporter$start_feature(feature_name)

Arguments

Method end_feature()

End the current feature

Usage

CucumberReporter$end_feature()

Method start_step()

Start a step

Usage

CucumberReporter$start_step(step)

Arguments

Method end_step()

End a step (called after execution with status/error/duration populated)

Usage

CucumberReporter$end_step(step)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CucumberReporter$clone(deep = FALSE)

Arguments

Define extra parameters to use in Cucumber steps.

Description

The following parameter types are available by default:

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

Usage

define_parameter_type(name, regexp, transformer)

Arguments

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

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}⁠

• cucumber.reporter_max_docstring_lines

  Max docstring lines CucumberProgressReporter prints per step before truncating.

  default: Inf

• cucumber.reporter_max_table_lines

  Max data table rows CucumberProgressReporter prints per step before truncating.

  default: Inf

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

Mark a step as pending

Description

Call 'pending()' inside a step implementation to signal that the step is not yet implemented. The scenario will be reported as skipped rather than failed.

Usage

pending(message = "TODO")

Arguments

Details

This is useful when you want to write your feature files first and implement the steps later, or when you want to temporarily disable a step without deleting its implementation.

Examples

given("I have {int} cucumbers in my basket", function(n, context) {
  pending("not yet implemented")
})

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, tags = NULL, reporter = get_reporter(), ...)

Arguments

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

Given there is money in my account
Then there is money in my account

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

Given my account has a balance of £430

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

})

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,
  tags = NULL,
  reporter = get_reporter(),
  env = NULL,
  load_helpers = TRUE,
  stop_on_failure = TRUE,
  stop_on_warning = FALSE,
  ...
)

Arguments

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")

# Tag expressions
cucumber::test("tests/acceptance", tags = "@smoke")
cucumber::test("tests/acceptance", tags = "@smoke and @fast")
cucumber::test("tests/acceptance", tags = "@wip and not @slow")
cucumber::test("tests/acceptance", tags = "(@smoke or @ui) and (not @slow)")

## End(Not run)

Validate lines read from a feature file

Description

Validate lines read from a feature file

Usage

validate_feature(lines)