Merge branch 'master' into HEAD

.gitignore

@@ -1,5 +1,6 @@
 **/*.js
 **/*.d.ts
+!examples/**/*
 !features/**/*
 !cucumber.d.ts
 !cucumber.js

README.md

@@ -11,15 +11,15 @@ See [badeball/cypress-cucumber-preprocessor](https://github.com/badeball/cypress
 The preprocessor (with its dependencies) parses Gherkin documents and allows you to write tests as shown below.
 
 ```cucumber
-# cypress/integration/duckduckgo.feature
+# cypress/e2e/duckduckgo.feature
 Feature: duckduckgo.com
   Scenario: visting the frontpage
     When I visit duckduckgo.com
     Then I should see a search bar
 ```
 
 ```ts
-// cypress/integration/duckduckgo.ts
+// cypress/e2e/duckduckgo.ts
 import { When, Then } from "@klaveness/cypress-cucumber-preprocessor";
 
 When("I visit duckduckgo.com", () => {

browserify.ts

@@ -4,7 +4,7 @@ import { EventEmitter } from "events";
 
 import browserify from "@cypress/browserify-preprocessor";
 
-import { ICypressConfiguration } from "@badeball/cypress-configuration";
+import { ICypressConfiguration } from "@klaveness/cypress-configuration";
 
 import debug from "./lib/debug";
 

declarations.d.ts

@@ -1 +1,3 @@
 declare module "@cypress/browserify-preprocessor";
+
+declare module "pngjs";

docs/configuration.md

@@ -0,0 +1,57 @@
+# Configuration
+
+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`, with corresponding examples shown below.
+
+```
+// .cypress-cucumber-preprocessorrc.json
+{
+  "json": {
+    "enabled": true
+  }
+}
+```
+
+```
+// package.json
+{
+  "dependencies": {
+    "@klaveness/cypress-cucumber-preprocessor": "latest"
+  },
+  "cypress-cucumber-preprocessor": {
+    "json": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## Configuration overrides
+
+Configuration options can be overriden using (Cypress-) [environment variable](https://docs.cypress.io/guides/guides/environment-variables). The `filterSpecs` options (described in [docs/tags.md](tags.md)) can for instance be overriden by running Cypress like shown below.
+
+```
+$ cypress run -e filterSpecs=true
+```
+
+Cypress environment variables can also be configured through ordinary environment variables, like shown below.
+
+```
+$ CYPRESS_filterSpecs=true cypress run
+```
+
+Every configuration option has a similar key which can be use to override it, shown in the table below.
+
+| JSON path          | Environment key   | Example(s)                               |
+|--------------------|-------------------|------------------------------------------|
+| `stepDefinitions`  | `stepDefinitions` | `[filepath].{js,ts}` |
+| `messages.enabled` | `messagesEnabled` | `true`, `false`                          |
+| `messages.output`  | `messagesOutput`  | `cucumber-messages.ndjson`               |
+| `json.enabled`     | `jsonEnabled`     | `true`, `false`                          |
+| `json.formatter`   | `jsonFormatter`   | `/usr/bin/cucumber-json-formatter`       |
+| `json.output`      | `jsonOutput`      | `cucumber-report.json`                   |
+| `filterSpecs`      | `filterSpecs`     | `true`, `false`                          |
+| `omitFiltered`     | `omitFiltered`    | `true`, `false`                          |
+
+## Test configuration
+
+Some of Cypress' [configuration options](https://docs.cypress.io/guides/references/configuration) can be overridden per-test, [Test configuration](test-configuration.md).

docs/faq.md

@@ -3,3 +3,15 @@
 ### `--env` / `tags` isn't picked up
 
 This might be because you're trying to specify `-e / --env` multiple times, but [multiple values should be comma-separated](https://docs.cypress.io/guides/guides/command-line#cypress-run-env-lt-env-gt).
+
+---
+
+### I get `fs_1.promises.rm is not a function`
+
+Upgrade your node version to at least [v14.14.0](https://nodejs.org/api/fs.html#fspromisesrmpath-options).
+
+---
+
+### I get `spawn cucumber-json-formatter ENOENT`
+
+You need to install `cucumber-json-formatter` **yourself**, as per [documentation](json-report.md).

docs/json-report.md

@@ -26,12 +26,16 @@ export default async (
 }
 ```
 
-This also **requires** you to have downloaded and installed the [cucumber-json-formatter](https://github.com/cucumber/common/tree/main/json-formatter) **yourself**. Arch Linux users can install it from [AUR](https://aur.archlinux.org/packages/cucumber-json-formatter).
+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).
 
 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`.
 
 The report is outputted to `cucumber-report.json` in the project directory, but can be configured through the `json.output` property.
 
+## Screenshots
+
+Screenshots are automatically added to JSON reports, including that of failed tests (unless you have disabled `screenshotOnRunFailure`).
+
 ## Attachments
 
 Text, images and other data can be added to the output of the messages and JSON reports with attachments.

docs/quick-start.md

@@ -4,12 +4,16 @@ See [badeball/cypress-cucumber-preprocessor](https://github.com/badeball/cypress
 
 # Configuration
 
-[Configure](https://docs.cypress.io/guides/references/configuration) `testFiles` with `"**/*.feature"`, using EG. `cypress.json`.
+[Configure](https://docs.cypress.io/guides/references/configuration) `specPattern` with `"**/*.feature"`, using EG. `cypress.config.ts`.
 
-```json
-{
-  "testFiles": "**/*.feature"
-}
+```js
+import { defineConfig } from "cypress";
+
+export default defineConfig({
+  e2e: {
+    specPattern: "**/*.feature"
+  }
+});
 ```
 
 Configure your preferred bundler to process features files, with examples for
@@ -18,20 +22,22 @@ Configure your preferred bundler to process features files, with examples for
 * [Webpack](../examples/webpack)
 * [Esbuild](../examples/esbuild)
 
+Read more about configuration options at [docs/configuration.md](configuration.md).
+
 # Write a test
 
-Write Gherkin documents anywhere in your configured integration folder (defaults to `cypress/integration`) and add a file for type definitions with a corresponding name (read more about how step definitions are resolved in [docs/step-definitions.md](step-definitions.md)). Reading [docs/cucumber-basics.md](cucumber-basics.md) is highly recommended.
+Write Gherkin documents and add a file for type definitions with a corresponding name (read more about how step definitions are resolved in [docs/step-definitions.md](step-definitions.md)). Reading [docs/cucumber-basics.md](cucumber-basics.md) is highly recommended.
 
 ```cucumber
-# cypress/integration/duckduckgo.feature
+# cypress/e2e/duckduckgo.feature
 Feature: duckduckgo.com
   Scenario: visting the frontpage
     When I visit duckduckgo.com
     Then I should see a search bar
 ```
 
 ```ts
-// cypress/integration/duckduckgo.ts
+// cypress/e2e/duckduckgo.ts
 import { When, Then } from "@klaveness/cypress-cucumber-preprocessor";
 
 When("I visit duckduckgo.com", () => {

docs/readme.md

@@ -7,4 +7,6 @@
 * [Tags](tags.md)
 * [JSON report](json-report.md)
 * [Localisation](localisation.md)
+* [Configuration](configuration.md)
+* [Test configuration](test-configuration.md)
 * [Frequently asked questions](faq.md)

docs/state-management.md

@@ -23,7 +23,7 @@ Please note that if you use arrow functions, you won’t be able to share state
 Even though `setWorldConstructor` isn't implemented, it's behavior can be closely replicated like shown below.
 
 ```gherkin
-# cypress/integration/math.feature
+# cypress/e2e/math.feature
 Feature: Replicating setWorldConstructor()
   Scenario: easy maths
     Given a variable set to 1
@@ -32,7 +32,7 @@ Feature: Replicating setWorldConstructor()
 ```
 
 ```ts
-// cypress/support/index.ts
+// cypress/support/e2e.ts
 beforeEach(function () {
   const world = {
     variable: 0,

docs/step-definitions.md

@@ -5,17 +5,17 @@ Step definitions are resolved using search paths that are configurable through t
 ```json
 {
   "stepDefinitions": [
-    "cypress/integration/[filepath]/**/*.{js,ts}",
-    "cypress/integration/[filepath].{js,ts}",
+    "[filepath]/**/*.{js,ts}",
+    "[filepath].{js,ts}",
     "cypress/support/step_definitions/**/*.{js,ts}",
   ]
 }
 ```
 
-This means that if you have a file `cypress/integration/duckduckgo.feature`, it will match step definitions found in
+This means that if you have a file `cypress/e2e/duckduckgo.feature`, it will match step definitions found in
 
-* `cypress/integration/duckduckgo/steps.ts`
-* `cypress/integration/duckduckgo.ts`
+* `cypress/e2e/duckduckgo/steps.ts`
+* `cypress/e2e/duckduckgo.ts`
 * `cypress/support/step_definitions/duckduckgo.ts`
 
 ## Hierarchy
@@ -25,14 +25,14 @@ There's also a `[filepart]` option available. Given a configuration shown below
 ```json
 {
   "stepDefinitions": [
-    "cypress/integration/[filepart]/step_definitions/**/*.{js,ts}"
+    "[filepart]/step_definitions/**/*.{js,ts}"
   ]
 }
 ```
 
-... and a feature file `cypress/integration/foo/bar/baz.feature`, the preprocessor would look for step definitions in
+... and a feature file `cypress/e2e/foo/bar/baz.feature`, the preprocessor would look for step definitions in
 
-* `cypress/integration/foo/bar/baz/step_definitions/**/*.{js,ts}`
-* `cypress/integration/foo/bar/step_definitions/**/*.{js,ts}`
-* `cypress/integration/foo/step_definitions/**/*.{js,ts}`
-* `cypress/integration/step_definitions/**/*.{js,ts}`
+* `cypress/e2e/foo/bar/baz/step_definitions/**/*.{js,ts}`
+* `cypress/e2e/foo/bar/step_definitions/**/*.{js,ts}`
+* `cypress/e2e/foo/step_definitions/**/*.{js,ts}`
+* `cypress/e2e/step_definitions/**/*.{js,ts}`

docs/tags.md

@@ -58,4 +58,6 @@ By default, all filtered tests are made *pending* using `it.skip` method. If you
 
 ## Smart tagging
 
-In the absence of a `tags` value and presence of a scenario with `@focus`, only said scenario will run. You can in other words use this tag as you would use `.only()` in Mocha.
+In the absence of a `tags` value and presence of a scenario with `@only`, only said scenario will run. You can in other words use this tag as you would use `.only()` in Mocha.
+
+Similarly, scenarios tagged with `@skip` will always be skipped, despite being tagged with something else matching a tag filter.

docs/test-configuration.md

@@ -0,0 +1,37 @@
+# Test configuration
+
+Some of Cypress' [configuration options](https://docs.cypress.io/guides/references/configuration) can be overridden per-test by leveraging tags. Below are all supported configuration options shown.
+
+```gherkin
+@animationDistanceThreshold(5)
+@blockHosts('http://www.foo.com','http://www.bar.com')
+@defaultCommandTimeout(5)
+@execTimeout(5)
+@includeShadowDom(true)
+@includeShadowDom(false)
+@keystrokeDelay(5)
+@numTestsKeptInMemory(5)
+@pageLoadTimeout(5)
+@redirectionLimit(5)
+@requestTimeout(5)
+@responseTimeout(5)
+@retries(5)
+@retries(runMode=5)
+@retries(openMode=5)
+@retries(runMode=5,openMode=10)
+@retries(openMode=10,runMode=5)
+@screenshotOnRunFailure(true)
+@screenshotOnRunFailure(false)
+@scrollBehavior('center')
+@scrollBehavior('top')
+@scrollBehavior('bottom')
+@scrollBehavior('nearest')
+@slowTestThreshold(5)
+@viewportHeight(720)
+@viewportWidth(1280)
+@waitForAnimations(true)
+@waitForAnimations(false)
+Feature: a feature
+  Scenario: a scenario
+    Given a table step
+```

esbuild.ts

@@ -1,6 +1,6 @@
 import esbuild from "esbuild";
 
-import { ICypressConfiguration } from "@badeball/cypress-configuration";
+import { ICypressConfiguration } from "@klaveness/cypress-configuration";
 
 import { compile } from "./lib/template";
 
@@ -25,3 +25,5 @@ export function createEsbuildPlugin(
     },
   };
 }
+
+export default createEsbuildPlugin;

examples/browserify-cjs/cypress.config.js

@@ -0,0 +1,20 @@
+const { defineConfig } = require("cypress");
+const preprocessor = require("@klaveness/cypress-cucumber-preprocessor");
+const browserify = require("@klaveness/cypress-cucumber-preprocessor/browserify");
+
+async function setupNodeEvents(on, config) {
+  await preprocessor.addCucumberPreprocessorPlugin(on, config);
+
+  on("file:preprocessor", browserify.default(config));
+
+  // Make sure to return the config object as it might have been modified by the plugin.
+  return config;
+}
+
+module.exports = defineConfig({
+  e2e: {
+    specPattern: "**/*.feature",
+    supportFile: false,
+    setupNodeEvents,
+  },
+});

examples/browserify-cjs/cypress/e2e/duckduckgo.js

@@ -0,0 +1,15 @@
+const { When, Then } = require("@klaveness/cypress-cucumber-preprocessor");
+
+When("I visit duckduckgo.com", () => {
+  cy.visit("https://duckduckgo.com/");
+});
+
+Then("I should see a search bar", () => {
+  cy.get("input").should(
+    "have.attr",
+    "placeholder",
+    "Search the web without being tracked"
+  );
+
+  assert.deepEqual({}, {});
+});

examples/browserify-cjs/package.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": {
+    "@klaveness/cypress-cucumber-preprocessor": "latest",
+    "@cypress/browserify-preprocessor": "latest",
+    "cypress": "latest"
+  }
+}