Improvde error messages upon missing step definitions

My hope is that this will give greater understanding into the
resolvement process and give the end-user some hints as to what might be
wrong. Fixes #763.

Author: badeball

features/step_definitions/cli_steps.ts

@@ -2,6 +2,7 @@ import util from "util";
 import { Given, When, Then } from "@cucumber/cucumber";
 import assert from "assert";
 import childProcess from "child_process";
+import { isPost10, isPre10 } from "../support/helpers";
 
 function execAsync(
   command: string
@@ -138,6 +139,18 @@ Then("the output should contain", function (content) {
   assert.match(this.lastRun.stdout, new RegExp(rescape(content)));
 });
 
+Then("if pre-v10, the output should contain", function (content) {
+  if (isPre10()) {
+    assert.match(this.lastRun.stdout, new RegExp(rescape(content)));
+  }
+});
+
+Then("if post-v10, the output should contain", function (content) {
+  if (isPost10()) {
+    assert.match(this.lastRun.stdout, new RegExp(rescape(content)));
+  }
+});
+
 Then("the output should match", function (content) {
   assert.match(this.lastRun.stdout, new RegExp(content));
 });

features/undefined_step.feature

@@ -1,6 +1,6 @@
 Feature: undefined Steps
 
-  Scenario:
+  Scenario: no files containing step definitions
     Given a file named "cypress/e2e/a.feature" with:
       """
       Feature: a feature name
@@ -9,7 +9,98 @@ Feature: undefined Steps
       """
     When I run cypress
     Then it fails
-    And the output should contain
+    And if pre-v10, the output should contain
       """
-      Step implementation missing for: an undefined step
+      Step implementation missing for "an undefined step".
+
+      We tried searching for files containing step definitions using the following search pattern templates:
+
+        - cypress/e2e/[filepath]/**/*.{js,mjs,ts,tsx}
+        - cypress/e2e/[filepath].{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These templates resolved to the following search patterns:
+
+        - cypress/e2e/a/**/*.{js,mjs,ts,tsx}
+        - cypress/e2e/a.{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These patterns matched **no files** containing step definitions. This almost certainly means that you have misconfigured `stepDefinitions`.
+      """
+    And if post-v10, the output should contain
+      """
+      Step implementation missing for "an undefined step".
+
+      We tried searching for files containing step definitions using the following search pattern templates:
+
+        - [filepath]/**/*.{js,mjs,ts,tsx}
+        - [filepath].{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These templates resolved to the following search patterns:
+
+        - cypress/e2e/a/**/*.{js,mjs,ts,tsx}
+        - cypress/e2e/a.{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These patterns matched **no files** containing step definitions. This almost certainly means that you have misconfigured `stepDefinitions`.
+      """
+
+  Scenario: step definitions exist, but none matching
+    Given a file named "cypress/e2e/a.feature" with:
+      """
+      Feature: a feature name
+        Scenario: a scenario name
+          Given an undefined step
+      """
+    And a file named "cypress/support/step_definitions/steps.js" with:
+      """
+      const { When } = require("@badeball/cypress-cucumber-preprocessor");
+      When("unused step definition", function() {});
+      """
+    When I run cypress
+    Then it fails
+    And if pre-v10, the output should contain
+      """
+      Step implementation missing for "an undefined step".
+
+      We tried searching for files containing step definitions using the following search pattern templates:
+
+        - cypress/e2e/[filepath]/**/*.{js,mjs,ts,tsx}
+        - cypress/e2e/[filepath].{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These templates resolved to the following search patterns:
+
+        - cypress/e2e/a/**/*.{js,mjs,ts,tsx}
+        - cypress/e2e/a.{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These patterns matched the following files:
+
+        - cypress/support/step_definitions/steps.js
+
+      However, none of these files contained a step definition matching "an undefined step".
+      """
+    And if post-v10, the output should contain
+      """
+      Step implementation missing for "an undefined step".
+
+      We tried searching for files containing step definitions using the following search pattern templates:
+
+        - [filepath]/**/*.{js,mjs,ts,tsx}
+        - [filepath].{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These templates resolved to the following search patterns:
+
+        - cypress/e2e/a/**/*.{js,mjs,ts,tsx}
+        - cypress/e2e/a.{js,mjs,ts,tsx}
+        - cypress/support/step_definitions/**/*.{js,mjs,ts,tsx}
+
+      These patterns matched the following files:
+
+        - cypress/support/step_definitions/steps.js
+
+      However, none of these files contained a step definition matching "an undefined step".
       """

lib/add-cucumber-preprocessor-plugin.ts

@@ -34,6 +34,17 @@ import { getTags } from "./environment-helpers";
 
 import { ensureIsAbsolute } from "./helpers";
 
+/**
+ * Work-around for the fact that some Cypress versions pre v10 were missing this property in their types.
+ */
+declare global {
+  namespace Cypress {
+    interface PluginConfigOptions {
+      testFiles: string[];
+    }
+  }
+}
+
 function memoize<T extends (...args: any[]) => any>(
   fn: T
 ): (...args: Parameters<T>) => ReturnType<T> {

lib/create-tests.ts

@@ -8,7 +8,13 @@ import { assertAndReturn } from "./assertions";
 
 import DataTable from "./data_table";
 
-import { assignRegistry, freeRegistry, IHook, Registry } from "./registry";
+import {
+  assignRegistry,
+  freeRegistry,
+  IHook,
+  MissingDefinitionError,
+  Registry,
+} from "./registry";
 
 import { collectTagNames, traverseGherkinDocument } from "./ast-helpers";
 
@@ -26,6 +32,7 @@ import { getTags } from "./environment-helpers";
 import { notNull } from "./type-guards";
 
 import { looksLikeOptions, tagToCypressOptions } from "./tag-parser";
+import { Context } from "mocha";
 
 declare global {
   namespace globalThis {
@@ -45,6 +52,11 @@ interface CompositionContext {
     enabled: boolean;
     stack: messages.IEnvelope[];
   };
+  stepDefinitionHints: {
+    stepDefinitions: string[];
+    stepDefinitionPatterns: string[];
+    stepDefinitionPaths: string[];
+  };
 }
 
 /**
@@ -134,6 +146,28 @@ function duration(
   };
 }
 
+function minIndent(content: string) {
+  const match = content.match(/^[ \t]*(?=\S)/gm);
+
+  if (!match) {
+    return 0;
+  }
+
+  return match.reduce((r, a) => Math.min(r, a.length), Infinity);
+}
+
+function stripIndent(content: string) {
+  const indent = minIndent(content);
+
+  if (indent === 0) {
+    return content;
+  }
+
+  const regex = new RegExp(`^[ \\t]{${indent}}`, "gm");
+
+  return content.replace(regex, "");
+}
+
 function createFeature(
   context: CompositionContext,
   feature: messages.GherkinDocument.IFeature
@@ -481,14 +515,24 @@ function createPickle(
             const ensureChain = (value: any): Cypress.Chainable<any> =>
               Cypress.isCy(value) ? value : cy.wrap(value, { log: false });
 
-            return ensureChain(
-              registry.runStepDefininition(this, text, argument)
-            ).then((result: any) => {
-              return {
-                start,
-                result,
-              };
-            });
+            try {
+              return ensureChain(
+                registry.runStepDefininition(this, text, argument)
+              ).then((result: any) => {
+                return {
+                  start,
+                  result,
+                };
+              });
+            } catch (e) {
+              if (e instanceof MissingDefinitionError) {
+                throw new Error(
+                  createMissingStepDefinitionMessage(context, text)
+                );
+              } else {
+                throw e;
+              }
+            }
           })
           .then(({ start, result }) => {
             const end = createTimestamp();
@@ -578,7 +622,12 @@ export default function createTests(
   gherkinDocument: messages.IGherkinDocument,
   pickles: messages.IPickle[],
   messagesEnabled: boolean,
-  omitFiltered: boolean
+  omitFiltered: boolean,
+  stepDefinitionHints: {
+    stepDefinitions: string[];
+    stepDefinitionPatterns: string[];
+    stepDefinitionPaths: string[];
+  }
 ) {
   const noopNode = { evaluate: () => true };
   const environmentTags = getTags(Cypress.env());
@@ -630,6 +679,7 @@ export default function createTests(
           enabled: messagesEnabled,
           stack: messages,
         },
+        stepDefinitionHints,
       },
       gherkinDocument.feature
     );
@@ -744,3 +794,82 @@ export default function createTests(
     }
   });
 }
+
+function strictIsInteractive(): boolean {
+  const isInteractive = Cypress.config(
+    "isInteractive" as keyof Cypress.ConfigOptions
+  );
+
+  if (typeof isInteractive === "boolean") {
+    return isInteractive;
+  }
+
+  throw new Error(
+    "Expected to find a Cypress configuration property `isInteractive`, but didn't"
+  );
+}
+
+function createMissingStepDefinitionMessage(
+  context: CompositionContext,
+  text: string
+) {
+  const noStepDefinitionPathsTemplate = `
+    Step implementation missing for "<text>".
+
+    We tried searching for files containing step definitions using the following search pattern templates:
+
+    <step-definitions>
+
+    These templates resolved to the following search patterns:
+
+    <step-definition-patterns>
+
+    These patterns matched **no files** containing step definitions. This almost certainly means that you have misconfigured \`stepDefinitions\`.
+  `;
+
+  const someStepDefinitionPathsTemplate = `
+    Step implementation missing for "<text>".
+
+    We tried searching for files containing step definitions using the following search pattern templates:
+
+    <step-definitions>
+
+    These templates resolved to the following search patterns:
+
+    <step-definition-patterns>
+
+    These patterns matched the following files:
+
+    <step-definition-paths>
+
+    However, none of these files contained a step definition matching "<text>".
+  `;
+
+  const { stepDefinitionHints } = context;
+
+  const template =
+    stepDefinitionHints.stepDefinitionPaths.length > 0
+      ? someStepDefinitionPathsTemplate
+      : noStepDefinitionPathsTemplate;
+
+  const maybeEscape = (string: string) =>
+    strictIsInteractive() ? string.replace("*", "\\*") : string;
+
+  const prettyPrintList = (items: string[]) =>
+    items.map((item) => "  - " + maybeEscape(item)).join("\n");
+
+  return stripIndent(template)
+    .replaceAll("<text>", text)
+    .replaceAll(
+      "<step-definitions>",
+      prettyPrintList(stepDefinitionHints.stepDefinitions)
+    )
+    .replaceAll(
+      "<step-definition-patterns>",
+      prettyPrintList(stepDefinitionHints.stepDefinitionPatterns)
+    )
+    .replaceAll(
+      "<step-definition-paths>",
+      prettyPrintList(stepDefinitionHints.stepDefinitionPaths)
+    );
+}

lib/step-definitions.ts

@@ -29,11 +29,11 @@ export async function getStepDefinitionPaths(
     cypress: ICypressConfiguration;
     preprocessor: IPreprocessorConfiguration;
   },
-  filepath: string
+  stepDefinitionPatterns: string[]
 ): Promise<string[]> {
   const files = (
     await Promise.all(
-      getStepDefinitionPatterns(configuration, filepath).map((pattern) =>
+      stepDefinitionPatterns.map((pattern) =>
         util.promisify(glob)(pattern, { nodir: true })
       )
     )