support: re-add setDefinitionFunctionWrapper (minus generator step logic)

CHANGELOG.md

@@ -9,13 +9,11 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
 ----
 ## [Unreleased] (In Git)
 
-See the [migration guide](./docs/migration.md) for details of how to migrate from 7.x.x to 8.x.x
-
 ### Breaking changes
 
 * Drop support for Node.js 10 and 15, add support for Node.js 16
 * Remove deprecated `--retryTagFilter` option (the correct option is `--retry-tag-filter`)
-* Remove `setDefinitionFunctionWrapper` and step definition option `wrapperOptions`
+* Drop native support for generator functions used as step definitions
 
 ### Added
 

dependency-lint.yml

@@ -20,6 +20,7 @@ ignoreErrors:
     - '@typescript-eslint/eslint-plugin' # peer dependency of standard-with-typescript
     - '@typescript-eslint/parser' # peer dependency of @typescript-eslint/eslint-plugin
     - '@types/*' # type definitions
+    - bluebird # features/generator_step_definitions.feature
     - coffeescript # features/compiler.feature
     - eslint-config-prettier # .eslintrc.yml - extends - prettier
     - eslint-config-standard-with-typescript # .eslintrc.yml - extends - standard-with-typescript

docs/migration.md

@@ -1,12 +1,31 @@
-# Migrating from 7.x.x to 8.x.x
+# Migrating to cucumber-js 8.x.x
 
-## Removal of setDefinitionFunctionWrapper
+## Generator step definitions
 
-If this was used to wrap generator functions, please transition to using async / await.
-If this was used to wrap step definitions, please use `BeforeStep` / `AfterStep` hooks instead.
-If you had other use cases, please create an issue.
+Generator functions used in step definitions (`function*` with the `yield` keyword)
+are not natively supported anymore with cucumber-js.
 
-# Migrating from 6.x.x to 7.x.x
+You may consider using `async`/`await` rather than generators.
+
+You can still use generators as before but you need to add your own dependencies
+to `bluebird` and `is-generator`. Cucumber-js will no display explicit error message
+anymore in case you use a generator without wrapping it properly.
+
+```javascript
+const isGenerator = require('is-generator')
+const {coroutine} = require('bluebird')
+const {setDefinitionFunctionWrapper} = require('@cucumber/cucumber')
+
+setDefinitionFunctionWrapper(function (fn) {
+  if (isGenerator.fn(fn)) {
+    return coroutine(fn)
+  } else {
+    return fn
+  }
+})
+```
+
+# Migrating to cucumber-js 7.x.x
 
 ## Package Name
 

docs/support_files/api_reference.md

@@ -113,6 +113,7 @@ Aliases: `Given`, `When`, `Then`.
 * `pattern`: A regex or string pattern to match against a gherkin step.
 * `options`: An object with the following keys:
   - `timeout`: A step-specific timeout, to override the default timeout.
+  - `wrapperOptions`: Step-specific options that are passed to the definition function wrapper.
 * `fn`: A function, which should be defined as follows:
   - Should have one argument for each capture in the regular expression.
   - May have an additional argument if the gherkin step has a docstring or data table.
@@ -132,6 +133,37 @@ Set the default timeout for asynchronous steps. Defaults to `5000` milliseconds.
 
 ---
 
+#### `setDefinitionFunctionWrapper(wrapper)`
+
+_Note: the usage of `setDefinitionFunctionWrapper` is discouraged in favor of [BeforeStep](#beforestepoptions-fn) and [AfterStep](#afterstepoptions-fn) hooks._
+
+Set a function used to wrap step / hook definitions.
+
+The `wrapper` function is expected to take 2 arguments:
+
+- `fn` is the original function defined for the step - needs to be called in order for the step to be run.
+- `options` is the step specific `wrapperOptions` and may be undefined.
+
+Example:
+
+```javascript
+setDefinitionFunctionWrapper(function(fn, options) {
+  return function(...args) {
+    // call original function with correct `this` and arguments
+    // ensure return value of function is returned
+    return fn.apply(this, args)
+      .catch(error => {
+        // rethrow error to avoid swallowing failure
+        throw error;
+      });
+  }
+})
+```
+
+When used, the result is wrapped again to ensure it has the same length of the original step / hook definition.
+
+---
+
 #### `setWorldConstructor(constructor)`
 
 Set a custom world constructor, to override the default world constructor:

docs/support_files/step_definitions.md

@@ -69,6 +69,36 @@ When(/^I view my profile$/, function () {
 });
 ```
 
+
+## Definition function wrapper
+
+If you would like to wrap step or hook definitions in with some additional logic you can use `setDefinitionFunctionWrapper(fn)`. The definitions will be wrapped after they have all been loaded but before the tests begin to run. One example usage is wrapping generator functions to return promises. Cucumber will do an additional stage of wrapping to ensure the function retains its original length.
+
+```javascript
+// features/step_definitions/file_steps.js
+const { Then } = require('@cucumber/cucumber');
+const assert = require('assert');
+const mzFs = require('mz/fs');
+
+Then(/^the file named (.*) is empty$/, function *(fileName) {
+  contents = yield mzFs.readFile(fileName, 'utf8');
+  assert.equal(contents, '');
+});
+
+// features/support/setup.js
+const { setDefinitionFunctionWrapper } = require('@cucumber/cucumber');
+const isGenerator = require('is-generator');
+const Promise = require('bluebird');
+
+setDefinitionFunctionWrapper(function (fn) {
+  if (isGenerator.fn(fn)) {
+    return Promise.coroutine(fn);
+  } else {
+    return fn;
+  }
+});
+```
+
 ## Pending steps
 
 Each interface has its own way of marking a step as pending

features/step_wrapper_with_options.feature

@@ -0,0 +1,35 @@
+Feature: Step Wrapper with Options
+  In order to be able to write more complex step definition wrappers
+  As a developer
+  I want Cucumber to provide the "options" object to the wrapping function
+
+  @spawn
+  Scenario: options passed to the step definitions wrapper
+    Given a file named "features/a.feature" with:
+      """
+      Feature: Step with an option
+        Scenario: Steps
+          When I run a step with options
+      """
+    And a file named "features/step_definitions/cucumber_steps.js" with:
+      """
+      const {When} = require('@cucumber/cucumber')
+
+      When(/^I run a step with options$/, {wrapperOptions: {retry: 2}}, function () {})
+      """
+    And a file named "features/support/setup.js" with:
+      """
+      const {setDefinitionFunctionWrapper} = require('@cucumber/cucumber')
+
+      setDefinitionFunctionWrapper(function (fn, options = {}) {
+        if (options.retry) {
+          console.log("Max retries: ", options.retry);
+        }
+        return fn;
+      })
+      """
+    When I run cucumber-js
+    Then the output contains the text:
+      """
+      Max retries: 2
+      """