@qavajs/cypress-runner-adapter 1.9.1 → 1.10.0

package/README.md

@@ -1,5 +1,9 @@
 # @qavajs/cypress-runner-adapter
-Adapter to run Gherkin tests via cypress test runner
+
+Cypress preprocessor that compiles Gherkin `.feature` files into Cypress/Mocha test suites, enabling full BDD-style testing with Cucumber syntax inside Cypress.
+
+[![npm](https://img.shields.io/npm/v/@qavajs/cypress-runner-adapter)](https://www.npmjs.com/package/@qavajs/cypress-runner-adapter)
+[![license](https://img.shields.io/npm/l/@qavajs/cypress-runner-adapter)](LICENSE)
 
 ## Installation
 
@@ -7,7 +11,9 @@ Adapter to run Gherkin tests via cypress test runner
 npm install @qavajs/cypress-runner-adapter
 ```
 
-## Basic Configuration
+## Configuration
+
+Register the preprocessor in `cypress.config.js`:
 
 ```javascript
 const { defineConfig } = require('cypress');
@@ -18,39 +24,171 @@ module.exports = defineConfig({
         specPattern: 'cypress/feature/**/*.feature',
         supportFile: 'cypress/support/e2e.js',
         setupNodeEvents(on, config) {
-            on('file:preprocessor', cucumber)
+            on('file:preprocessor', cucumber);
         },
     },
 });
 ```
 
-`support/e2e.js` is entry point with step definition;
+## Step Definitions
+
+Define steps in your support file (e.g. `cypress/support/e2e.js`):
 
 ```javascript
-import { When, setWorldConstructor } from '@qavajs/cypress-runner-adapter';
+import { Given, When, Then, setWorldConstructor, World } from '@qavajs/cypress-runner-adapter';
 
-class World {
-    parameter = 42;
+class CustomWorld extends World {
+    constructor(options) {
+        super(options);
+        this.myValue = null;
+    }
 }
 
-setWorldConstructor(World);
+setWorldConstructor(CustomWorld);
 
-When('open {string} url', function (url) {
+Given('I navigate to {string}', function (url) {
     cy.visit(url);
 });
+
+When('I click {string}', function (selector) {
+    cy.get(selector).click();
+});
+
+Then('{string} should be visible', function (selector) {
+    cy.get(selector).should('be.visible');
+});
+```
+
+## Hooks
+
+All standard Cucumber hooks are supported. Hooks receive a `params` object with context about the current test.
+
+```javascript
+import { Before, After, BeforeStep, AfterStep, BeforeAll, AfterAll } from '@qavajs/cypress-runner-adapter';
+
+BeforeAll(function () {
+    // runs once before all tests
+});
+
+Before(function ({ gherkinDocument, pickle, testCaseStartedId }) {
+    // runs before each scenario
+});
+
+Before({ tags: '@login' }, function () {
+    // runs before scenarios tagged with @login
+});
+
+Before({ name: 'setup' }, function () {
+    // named hook
+});
+
+BeforeStep(function ({ testStepId }) {
+    // runs before each step
+});
+
+AfterStep(function ({ result }) {
+    // runs after each step
+});
+
+After(function ({ result, error }) {
+    // runs after each scenario
+});
+
+AfterAll(function () {
+    // runs once after all tests
+});
+```
+
+## Parameter Types
+
+Define custom parameter types using `defineParameterType`:
+
+```javascript
+import { defineParameterType } from '@qavajs/cypress-runner-adapter';
+
+defineParameterType({
+    name: 'color',
+    regexp: /(red|blue|green)/,
+    transformer: color => color.toUpperCase()
+});
+
+// usage in step definition:
+// When('I select {color} theme', function (color) { ... });
+```
+
+## World
+
+The `World` class is instantiated for each scenario and is available as `this` inside step definitions and hooks. Extend it to share state across steps within a scenario.
+
+| Property / Method | Description |
+|---|---|
+| `this.log(message)` | Log a message to the Cypress command log |
+| `this.attach(data)` | Attach data to the test report |
+| `this.link(url)` | Attach a link to the test report |
+| `this.executeStep(text)` | Programmatically execute a step by its text |
+
+```javascript
+import { When, World, setWorldConstructor } from '@qavajs/cypress-runner-adapter';
+
+class AppWorld extends World {
+    constructor(options) {
+        super(options);
+        this.userId = null;
+    }
+}
+
+setWorldConstructor(AppWorld);
+
+When('I store user {string}', function (id) {
+    this.userId = id;
+});
+
+When('I use stored user', function () {
+    cy.log(this.userId);
+});
+
+When('I execute another step', function () {
+    this.executeStep('I navigate to "https://example.com"');
+});
 ```
 
-## Tags
-Test can be filtered using Cucumber tag expressions provided via environment variable `TAGS`
+## Template Steps
+
+`Template` composes a step from other steps using a multiline string. The function receives the same arguments as the step and returns the steps to execute:
+
+```javascript
+import { When, Template } from '@qavajs/cypress-runner-adapter';
+
+When('I search for {string} on Wikipedia', Template(term => `
+    I navigate to 'https://en.wikipedia.org/'
+    I search '${term}'
+`));
 ```
-TAGS='@first and @second' npx cypress run
+
+## Tag Filtering
+
+Filter scenarios using Cucumber tag expressions via the `TAGS` environment variable:
+
+```bash
+TAGS='@smoke' npx cypress run
+TAGS='@smoke and not @slow' npx cypress run
+TAGS='@login or @auth' npx cypress run
 ```
 
-## Translation Mode
-Gherkin tests can be translated in different modes
-- `describe` - default mode. Scenario will be translated as `describe`, each step will be translated as `it`
-- `it` - Scenario will be translated as `it`
+## Translation Modes
+
+Controls how Gherkin scenarios are mapped to Mocha constructs. Set via the `MODE` environment variable.
+
+| Mode | Scenario maps to | Steps map to |
+|---|---|---|
+| `describe` (default) | `describe` | `it` |
+| `it` | `it` | _(inline)_ |
 
 ```bash
+# default (describe) mode
+npx cypress run
+
+# it mode
+MODE=it npx cypress run
 MODE=it npx cypress open
-```
+```

package/adapter/index.js

@@ -19,7 +19,7 @@ function adapter(testCases) {
 }
 
 module.exports = async function cucumber(file) {
-    const { filePath, outputPath, shouldWatch } = file;
+    const { filePath, outputPath } = file;
     if (!filePath.endsWith('.feature')) {
         return webpackPreprocessor(file);
     }

package/adapter/make_mocha_tests_describe.js

@@ -3,6 +3,21 @@ module.exports = function makeMochaTest(tests) {
         cy.log(data);
     }
 
+    function attach(data, options) {
+        const type = typeof options === 'string' ? options : options?.mediaType ? options.mediaType : 'text/plain';
+        const name = options?.name ?? 'attachment';
+        const src = typeof data === 'string' && data.startsWith('data:')
+            ? data
+            : `data:${type};base64,${btoa(unescape(encodeURIComponent(String(data))))}`;
+        cy.then(() => {
+            Cypress.log({
+                displayName: name,
+                message: type,
+                consoleProps: () => ({ name, src })
+            });
+        });
+    }
+
     function keyword(step) {
         switch (step.type) {
             case 'Context': return 'Given';
@@ -63,7 +78,7 @@ module.exports = function makeMochaTest(tests) {
         describe('Scenario: ' + test.name, { testIsolation: false }, function () {
             const world = new supportCodeLibrary.World({
                 log,
-                attach: log,
+                attach,
                 link: log
             });
             world.executeStep = executeStepByText;
@@ -72,12 +87,14 @@ module.exports = function makeMochaTest(tests) {
             let duration = 0;
             let exception;
             let message;
+            let willBeRetried = false;
             afterEach(function () {
                 if (this.currentTest.state !== 'passed') {
                     skip = true;
                 }
                 duration += this.currentTest.duration;
                 if (this.currentTest.state === 'failed') {
+                    willBeRetried = this.currentTest.currentRetry() < this.currentTest._retries;
                     status = this.currentTest.state;
                     exception = this.currentTest.err;
                     message = this.currentTest.err?.message;
@@ -150,7 +167,7 @@ module.exports = function makeMochaTest(tests) {
                                 message
                             },
                             gherkinDocument: tests,
-                            willBeRetried: false,
+                            willBeRetried,
                             testCaseStartedId: test.id,
                         }]);
                     });

package/adapter/make_mocha_tests_it.js

@@ -3,6 +3,21 @@ module.exports = function makeMochaTest(tests) {
         cy.log(data);
     }
 
+    function attach(data, options) {
+        const type = typeof options === 'string' ? options : options?.mediaType ? options.mediaType : 'text/plain';
+        const name = options?.name ?? 'attachment';
+        const src = typeof data === 'string' && data.startsWith('data:')
+            ? data
+            : `data:${type};base64,${btoa(unescape(encodeURIComponent(String(data))))}`;
+        cy.then(() => {
+            Cypress.log({
+                displayName: name,
+                message: type,
+                consoleProps: () => ({ name, src })
+            });
+        });
+    }
+
     function keyword(step) {
         switch (step.type) {
             case 'Context':
@@ -100,7 +115,7 @@ module.exports = function makeMochaTest(tests) {
         this.currentTest.body = renderGherkinTest(test.steps);
         const world = this.world = new supportCodeLibrary.World({
             log,
-            attach: log,
+            attach,
             link: log
         });
         for (const beforeTest of supportCodeLibrary.beforeTestCaseHookDefinitions) {
@@ -121,6 +136,7 @@ module.exports = function makeMochaTest(tests) {
         const test = findTest(tests, this.currentTest.title);
         const world = this.world;
         const result = getResult(this.currentTest);
+        const willBeRetried = result.status === 'failed' && this.currentTest.currentRetry() < this.currentTest._retries;
         // corner case to complete AfterStep if test is failed
         if (result.status === 'failed' && this.step) {
             for (const afterStep of supportCodeLibrary.afterTestStepHookDefinitions) {
@@ -144,7 +160,7 @@ module.exports = function makeMochaTest(tests) {
                         result,
                         gherkinDocument: tests,
                         testCaseStartedId: test.id,
-                        willBeRetried: false
+                        willBeRetried
                     }]);
                 });
             }

package/index.d.ts

@@ -13,7 +13,7 @@ declare type ParameterTypeOption = {
     transformer?: Function,
     useForSnippets?: boolean
 }
-declare interface IWorld {}
+export function defineStep(keyword: string, expression: Expression, fn: Function): void;
 export function Given(expression: Expression, fn: Function): void;
 export function When(expression: Expression, fn: Function): void;
 export function Then(expression: Expression, fn: Function): void;
@@ -29,12 +29,16 @@ export function BeforeAll(fn: Function): void;
 export function AfterAll(fn: Function): void;
 export function setWorldConstructor(world: IWorld): void;
 export function defineParameterType(option: ParameterTypeOption): void;
+export function setDefaultTimeout(milliseconds: number): void;
 export function Template(template: (...args: any[]) => string): () => void;
 export class World {
+    log: (...args: any) => void;
+    attach: (...args: any) => void;
+    link: (...args: any) => void;
+    executeStep(text: string, argument?: any): void;
     constructor(options: {
         log: (...args: any) => void;
         attach: (...args: any) => void;
         link: (...args: any) => void;
-        executeStep: (...args: any) => Promise<any>;
     });
 }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@qavajs/cypress-runner-adapter",
-  "version": "1.9.1",
-  "main": "index.js",
+  "version": "1.10.0",
+  "main": "supportCodeLibrary/index.js",
+  "exports": {
+    ".": "./supportCodeLibrary/index.js",
+    "./adapter": "./adapter/index.js"
+  },
   "files": [
     "adapter",
     "supportCodeLibrary",
-    "index.js",
     "index.d.ts",
-    "adapter.js",
     "adapter.d.ts"
   ],
   "scripts": {
@@ -31,13 +33,12 @@
   "homepage": "https://qavajs.github.io/docs/intro",
   "dependencies": {
     "@cucumber/cucumber-expressions": "^19.0.0",
-    "@cucumber/gherkin": "^39.0.0",
+    "@cucumber/gherkin": "^39.1.0",
     "@cucumber/tag-expressions": "^9.1.0",
-    "@cypress/webpack-preprocessor": "^7.0.2"
+    "@cypress/webpack-preprocessor": "^7.1.0"
   },
   "devDependencies": {
-    "cypress": "^15.12.0",
-    "mochawesome": "^7.1.4"
+    "cypress": "^15.14.2"
   },
   "keywords": [
     "cypress",

package/supportCodeLibrary/index.js

@@ -108,6 +108,10 @@ export function defineParameterType(options) {
     supportCodeLibrary.parameterTypeRegistry.defineSourcedParameterType(parameterType, {})
 }
 
+export function setDefaultTimeout(milliseconds) {
+    Cypress.config('defaultCommandTimeout', milliseconds);
+}
+
 /**
  * Define template step
  * @param {() => string} scenario - multiline string with steps

package/supportCodeLibrary/sourced_parameter_type_registry.js

@@ -13,8 +13,4 @@ export class SourcedParameterTypeRegistry extends ParameterTypeRegistry {
         this.defineParameterType(parameterType)
         this.parameterTypeToSource.set(parameterType, source)
     }
-
-    lookupSource(parameterType) {
-        return this.parameterTypeToSource.get(parameterType)
-    }
 }

package/supportCodeLibrary/step_definition.js

@@ -21,8 +21,6 @@ export default class StepDefinition extends Definition {
             parameters.push(argumentParameter)
         }
         return {
-            getInvalidCodeLengthMessage: () =>
-                this.baseGetInvalidCodeLengthMessage(parameters),
             parameters,
             validCodeLengths: [parameters.length, parameters.length + 1],
         }

package/supportCodeLibrary/test_case_hook_definition.js

@@ -5,7 +5,7 @@ export default class TestCaseHookDefinition extends Definition {
 
     constructor(data) {
         super(data)
-        this.name = data.options.name
+        this.name = data.options.name ?? 'Hook'
         this.tagExpression = data.options.tags
         this.pickleTagFilter = new PickleTagFilter(data.options.tags)
     }
@@ -13,13 +13,4 @@ export default class TestCaseHookDefinition extends Definition {
     appliesToTestCase(pickle) {
         return this.pickleTagFilter.matchesAllTagExpressions(pickle)
     }
-
-    async getInvocationParameters({ hookParameter }) {
-        return {
-            getInvalidCodeLengthMessage: () =>
-                this.buildInvalidCodeLengthMessage('0 or 1', '2'),
-            parameters: [hookParameter],
-            validCodeLengths: [0, 1, 2],
-        }
-    }
 }

package/supportCodeLibrary/test_step_hook_definition.js

@@ -11,13 +11,4 @@ export default class TestStepHookDefinition extends Definition {
     appliesToTestCase(pickle) {
         return this.pickleTagFilter.matchesAllTagExpressions(pickle)
     }
-
-    async getInvocationParameters({ hookParameter }) {
-        return {
-            getInvalidCodeLengthMessage: () =>
-                this.buildInvalidCodeLengthMessage('0 or 1', '2'),
-            parameters: [hookParameter],
-            validCodeLengths: [0, 1, 2],
-        }
-    }
 }

package/adapter.js

@@ -1 +0,0 @@
-module.exports = require('./adapter/index');

package/index.js

@@ -1 +0,0 @@
-module.exports = require('./supportCodeLibrary');