Replace diagnostics with a more proper dry-run

This is "more proper" in the sense that it's still executing tests an
actual Cypress environments, while still being reasonably quick.

This is related to #1120 [1].

This closes #1129 [2].

[1] #1120
[2] #1129

Author: badeball

CHANGELOG.md

@@ -10,9 +10,9 @@ Breaking changes:
 
   - User of `@badeball/cypress-cucumber-preprocessor/browserify` should change their Cypress config in accordance with the related [examples](examples).
 
-- The executable `cypress-cucumber-diagnostics` no longer respect flags such as `--project` or `--env`. The long-term plan is to rewamp dry run altogether, and run it in a Cypress environment.
+- The executable `cypress-cucumber-diagnostics` has been replaced by a [`dryRun` option](docs/dry-run.md).
 
-- `esbuild` is now an optional peer dependency. This is relevant for users using `esbuild` as their bundler, as well as users of `cypress-cucumber-diagnostics`.
+- `esbuild` is now an optional peer dependency. This is relevant for users using `esbuild` as their bundler.
 
 Other changees:
 

augmentations.d.ts

@@ -2,6 +2,8 @@ import messages from "@cucumber/messages";
 
 import { Registry } from "./lib/registry";
 
+import { MochaGlobals } from "mocha";
+
 declare module "@cucumber/cucumber" {
   interface IWorld {
     tmpDir: string;
@@ -25,6 +27,10 @@ declare global {
     var __cypress_cucumber_preprocessor_registry_dont_use_this:
       | Registry
       | undefined;
+
+    var __cypress_cucumber_preprocessor_mocha_dont_use_this:
+      | Pick<MochaGlobals, "before" | "beforeEach" | "after" | "afterEach">
+      | undefined;
   }
 
   interface Window {

docs/configuration.md

@@ -80,10 +80,13 @@ Every configuration option has a similar key which can be use to override it, sh
 | `json.output`          | `jsonOutput`           | `cucumber-report.json`                   |
 | `html.enabled`         | `htmlEnabled`          | `true`, `false`                          |
 | `html.output`          | `htmlOutput`           | `cucumber-report.html`                   |
+| `usage.enabled`        | `usageEnabled`         | `true`, `false`                          |
+| `usage.output`         | `usageOutput`          | `stdout`                                 |
 | `pretty.enabled`       | `prettyEnabled`        | `true`, `false`                          |
 | `filterSpecsMixedMode` | `filterSpecsMixedMode` | `hide`, `show`, `empty-set`              |
 | `filterSpecs`          | `filterSpecs`          | `true`, `false`                          |
 | `omitFiltered`         | `omitFiltered`         | `true`, `false`                          |
+| `dryRun`               | `dryRun`               | `true`, `false`                          |
 
 ## Test configuration
 

docs/diagnostics.md

@@ -0,0 +1,15 @@
+[← Back to documentation](readme.md)
+
+# Dry run
+
+Dry run is a run mode in which no steps or any type of hooks are executed. A few examples where this is useful:
+
+- Finding unused step definitions with [usage reports](usage-report.md)
+- Generating snippets for all undefined steps
+- Checking if your path, tag expression, etc. matches the scenarios you expect it to
+
+Dry run can be enabled using `dryRun`, like seen below.
+
+```
+$ cypress run --env dryRun=true
+```

docs/dry-run.md

@@ -7,15 +7,17 @@
 * [Step definitions](step-definitions.md)
 * [Tags](tags.md)
 * [Pretty output](pretty-output.md)
+* [Source maps](source-maps.md)
+* [Dry run](dry-run.md)
 * Reports
   * [Messages report](messages-report.md)
   * [JSON report](json-report.md)
   * [HTML report](html-report.md)
+  * [Usage report](usage-report.md)
 * [Localisation](localisation.md)
 * [Configuration](configuration.md)
 * [Test configuration](test-configuration.md)
 * CLI utilities
-  * [Diagnostics / dry run](diagnostics.md)
   * [JSON formatter](json-formatter.md)
   * [HTML formatter](html-formatter.md)
   * [Parallelization using Cypress Cloud & merging reports](merging-reports.md)

docs/readme.md

@@ -0,0 +1,50 @@
+[← Back to documentation](readme.md)
+
+# Source maps
+
+How to enable source maps for each bundler is shown below.
+
+## esbuild
+
+```js
+const { defineConfig } = require("cypress");
+const createBundler = require("@bahmutov/cypress-esbuild-preprocessor");
+const {
+  addCucumberPreprocessorPlugin,
+} = 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 addCucumberPreprocessorPlugin(on, config);
+
+  on(
+    "file:preprocessor",
+    createBundler({
+      plugins: [createEsbuildPlugin(config)],
+      sourcemap: "inline"
+    })
+  );
+
+  // Make sure to return the config object as it might have been modified by the plugin.
+  return config;
+}
+
+module.exports = defineConfig({
+  e2e: {
+    baseUrl: "https://duckduckgo.com",
+    specPattern: "**/*.feature",
+    setupNodeEvents,
+  },
+});
+```
+
+## Webpack
+
+Source maps are enabled by default.
+
+## Browserify
+
+Source maps are enabled by default.

docs/source-maps.md

@@ -0,0 +1,45 @@
+[← Back to documentation](readme.md)
+
+# Usage reports
+
+> :warning: This requires you to have [source maps](source-maps.md) enabled.
+
+The usage report lists your step definitions and tells you about usages in your scenarios, including the duration of each usage, and any unused steps. Here's an example of the output:
+
+```
+┌───────────────────────────────────────┬──────────┬─────────────────────────────────┐
+│ Pattern / Text                        │ Duration │ Location                        │
+├───────────────────────────────────────┼──────────┼─────────────────────────────────┤
+│ an empty todo list                    │ 760.33ms │ support/steps/steps.ts:6        │
+│   an empty todo list                  │ 820ms    │ features/empty.feature:4        │
+│   an empty todo list                  │ 761ms    │ features/adding-todos.feature:4 │
+│   an empty todo list                  │ 700ms    │ features/empty.feature:4        │
+├───────────────────────────────────────┼──────────┼─────────────────────────────────┤
+│ I add the todo {string}               │ 432.00ms │ support/steps/steps.ts:10       │
+│   I add the todo "buy some cheese"    │ 432ms    │ features/adding-todos.feature:5 │
+├───────────────────────────────────────┼──────────┼─────────────────────────────────┤
+│ my cursor is ready to create a todo   │ 53.00ms  │ support/steps/steps.ts:27       │
+│   my cursor is ready to create a todo │ 101ms    │ features/empty.feature:10       │
+│   my cursor is ready to create a todo │ 5ms      │ features/adding-todos.feature:8 │
+├───────────────────────────────────────┼──────────┼─────────────────────────────────┤
+│ no todos are listed                   │ 46.00ms  │ support/steps/steps.ts:15       │
+│   no todos are listed                 │ 46ms     │ features/empty.feature:7        │
+├───────────────────────────────────────┼──────────┼─────────────────────────────────┤
+│ the todos are:                        │ 31.00ms  │ support/steps/steps.ts:21       │
+│   the todos are:                      │ 31ms     │ features/adding-todos.feature:6 │
+├───────────────────────────────────────┼──────────┼─────────────────────────────────┤
+│ I remove the todo {string}            │ UNUSED   │ support/steps/steps.ts:33       │
+└───────────────────────────────────────┴──────────┴─────────────────────────────────┘
+```
+
+Usage reports can be enabled using the `usage.enabled` property. The preprocessor uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig), which means you can place configuration options in EG. `.cypress-cucumber-preprocessorrc.json` or `package.json`. An example configuration is shown below.
+
+```json
+{
+  "usage": {
+    "enabled": true
+  }
+}
+```
+
+The report is outputted to stdout (your console) by default, but can be configured to be written to a file through the `usage.output` property.