@qavajs/cypress-runner-adapter 1.9.1 → 1.9.2

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/index.d.ts

@@ -13,7 +13,6 @@ declare type ParameterTypeOption = {
     transformer?: Function,
     useForSnippets?: boolean
 }
-declare interface IWorld {}
 export function Given(expression: Expression, fn: Function): void;
 export function When(expression: Expression, fn: Function): void;
 export function Then(expression: Expression, fn: Function): void;
@@ -31,10 +30,13 @@ export function setWorldConstructor(world: IWorld): void;
 export function defineParameterType(option: ParameterTypeOption): 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.9.2",
+  "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": {
@@ -33,11 +35,10 @@
     "@cucumber/cucumber-expressions": "^19.0.0",
     "@cucumber/gherkin": "^39.0.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.13.0"
   },
   "keywords": [
     "cypress",

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');