Validate that addCucumberPreprocessorPlugin has been invoked

badeball · badeball · commit cac92b082368 · 2022-09-04T20:25:08.000+02:00
This allows me to not mention it everywhere in the docs, which became
tiring. This is also a preperation for adding another page which would
otherwise have had to mention it.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ All notable changes to this project will be documented in this file.
 
 - Total execution time is correctly shown in HTML reports, fixes [#813](https://github.com/badeball/cypress-cucumber-preprocessor/issues/813).
 
+- Validate inclusion of `addCucumberPreprocessorPlugin()` in `setupNodeEvents()`, fixes [#820](https://github.com/badeball/cypress-cucumber-preprocessor/issues/820).
+
 ## v12.1.0
 
 - Start time and execution time is shown in HTML reports, fixes [#798](https://github.com/badeball/cypress-cucumber-preprocessor/issues/798).
diff --git a/docs/html-report.md b/docs/html-report.md
@@ -9,23 +9,3 @@ HTML reports can be enabled using the `html.enabled` property. The preprocessor
   }
 }
 ```
-
-This **requires** you to have registered this module in your [configuration file](https://docs.cypress.io/guides/references/configuration#Configuration-File), as shown below.
-
-```ts
-import { addCucumberPreprocessorPlugin } from "@badeball/cypress-cucumber-preprocessor";
-
-export default defineConfig({
-  e2e: {
-    async setupNodeEvents(
-      on: Cypress.PluginEvents,
-      config: Cypress.PluginConfigOptions
-    ) {
-      await addCucumberPreprocessorPlugin(on, config);
-
-      // Make sure to return the config object as it might have been modified by the plugin.
-      return config;
-    },
-  },
-});
-```
diff --git a/docs/json-report.md b/docs/json-report.md
@@ -10,27 +10,7 @@ JSON reports can be enabled using the `json.enabled` property. The preprocessor
 }
 ```
 
-This **requires** you to have registered this module in your [configuration file](https://docs.cypress.io/guides/references/configuration#Configuration-File), as shown below.
-
-```ts
-import { addCucumberPreprocessorPlugin } from "@badeball/cypress-cucumber-preprocessor";
-
-export default defineConfig({
-  e2e: {
-    async setupNodeEvents(
-      on: Cypress.PluginEvents,
-      config: Cypress.PluginConfigOptions
-    ) {
-      await addCucumberPreprocessorPlugin(on, config);
-
-      // Make sure to return the config object as it might have been modified by the plugin.
-      return config;
-    },
-  },
-});
-```
-
-This also **requires** you to have downloaded and installed the [cucumber-json-formatter](https://github.com/cucumber/json-formatter) **yourself**. Arch Linux users can install it from [AUR](https://aur.archlinux.org/packages/cucumber-json-formatter).
+This **requires** you to have downloaded and installed the [cucumber-json-formatter](https://github.com/cucumber/json-formatter) **yourself**. Arch Linux users can install it from [AUR](https://aur.archlinux.org/packages/cucumber-json-formatter).
 
 The location of the executable is configurable through the `json.formatter` property, but it will by default search for `cucumber-json-formatter` in your `PATH`.
 
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -21,6 +21,7 @@ export default defineConfig({
       on: Cypress.PluginEvents,
       config: Cypress.PluginConfigOptions
     ): Promise<Cypress.PluginConfigOptions> {
+      // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
       await addCucumberPreprocessorPlugin(on, config);
 
       on(
diff --git a/docs/tags.md b/docs/tags.md
@@ -37,25 +37,7 @@ Tags are inherited by child elements. Tags that are placed above a `Feature` wil
 
 ## Running a subset of scenarios
 
-Normally when running a subset of scenarios using `cypress run --env tags=@foo`, you could potentially encounter files containing no matching scenarios. These can be pre-filtered away by setting `filterSpecs` to `true`, thus saving you execution time. This **requires** you to have registered this module in your [configuration file](https://docs.cypress.io/guides/references/configuration#Configuration-File), as shown below.
-
-```ts
-import { addCucumberPreprocessorPlugin } from "@badeball/cypress-cucumber-preprocessor";
-
-export default defineConfig({
-  e2e: {
-    async setupNodeEvents(
-      on: Cypress.PluginEvents,
-      config: Cypress.PluginConfigOptions
-    ) {
-      await addCucumberPreprocessorPlugin(on, config);
-
-      // Make sure to return the config object as it might have been modified by the plugin.
-      return config;
-    },
-  },
-});
-```
+Normally when running a subset of scenarios using `cypress run --env tags=@foo`, you could potentially encounter files containing no matching scenarios. These can be pre-filtered away by setting `filterSpecs` to `true`, thus saving you execution time.
 
 ## Omit filtered tests
 
diff --git a/examples/browserify-cjs/cypress.config.js b/examples/browserify-cjs/cypress.config.js
@@ -3,6 +3,7 @@ const preprocessor = require("@badeball/cypress-cucumber-preprocessor");
 const browserify = require("@badeball/cypress-cucumber-preprocessor/browserify");
 
 async function setupNodeEvents(on, config) {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await preprocessor.addCucumberPreprocessorPlugin(on, config);
 
   on("file:preprocessor", browserify.default(config));
diff --git a/examples/browserify-esm/cypress.config.mjs b/examples/browserify-esm/cypress.config.mjs
@@ -3,6 +3,7 @@ import preprocessor from "@badeball/cypress-cucumber-preprocessor";
 import browserify from "@badeball/cypress-cucumber-preprocessor/browserify.js";
 
 export async function setupNodeEvents(on, config) {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await preprocessor.addCucumberPreprocessorPlugin(on, config);
 
   on("file:preprocessor", browserify.default(config));
diff --git a/examples/browserify-ts/cypress.config.ts b/examples/browserify-ts/cypress.config.ts
@@ -6,6 +6,7 @@ async function setupNodeEvents(
   on: Cypress.PluginEvents,
   config: Cypress.PluginConfigOptions
 ): Promise<Cypress.PluginConfigOptions> {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await addCucumberPreprocessorPlugin(on, config);
 
   on(
diff --git a/examples/esbuild-cjs/cypress.config.js b/examples/esbuild-cjs/cypress.config.js
@@ -4,6 +4,7 @@ const preprocessor = require("@badeball/cypress-cucumber-preprocessor");
 const createEsbuildPlugin = require("@badeball/cypress-cucumber-preprocessor/esbuild");
 
 async function setupNodeEvents(on, config) {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await preprocessor.addCucumberPreprocessorPlugin(on, config);
 
   on(
diff --git a/examples/esbuild-esm/cypress.config.mjs b/examples/esbuild-esm/cypress.config.mjs
@@ -4,6 +4,7 @@ import preprocessor from "@badeball/cypress-cucumber-preprocessor";
 import createEsbuildPlugin from "@badeball/cypress-cucumber-preprocessor/esbuild.js";
 
 export async function setupNodeEvents(on, config) {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await preprocessor.addCucumberPreprocessorPlugin(on, config);
 
   on(
diff --git a/examples/esbuild-ts/cypress.config.ts b/examples/esbuild-ts/cypress.config.ts
@@ -7,6 +7,7 @@ async function setupNodeEvents(
   on: Cypress.PluginEvents,
   config: Cypress.PluginConfigOptions
 ): Promise<Cypress.PluginConfigOptions> {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await addCucumberPreprocessorPlugin(on, config);
 
   on(
diff --git a/examples/webpack-cjs/cypress.config.js b/examples/webpack-cjs/cypress.config.js
@@ -3,6 +3,7 @@ const webpack = require("@cypress/webpack-preprocessor");
 const preprocessor = require("@badeball/cypress-cucumber-preprocessor");
 
 async function setupNodeEvents(on, config) {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await preprocessor.addCucumberPreprocessorPlugin(on, config);
 
   on(
diff --git a/examples/webpack-esm/cypress.config.mjs b/examples/webpack-esm/cypress.config.mjs
@@ -3,6 +3,7 @@ import webpack from "@cypress/webpack-preprocessor";
 import preprocessor from "@badeball/cypress-cucumber-preprocessor";
 
 export async function setupNodeEvents(on, config) {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await preprocessor.addCucumberPreprocessorPlugin(on, config);
 
   on(
diff --git a/examples/webpack-ts/cypress.config.ts b/examples/webpack-ts/cypress.config.ts
@@ -6,6 +6,7 @@ async function setupNodeEvents(
   on: Cypress.PluginEvents,
   config: Cypress.PluginConfigOptions
 ): Promise<Cypress.PluginConfigOptions> {
+  // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
   await addCucumberPreprocessorPlugin(on, config);
 
   on(
diff --git a/features/loaders/browserify.feature b/features/loaders/browserify.feature
@@ -10,16 +10,19 @@ Feature: browserify + typescript
     And a file named "cypress/plugins/index.js" or "setupNodeEvents.js" (depending on Cypress era) with:
       """
       const browserify = require("@cypress/browserify-preprocessor");
+      const { addCucumberPreprocessorPlugin } = require("@badeball/cypress-cucumber-preprocessor");
       const { preprocessor } = require("@badeball/cypress-cucumber-preprocessor/browserify");
 
       module.exports = async (on, config) => {
+        await addCucumberPreprocessorPlugin(on, config);
         on(
           "file:preprocessor",
           preprocessor(config, {
             ...browserify.defaultOptions,
             typescript: require.resolve("typescript")
           })
         );
+        return config;
       };
       """
     And a file named "cypress/support/step_definitions/steps.ts" with:
diff --git a/features/loaders/esbuild.feature b/features/loaders/esbuild.feature
@@ -10,15 +10,18 @@ Feature: esbuild + typescript
     And a file named "cypress/plugins/index.js" or "setupNodeEvents.js" (depending on Cypress era) with:
       """
       const createBundler = require("@bahmutov/cypress-esbuild-preprocessor");
+      const { addCucumberPreprocessorPlugin } = require("@badeball/cypress-cucumber-preprocessor");
       const { createEsbuildPlugin } = require("@badeball/cypress-cucumber-preprocessor/esbuild");
 
       module.exports = async (on, config) => {
+        await addCucumberPreprocessorPlugin(on, config);
         on(
           "file:preprocessor",
           createBundler({
             plugins: [createEsbuildPlugin(config)]
           })
         );
+        return config;
       };
       """
     And a file named "cypress/support/step_definitions/steps.ts" with:
diff --git a/features/loaders/webpack.feature b/features/loaders/webpack.feature
@@ -10,8 +10,10 @@ Feature: webpack + typescript
     And a file named "cypress/plugins/index.js" or "setupNodeEvents.js" (depending on Cypress era) with:
       """
       const webpack = require("@cypress/webpack-preprocessor");
+      const { addCucumberPreprocessorPlugin } = require("@badeball/cypress-cucumber-preprocessor");
 
       module.exports = async (on, config) => {
+        await addCucumberPreprocessorPlugin(on, config);
         on(
           "file:preprocessor",
           webpack({
@@ -44,6 +46,7 @@ Feature: webpack + typescript
             }
           })
         );
+        return config;
       };
       """
     And a file named "cypress/support/step_definitions/steps.ts" with:
diff --git a/features/setup.feature b/features/setup.feature
@@ -0,0 +1,34 @@
+@no-default-plugin
+Feature: setup
+  Scenario: missing addCucumberPreprocessorPlugin in setupNodeEvents
+    Given a file named "cypress/e2e/a.feature" with:
+      """
+      Feature: a feature name
+        Scenario: a scenario name
+          Given a step
+      """
+    And a file named "cypress/plugins/index.js" or "setupNodeEvents.js" (depending on Cypress era) with:
+      """
+      const createBundler = require("@bahmutov/cypress-esbuild-preprocessor");
+      const { createEsbuildPlugin } = require("@badeball/cypress-cucumber-preprocessor/esbuild");
+
+      module.exports = async (on, config) => {
+        on(
+          "file:preprocessor",
+          createBundler({
+            plugins: [createEsbuildPlugin(config)]
+          })
+        );
+      };
+      """
+    And a file named "cypress/support/step_definitions/steps.js" with:
+      """
+      import { Given } from "@badeball/cypress-cucumber-preprocessor";
+      Given("a step", function() {});
+      """
+    When I run cypress
+    Then it fails
+    And the output should contain
+      """
+      Missing preprocessor event handlers (this usally means you've not invoked `addCucumberPreprocessorPlugin()` or not returned the config object in `setupNodeEvents()`)
+      """
diff --git a/lib/add-cucumber-preprocessor-plugin.ts b/lib/add-cucumber-preprocessor-plugin.ts
@@ -28,6 +28,7 @@ import {
 import {
   HOOK_FAILURE_EXPR,
   INTERNAL_PROPERTY_NAME,
+  INTERNAL_SUITE_PROPERTIES,
   TASK_APPEND_MESSAGES,
   TASK_CREATE_STRING_ATTACHMENT,
   TASK_TEST_STEP_STARTED,
@@ -325,6 +326,8 @@ export default async function addCucumberPreprocessorPlugin(
   config: Cypress.PluginConfigOptions,
   options: AddOptions = {}
 ) {
+  config.env[INTERNAL_SUITE_PROPERTIES] = { isEventHandlersAttached: true };
+
   const preprocessor = await resolve(config, config.env, "/");
 
   if (!options.omitBeforeRunHandler) {
diff --git a/lib/constants.ts b/lib/constants.ts
@@ -10,5 +10,9 @@ export const TASK_CREATE_STRING_ATTACHMENT =
 export const INTERNAL_PROPERTY_NAME =
   "__cypress_cucumber_preprocessor_dont_use_this";
 
+export const INTERNAL_SPEC_PROPERTIES = INTERNAL_PROPERTY_NAME + "_spec";
+
+export const INTERNAL_SUITE_PROPERTIES = INTERNAL_PROPERTY_NAME + "_suite";
+
 export const HOOK_FAILURE_EXPR =
   /Because this error occurred during a `[^`]+` hook we are skipping all of the remaining tests\./;
diff --git a/lib/create-tests.ts b/lib/create-tests.ts
@@ -4,7 +4,7 @@ import parse from "@cucumber/tag-expressions";
 
 import { v4 as uuid } from "uuid";
 
-import { assertAndReturn } from "./assertions";
+import { assertAndReturn, fail } from "./assertions";
 
 import DataTable from "./data_table";
 
@@ -23,6 +23,8 @@ import { YieldType } from "./types";
 import {
   HOOK_FAILURE_EXPR,
   INTERNAL_PROPERTY_NAME,
+  INTERNAL_SPEC_PROPERTIES,
+  INTERNAL_SUITE_PROPERTIES,
   TASK_APPEND_MESSAGES,
   TASK_TEST_STEP_STARTED,
 } from "./constants";
@@ -83,16 +85,26 @@ interface IStep {
   pickleStep?: messages.PickleStep;
 }
 
-export interface InternalProperties {
+export interface InternalSpecProperties {
   pickle: messages.Pickle;
   testCaseStartedId: string;
   currentStep?: IStep;
   allSteps: IStep[];
   remainingSteps: IStep[];
 }
 
-function retrieveInternalProperties(): InternalProperties {
-  return Cypress.env(INTERNAL_PROPERTY_NAME);
+export interface InternalSuiteProperties {
+  isEventHandlersAttached?: boolean;
+}
+
+function retrieveInternalSpecProperties(): InternalSpecProperties {
+  return Cypress.env(INTERNAL_SPEC_PROPERTIES);
+}
+
+function retrieveInternalSuiteProperties():
+  | InternalSuiteProperties
+  | undefined {
+  return Cypress.env(INTERNAL_SUITE_PROPERTIES);
 }
 
 function findPickleById(context: CompositionContext, astId: string) {
@@ -339,14 +351,14 @@ function createPickle(
 
   let attempt = 0;
 
-  const internalProperties: InternalProperties = {
+  const internalProperties: InternalSpecProperties = {
     pickle,
     testCaseStartedId: uuid(),
     allSteps: steps,
     remainingSteps: [...steps],
   };
 
-  const internalEnv = { [INTERNAL_PROPERTY_NAME]: internalProperties };
+  const internalEnv = { [INTERNAL_SPEC_PROPERTIES]: internalProperties };
 
   const suiteOptions = tags
     .filter(looksLikeOptions)
@@ -360,7 +372,8 @@ function createPickle(
   }
 
   it(scenarioName, suiteOptions, function () {
-    const { remainingSteps, testCaseStartedId } = retrieveInternalProperties();
+    const { remainingSteps, testCaseStartedId } =
+      retrieveInternalSpecProperties();
 
     assignRegistry(registry);
 
@@ -686,10 +699,18 @@ export default function createTests(
     globalThis[INTERNAL_PROPERTY_NAME] = true;
   }
 
+  before(function () {
+    if (!retrieveInternalSuiteProperties()?.isEventHandlersAttached) {
+      fail(
+        "Missing preprocessor event handlers (this usally means you've not invoked `addCucumberPreprocessorPlugin()` or not returned the config object in `setupNodeEvents()`)"
+      );
+    }
+  });
+
   afterEach(function () {
     freeRegistry();
 
-    const properties = retrieveInternalProperties();
+    const properties = retrieveInternalSpecProperties();
 
     const { testCaseStartedId, remainingSteps } = properties;
 
diff --git a/lib/methods.ts b/lib/methods.ts
