@qavajs/cypress-runner-adapter 1.9.0 → 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

@@ -1,4 +1,5 @@
-const { ensureFileSync, writeFileSync, readFileSync } = require('fs-extra');
+const { mkdirSync, writeFileSync, readFileSync } = require('node:fs');
+const { dirname } = require('node:path');
 const { randomUUID } = require('node:crypto');
 const { AstBuilder, compile, GherkinClassicTokenMatcher, Parser } = require('@cucumber/gherkin');
 const webpackPreprocessor = require('@cypress/webpack-preprocessor')();
@@ -18,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);
     }
@@ -26,7 +27,7 @@ module.exports = async function cucumber(file) {
     const tagExpression = tagExpressionParser(process.env.TAGS || '');
     const testCases = compile(gherkinDocument, filePath, uuidFn)
         .filter(test => tagExpression.evaluate(test.tags.map(tag => tag.name)));
-    ensureFileSync(outputPath);
+    mkdirSync(dirname(outputPath), { recursive: true });
     writeFileSync(outputPath, adapter(testCases), 'utf-8');
     return outputPath;
 }

package/adapter/make_mocha_tests_it.js

@@ -155,7 +155,7 @@ module.exports = function makeMochaTest(tests) {
         it('Scenario: ' + test.name, function () {
             const world = this.world;
             for (const step of test.steps) {
-                runStep({ keyword: keyword(step), name: stepNameText(step) }, function () {
+                runStep({ keyword: keyword(step), name: stepNameText(step) }, () => {
                     this.step = step;
                     const result = { status: 'passed', duration: 0 };
                     for (const beforeStep of supportCodeLibrary.beforeTestStepHookDefinitions) {

package/adapter.d.ts

@@ -1 +1 @@
-export default function (file: any): void;
+export default function (file: any): Promise<any>;

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,6 +30,10 @@ 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;

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@qavajs/cypress-runner-adapter",
-  "version": "1.9.0",
-  "main": "index.js",
+  "version": "1.9.2",
+  "main": "supportCodeLibrary/index.js",
+  "exports": {
+    ".": "./supportCodeLibrary/index.js",
+    "./adapter": "./adapter/index.js"
+  },
+  "files": [
+    "adapter",
+    "supportCodeLibrary",
+    "index.d.ts",
+    "adapter.d.ts"
+  ],
   "scripts": {
     "debug": "cypress open --config-file test/cypress.config.js",
     "test": "cypress run --config-file test/cypress.config.js",
@@ -25,12 +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",
-    "fs-extra": "^11.3.4"
+    "@cypress/webpack-preprocessor": "^7.1.0"
   },
   "devDependencies": {
-    "cypress": "^15.11.0",
-    "mochawesome": "^7.1.4"
+    "cypress": "^15.13.0"
   },
   "keywords": [
     "cypress",
@@ -42,4 +50,4 @@
     "test",
     "test-automation"
   ]
-}
+}

package/supportCodeLibrary/data_table.js

@@ -47,6 +47,6 @@ export default class DataTable {
         const transposed = this.rawTable[0].map((x, i) =>
             this.rawTable.map((y) => y[i])
         )
-        return new Data_table(transposed)
+        return new DataTable(transposed)
     }
 }

package/supportCodeLibrary/index.js

@@ -52,8 +52,7 @@ export function Given(pattern, code) {
 }
 
 export function Before(optionsOrCode, code) {
-    const defaultOptions = { name: 'Before' };
-    const options = code ? Object.assign(defaultOptions, optionsOrCode) : defaultOptions;
+    const options = code ? Object.assign({ name: 'Before' }, optionsOrCode) : { name: 'Before' };
     const handler = code ?? optionsOrCode;
     supportCodeLibrary.beforeTestCaseHookDefinitions.push(new TestCaseHookDefinition({
         code: handler,
@@ -62,8 +61,7 @@ export function Before(optionsOrCode, code) {
 }
 
 export function After(optionsOrCode, code) {
-    const defaultOptions = { name: 'After' };
-    const options = code ? Object.assign(defaultOptions, optionsOrCode) : defaultOptions;
+    const options = code ? Object.assign({ name: 'After' }, optionsOrCode) : { name: 'After' };
     const handler = code ?? optionsOrCode;
     supportCodeLibrary.afterTestCaseHookDefinitions.push(new TestCaseHookDefinition({
         code: handler,

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/CHANGELOG.md

@@ -1,82 +0,0 @@
-# Change Log
-
-All notable changes to the "@qavajs/cypress-runner-adapter" will be documented in this file.
-
-Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
-
-:rocket: - new feature
-
-:beetle: - bugfix
-
-:x: - deprecation/removal
-
-:pencil: - chore
-
-:microscope: - experimental
-
-## [1.9.0]
-- :rocket: added step log groups for `it` mode
-
-## [1.8.0]
-- :rocket: added `testCaseStartedId` and `testStepId` as hooks parameters to comply cucumber spec
-
-## [1.7.0]
-- :rocket: updated @cucumber/cucumber-expressions, @cucumber/gherkin, @cucumber/tag-expressions
-
-## [1.6.0]
-- :rocket: updated logs for Gherkin steps
-- :rocket: improved multi line and data table step logging
-
-## [1.5.0]
-- :rocket: added `world.log` method
-- :rocket: updated test.body to render corresponding step code
-
-## [1.4.2]
-- :pencil: updated to cypress 15.7.0
-- :pencil: updated to gherkin to 37.0.0
-
-## [1.4.1]
-- :beetle: fixed `result` property in `After` and `AfterStep` hooks
-- :rocket: added workaround to complete `AfterStep` hook in case of step fail
-
-## [1.4.0]
-- :rocket: added `Template` utility function
-```typescript
-import { When, Template } from '@qavajs/playwright-runner-adapter';
-
-When('I click {string} and verify {string}', Template((locator, expected) => `
-    I click '${locator}'
-    I expect '${locator} > Value' to equal '${expected}'
-`));
-```
-
-## [1.3.0]
-- :rocket: added tags support
-- :rocket: added alternative 'it mode' to translate gherkin tests to mocha `it` instead of `describe`
-```bash
-MODE=it npx cypress open
-```
-
-## [1.2.1]
-- :pencil: updated to cypress 15.3
-
-## [1.2.0]
-- :pencil: updated to cypress 15
-
-## [1.1.0]
-- :pencil: updated to cypress 14
-
-## [1.0.1]
-- :pencil: updated dependencies
-
-## [1.0.0]
-- :rocket: added `this.executeStep` world method
-
-## [0.2.0]
-- :rocket: added _BeforeAll_ and _AfterAll_ hooks support
-
-## [0.1.1]
-- :beetle: changed browserify to webpack
-
-## [0.1.0]
-- :rocket: initial implementation

package/adapter.js

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

package/index.js

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