Revert "remove support for generators (#1725)"

This reverts commit a2dcce6.

Author: aurelien-reeves

.mocharc.yml

@@ -2,8 +2,6 @@ colors: true
 file:
   - test/test_helper.ts
 full-trace: true
-forbid-only: true
-forbid-pending: true
 recursive: true
 reporter: dot
 require: 'ts-node/register'

CHANGELOG.md

@@ -9,13 +9,10 @@ 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`
+* Remove deprecated `--retryTagFilter` option (the correct option is `--retry-tag-filter`) 
 
 ### Added
 
@@ -36,7 +33,7 @@ See the [migration guide](./docs/migration.md) for details of how to migrate fro
 ### Fixed
 
 * Prevent duplicate scenario execution where the same feature is targeted in multiple line expressions ([#1706](https://github.com/cucumber/cucumber-js/issues/1706))
-* Fixed reports banner to point to [new docs](https://cucumber.io/docs/cucumber/environment-variables/) about environment variables
+* Fixed reports banner to point to [new docs](https://cucumber.io/docs/cucumber/environment-variables/) about environment variables 
 * Re-add color functions for use with custom formatters [1582](https://github.com/cucumber/cucumber-js/issues/1582)
 * IParameterTypeDefinition regexp fix [1702](https://github.com/cucumber/cucumber-js/issues/1702)
 

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,22 +1,14 @@
-# Migrating from 7.x.x to 8.x.x
-
-## Removal of setDefinitionFunctionWrapper
-
-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.
-
-# Migrating from 6.x.x to 7.x.x
+# Migrating to cucumber-js 7.x.x
 
 ## Package Name
 
 cucumber-js is now published at `@cucumber/cucumber` instead of `cucumber`. To upgrade, you'll need to remove the old package and add the new one:
-
+ 
 ```shell
 $ npm rm cucumber
 $ npm install --save-dev @cucumber/cucumber
-```
-
+``` 
+ 
 You'll need to update any `import`/`require` statements in your support code to use the new package name.
 
 (The executable is still `cucumber-js` though.)

docs/support_files/api_reference.md

@@ -112,6 +112,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.
@@ -131,6 +132,37 @@ Set the default timeout for asynchronous steps. Defaults to `5000` milliseconds.
 
 ---
 
+#### `setDefinitionFunctionWrapper(wrapper)`
+
+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.
+
+A common use case is attaching a screenshot on step failure - this would typically look something like (for a promise-based setup):
+
+```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 => {
+        // call a method on world
+        this.doScreenshot();
+        // 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/generator_step_definitions.feature

@@ -0,0 +1,61 @@
+Feature: Generator Step Definitions
+  In order to use new JavaScript features
+  As a developer
+  I want Cucumber to provide the possibility to use ES6 features
+
+  Background:
+    Given a file named "features/a.feature" with:
+      """
+      Feature: Step is a generator
+        Scenario: Step generator run successfully
+          When I call a step which is a generator with return value "ok"
+          Then I can see the yielded "ok" value in the context
+      """
+    And a file named "features/step_definitions/cucumber_steps.js" with:
+      """
+      const assert = require('assert')
+      const {setWorldConstructor, Then, When} = require('@cucumber/cucumber')
+
+      setWorldConstructor(function () {
+        this.context = ""
+      })
+
+      When(/^I call a step which is a generator with return value "([^"]*)"$/, function *(return_value) {
+        this.context = yield Promise.resolve(return_value);
+      })
+
+      Then(/^I can see the yielded "([^"]*)" value in the context$/, function(return_value) {
+        assert.equal(this.context, return_value)
+      })
+      """
+
+  @spawn
+  Scenario: without generator function runner
+    When I run cucumber-js
+    Then it fails
+    And the error output contains the text:
+      """
+      The following hook/step definitions use generator functions:
+
+        features/step_definitions/cucumber_steps.js:8
+
+      Use 'this.setDefinitionFunctionWrapper(fn)' to wrap them in a function that returns a promise
+      """
+
+  Scenario: with generator function wrapper
+    Given a file named "features/support/setup.js" with:
+      """
+      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
+        }
+      })
+      """
+    When I run cucumber-js
+    Then it passes

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

package.json

@@ -176,6 +176,7 @@
     "@cucumber/messages": "^16.0.1",
     "@cucumber/tag-expressions": "^3.0.1",
     "assertion-error-formatter": "^3.0.0",
+    "bluebird": "^3.7.2",
     "capital-case": "^1.0.4",
     "cli-table3": "^0.6.0",
     "colors": "^1.4.0",
@@ -186,6 +187,7 @@
     "figures": "^3.2.0",
     "glob": "^7.1.6",
     "indent-string": "^4.0.0",
+    "is-generator": "^1.0.3",
     "is-stream": "^2.0.0",
     "knuth-shuffle-seeded": "^1.0.6",
     "mz": "^2.7.0",
@@ -196,13 +198,15 @@
     "stacktrace-js": "^2.0.2",
     "string-argv": "^0.3.1",
     "tmp": "^0.2.1",
+    "util-arity": "^1.1.0",
     "verror": "^1.10.0"
   },
   "devDependencies": {
     "@cucumber/compatibility-kit": "7.0.0",
     "@cucumber/message-streams": "2.1.0",
     "@cucumber/query": "10.1.0",
     "@sinonjs/fake-timers": "7.1.2",
+    "@types/bluebird": "3.5.35",
     "@types/chai": "4.2.21",
     "@types/dirty-chai": "2.0.2",
     "@types/express": "4.17.13",

src/cli/helpers_spec.ts

@@ -135,6 +135,7 @@ describe('helpers', () => {
         stepDefinitions: [
           new StepDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '0',
             line: 9,
             options: {},
@@ -172,6 +173,7 @@ describe('helpers', () => {
         stepDefinitions: [
           new StepDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '0',
             line: 9,
             options: {},
@@ -209,6 +211,7 @@ describe('helpers', () => {
         beforeTestCaseHookDefinitions: [
           new TestCaseHookDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '0',
             line: 3,
             options: {
@@ -220,13 +223,15 @@ describe('helpers', () => {
         afterTestCaseHookDefinitions: [
           new TestCaseHookDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '1',
             line: 7,
             options: {},
             uri: 'features/support/hooks.js',
           }),
           new TestCaseHookDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '2',
             line: 11,
             options: {},
@@ -280,6 +285,7 @@ describe('helpers', () => {
         beforeTestRunHookDefinitions: [
           new TestRunHookDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '0',
             line: 3,
             options: {},
@@ -289,13 +295,15 @@ describe('helpers', () => {
         afterTestRunHookDefinitions: [
           new TestRunHookDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '1',
             line: 7,
             options: {},
             uri: 'features/support/run-hooks.js',
           }),
           new TestRunHookDefinition({
             code: noopFunction,
+            unwrappedCode: noopFunction,
             id: '2',
             line: 11,
             options: {},

src/formatter/helpers/usage_helpers/index.ts

@@ -34,7 +34,7 @@ function buildEmptyMapping(
   const mapping: Record<string, IUsage> = {}
   stepDefinitions.forEach((stepDefinition) => {
     mapping[stepDefinition.id] = {
-      code: stepDefinition.code.toString(),
+      code: stepDefinition.unwrappedCode.toString(),
       line: stepDefinition.line,
       pattern: stepDefinition.expression.source,
       patternType: stepDefinition.expression.constructor.name,