Add BeforeStep & AfterStep

This fixes #847 [1].

[1] #847

Author: badeball

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+- Add BeforeStep and AfterStep hooks, fixes [#847](https://github.com/badeball/cypress-cucumber-preprocessor/issues/847).
+
 ## v17.1.1
 
 - Allow generation of JSON reports with hooks (After / Before) even if `baseUrl` is undefined, fixes [#1017](https://github.com/badeball/cypress-cucumber-preprocessor/issues/1017).

docs/cucumber-basics.md

@@ -101,7 +101,7 @@ When("I fill in the entire form", function () {
 });
 ```
 
-# Hooks
+# Scenario hooks
 
 `Before()` and `After()` is similar to Cypress' `beforeEach()` and `afterEach()`, but they can be selected to conditionally run based on the tags of each scenario, as shown below. Furthermore, failure in these hooks does **not** result in remaining tests being skipped. This is contrary to Cypress' `beforeEach` and `afterEach`.
 
@@ -128,4 +128,35 @@ Before({ tags: "@foo or @bar" }, function () {
 });
 ```
 
+# Step hooks
+
+`BeforeStep()` and `AfterStep()` are hooks invoked before and after each step, respectively. These too can be selected to conditionally run based on the tags of each scenario, as shown below.
+
+> **Note**  
+> Contrary to how cucumber-js works, these `AfterStep()` hooks **does not** run if your step fails[^1].
+
+```ts
+import { BeforeStep } from "@badeball/cypress-cucumber-preprocessor";
+
+BeforeStep(function (options) {
+  // This hook will be executed before all steps.
+});
+
+BeforeStep({ tags: "@foo" }, function () {
+  // This hook will be executed before steps in scenarios tagged with @foo.
+});
+
+BeforeStep({ tags: "@foo and @bar" }, function () {
+  // This hook will be executed before steps in scenarios tagged with @foo and @bar.
+});
+
+BeforeStep({ tags: "@foo or @bar" }, function () {
+  // This hook will be executed before steps in scenarios tagged with @foo or @bar.
+});
+
+BeforeStep(function ({ pickle, pickleStep, gherkinDocument, result, testCaseStartedId, testStepId }) {
+  // Step hooks are invoked with an object containing a bunch of relevant data.
+});
+```
+
 [^1]: This discrepancy between the preprocessor and cucumber-js is currently considered to be unsolvable, as explained [here](https://github.com/badeball/cypress-cucumber-preprocessor/issues/824#issuecomment-1561492281).

features/reporters/json.feature

@@ -232,6 +232,57 @@ Feature: JSON formatter
       Then it fails
       And there should be a JSON output similar to "fixtures/failing-after.json"
 
+  Rule: step hooks affects the result of the current step
+    Background:
+      Given additional Cypress configuration
+        """
+        {
+          "screenshotOnRunFailure": false
+        }
+        """
+
+    Scenario: failing BeforeStep
+      Given a file named "cypress/e2e/a.feature" with:
+        """
+        Feature: a feature
+          Scenario: a scenario
+            Given a failing step
+            And another step
+        """
+      And a file named "cypress/support/step_definitions/steps.js" with:
+        """
+        const { BeforeStep, Given } = require("@badeball/cypress-cucumber-preprocessor");
+        BeforeStep(function() {
+          throw "some error"
+        })
+        Given("a failing step", function() {})
+        Given("another step", function () {})
+        """
+      When I run cypress
+      Then it fails
+      And there should be a JSON output similar to "fixtures/failing-step.json"
+
+    Scenario: failing AfterStep
+      Given a file named "cypress/e2e/a.feature" with:
+        """
+        Feature: a feature
+          Scenario: a scenario
+            Given a failing step
+            And another step
+        """
+      And a file named "cypress/support/step_definitions/steps.js" with:
+        """
+        const { AfterStep, Given } = require("@badeball/cypress-cucumber-preprocessor");
+        AfterStep(function() {
+          throw "some error"
+        })
+        Given("a failing step", function() {})
+        Given("another step", function () {})
+        """
+      When I run cypress
+      Then it fails
+      And there should be a JSON output similar to "fixtures/failing-step.json"
+
   Rule: it should contain screenshots captured during a test
     Scenario: explicit screenshot
       Given a file named "cypress/e2e/a.feature" with:

features/reporters/messages.feature

@@ -233,6 +233,57 @@ Feature: messages report
       Then it fails
       And there should be a messages similar to "fixtures/failing-after.ndjson"
 
+  Rule: step hooks affects the result of the current step
+    Background:
+      Given additional Cypress configuration
+        """
+        {
+          "screenshotOnRunFailure": false
+        }
+        """
+
+    Scenario: failing BeforeStep
+      Given a file named "cypress/e2e/a.feature" with:
+        """
+        Feature: a feature
+          Scenario: a scenario
+            Given a failing step
+            And another step
+        """
+      And a file named "cypress/support/step_definitions/steps.js" with:
+        """
+        const { BeforeStep, Given } = require("@badeball/cypress-cucumber-preprocessor");
+        BeforeStep(function() {
+          throw "some error"
+        })
+        Given("a failing step", function() {})
+        Given("another step", function () {})
+        """
+      When I run cypress
+      Then it fails
+      And there should be a messages similar to "fixtures/failing-step.ndjson"
+
+    Scenario: failing AfterStep
+      Given a file named "cypress/e2e/a.feature" with:
+        """
+        Feature: a feature
+          Scenario: a scenario
+            Given a failing step
+            And another step
+        """
+      And a file named "cypress/support/step_definitions/steps.js" with:
+        """
+        const { AfterStep, Given } = require("@badeball/cypress-cucumber-preprocessor");
+        AfterStep(function() {
+          throw "some error"
+        })
+        Given("a failing step", function() {})
+        Given("another step", function () {})
+        """
+      When I run cypress
+      Then it fails
+      And there should be a messages similar to "fixtures/failing-step.ndjson"
+
   Rule: it should contain screenshots captured during a test
     Scenario: explicit screenshot
       Given a file named "cypress/e2e/a.feature" with:

lib/browser-runtime.ts

@@ -63,6 +63,8 @@ import { runStepWithLogGroup } from "./helpers/cypress";
 
 import { getTags } from "./helpers/environment";
 
+import { IStepHookParameter } from "./public-member-types";
+
 type Node = ReturnType<typeof parse>;
 
 interface CompositionContext {
@@ -437,6 +439,16 @@ function createPickle(context: CompositionContext, pickle: messages.Pickle) {
           return cy.wrap(start, { log: false });
         })
           .then((start) => {
+            const beforeStepHooks = registry.resolveBeforeStepHooks(tags);
+            const afterStepHooks = registry.resolveAfterStepHooks(tags);
+            const options: IStepHookParameter = {
+              pickle,
+              pickleStep,
+              gherkinDocument,
+              testCaseStartedId,
+              testStepId: pickleStep.id,
+            };
+
             try {
               return runStepWithLogGroup({
                 keyword: assertAndReturn(
@@ -445,7 +457,23 @@ function createPickle(context: CompositionContext, pickle: messages.Pickle) {
                 ),
                 argument,
                 text,
-                fn: () => registry.runStepDefininition(this, text, argument),
+                fn: () => {
+                  for (const beforeStepHook of beforeStepHooks) {
+                    registry.runStepHook(this, beforeStepHook, options);
+                  }
+
+                  const result = registry.runStepDefininition(
+                    this,
+                    text,
+                    argument
+                  );
+
+                  for (const afterStepHook of afterStepHooks.reverse()) {
+                    registry.runStepHook(this, afterStepHook, options);
+                  }
+
+                  return result;
+                },
               }).then((result) => {
                 return {
                   start,

lib/entrypoint-browser.ts

@@ -25,6 +25,7 @@ import { getRegistry } from "./registry";
 
 import {
   IHookBody,
+  IStepHookBody,
   IParameterTypeDefinition,
   IStepDefinitionBody,
 } from "./public-member-types";
@@ -84,6 +85,36 @@ function defineAfter(
   }
 }
 
+function defineBeforeStep(options: { tags?: string }, fn: IStepHookBody): void;
+function defineBeforeStep(fn: IStepHookBody): void;
+function defineBeforeStep(
+  optionsOrFn: IStepHookBody | { tags?: string },
+  maybeFn?: IStepHookBody
+) {
+  if (typeof optionsOrFn === "function") {
+    getRegistry().defineBeforeStep({}, optionsOrFn);
+  } else if (typeof optionsOrFn === "object" && typeof maybeFn === "function") {
+    getRegistry().defineBeforeStep(optionsOrFn, maybeFn);
+  } else {
+    throw new Error("Unexpected argument for Before hook");
+  }
+}
+
+function defineAfterStep(options: { tags?: string }, fn: IStepHookBody): void;
+function defineAfterStep(fn: IStepHookBody): void;
+function defineAfterStep(
+  optionsOrFn: IStepHookBody | { tags?: string },
+  maybeFn?: IStepHookBody
+) {
+  if (typeof optionsOrFn === "function") {
+    getRegistry().defineAfterStep({}, optionsOrFn);
+  } else if (typeof optionsOrFn === "object" && typeof maybeFn === "function") {
+    getRegistry().defineAfterStep(optionsOrFn, maybeFn);
+  } else {
+    throw new Error("Unexpected argument for After hook");
+  }
+}
+
 function createStringAttachment(
   data: string,
   mediaType: string,
@@ -161,4 +192,6 @@ export {
   defineParameterType,
   defineBefore as Before,
   defineAfter as After,
+  defineBeforeStep as BeforeStep,
+  defineAfterStep as AfterStep,
 };

lib/entrypoint-node.ts

@@ -2,6 +2,7 @@ import DataTable from "./data_table";
 
 import {
   IHookBody,
+  IStepHookBody,
   IParameterTypeDefinition,
   IStepDefinitionBody,
 } from "./public-member-types";
@@ -98,4 +99,26 @@ export function After(
   throw createUnimplemented();
 }
 
+export function BeforeStep(options: { tags?: string }, fn: IStepHookBody): void;
+export function BeforeStep(fn: IStepHookBody): void;
+export function BeforeStep(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  optionsOrFn: IStepHookBody | { tags?: string },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  maybeFn?: IStepHookBody
+) {
+  throw createUnimplemented();
+}
+
+export function AfterStep(options: { tags?: string }, fn: IStepHookBody): void;
+export function AfterStep(fn: IStepHookBody): void;
+export function AfterStep(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  optionsOrFn: IStepHookBody | { tags?: string },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  maybeFn?: IStepHookBody
+) {
+  throw createUnimplemented();
+}
+
 export { default as DataTable } from "./data_table";

lib/public-member-types.ts

@@ -1,3 +1,5 @@
+import * as messages from "@cucumber/messages";
+
 export interface IParameterTypeDefinition<T, C extends Mocha.Context> {
   name: string;
   regexp: RegExp;
@@ -8,6 +10,18 @@ export interface IHookBody {
   (this: Mocha.Context): void;
 }
 
+export interface IStepHookParameter {
+  pickle: messages.Pickle;
+  pickleStep: messages.PickleStep;
+  gherkinDocument: messages.GherkinDocument;
+  testCaseStartedId: string;
+  testStepId: string;
+}
+
+export interface IStepHookBody {
+  (this: Mocha.Context, options: IStepHookParameter): void;
+}
+
 export interface IStepDefinitionBody<
   T extends unknown[],
   C extends Mocha.Context