@qavajs/cypress 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -10,6 +10,21 @@ Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how
 :pencil: - chore
 :microscope: - experimental
 
+## [2.9.0]
+- :pencil: added TypeScript declaration files (`index.d.ts`, `po.d.ts`, `defineQavajs.d.ts`)
+- :pencil: added `tsconfig.json`
+- :pencil: added `types` and `exports` fields to `package.json`
+
+## [2.8.2]
+- :rocket: added `clickable` condition (checks element is visible and not disabled)
+- :beetle: fixed `validateAllOf` exiting after first successful match instead of validating all values
+- :beetle: fixed circular reference in `I expect {value} {validation} at least one of:` step
+- :beetle: fixed `execute` steps throwing generic JS error on invalid function string — now surfaces a descriptive message
+- :pencil: added `engines` field to `package.json` (`node >= 18`)
+
+## [2.8.1]
+- :beetle: fixed native selector logging to display `[function]` instead of function body
+
 ## [2.8.0]
 - :rocket: improved memory and page object logging
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @qavajs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,8 @@
 # @qavajs/cypress
-qavajs implementation for cypress runner
+[![npm](https://img.shields.io/npm/v/@qavajs/cypress)](https://www.npmjs.com/package/@qavajs/cypress)
+[![license](https://img.shields.io/npm/l/@qavajs/cypress)](LICENSE)
+
+Gherkin/BDD step definitions for web testing with Cypress. Part of the [qavajs](https://github.com/qavajs) framework.
 
 ## Installation
 
@@ -8,49 +11,235 @@ npm install @qavajs/cypress @qavajs/cypress-runner-adapter @qavajs/memory
 ```
 
 ## Configuration
-cypress.config.js
+
+**cypress.config.js**
 ```javascript
 const { defineConfig } = require('cypress');
 const cucumber = require('@qavajs/cypress-runner-adapter/adapter');
+
 module.exports = defineConfig({
     e2e: {
-        specPattern: 'cypress/features/**/*.feature', //path to features
-        supportFile: 'cypress/support/e2e.js', //path to main support file
+        specPattern: 'cypress/features/**/*.feature',
+        supportFile: 'cypress/support/e2e.js',
         setupNodeEvents(on, config) {
-            on('file:preprocessor', cucumber)
+            on('file:preprocessor', cucumber);
         },
     },
 });
-
 ```
-support file defines steps and loads qavajs entities (memory and page object)
+
+**cypress/support/e2e.js**
 ```typescript
 import defineQavajs from '@qavajs/cypress/defineQavajs';
 import '@qavajs/cypress';
 
-import PageObject from '../page_object/'; // path to qavajs page objects
-import Memory from '../memory'; // path to qavajs memory
+import PageObject from '../page_object';
+import Memory from '../memory';
 
 defineQavajs({
     pageObject: new PageObject(),
     memory: new Memory()
 });
+```
 
+## Page Objects
 
-```
+Page objects define element locators used in step definitions.
+
+```typescript
+import { locator } from '@qavajs/cypress/po';
+
+class Header {
+    Logo = locator('.logo');
+    Nav  = locator('nav');
+}
+
+export default class App {
+    // Simple CSS/XPath selector
+    SearchInput = locator('#search');
+    SearchButton = locator('#searchBtn');
+    Results = locator('.result-item');
+
+    // Parameterized selector
+    ResultByIndex = locator.template(idx => `.result-item:nth-child(${idx})`);
+
+    // Custom Cypress query
+    ActiveTab = locator.native(({ cy }) => cy.get('.tab').filter('.active'));
 
-## Development and testing
-Install dependencies
+    // Nested component
+    Header = locator('header').as(Header);
+}
 ```
-npm install
+
+Elements are referenced in steps by their property name (e.g. `'Search Input'` or `'Header > Logo'` for nested components).
+
+## Memory
+
+The memory class stores values accessible in steps via the `$key` syntax.
+
+```typescript
+export default class Memory {
+    baseUrl = 'https://example.com';
+    testUser = 'user@example.com';
+    // Functions are called on access
+    timestamp = () => Date.now();
+    uppercase = (str: string) => str.toUpperCase();
+}
 ```
 
-Execute tests
+Use `$key` in any step parameter to reference a memory value, `$key()` to call a function, and `$key.property` for nested access.
+
+---
+
+## Step Definitions
+
+### Navigation & Actions
+
+| Step | Description |
+|------|-------------|
+| `I open '{value}' url` | Navigate to a URL |
+| `I reload page` | Reload current page |
+| `I go back` | Browser back |
+| `I go forward` | Browser forward |
+| `I click '{locator}'` | Click an element |
+| `I force click '{locator}'` | Force-click (bypasses actionability checks) |
+| `I double click '{locator}'` | Double-click |
+| `I right click '{locator}'` | Right-click |
+| `I type '{value}' to '{locator}'` | Type text into an element |
+| `I type '{value}' into '{locator}'` | Alias for type |
+| `I clear '{locator}'` | Clear an input |
+| `I clear '{locator}' and type '{value}'` | Clear then type |
+| `I press '{value}' key` | Press a keyboard key or combo (e.g. `Enter`, `Control+C`) |
+| `I press '{value}' key {int} times` | Press key N times |
+| `I hover over '{locator}'` | Hover over element |
+| `I select '{value}' option from '{locator}' dropdown` | Select by text |
+| `I select {int} option from '{locator}' dropdown` | Select by index |
+| `I click '{value}' text in '{locator}' collection` | Click item in collection by text |
+| `I upload '{value}' to '{locator}'` | Upload a file |
+| `I scroll to '{locator}'` | Scroll element into view |
+| `I scroll by '{value}'` | Scroll page by `x, y` offset |
+| `I scroll by '{value}' in '{locator}'` | Scroll within element |
+
+### Alerts & Dialogs
+
+| Step | Description |
+|------|-------------|
+| `I will accept alert` | Accept the next alert |
+| `I will dismiss alert` | Dismiss the next alert |
+| `I will type '{value}' to alert` | Type into the next prompt |
+
+### Validations
+
+| Step | Description |
+|------|-------------|
+| `I expect '{locator}' {condition}` | Assert element condition (see Conditions) |
+| `I expect text of '{locator}' {validation} '{value}'` | Assert element text |
+| `I expect value of '{locator}' {validation} '{value}'` | Assert input value |
+| `I expect '{attr}' attribute of '{locator}' {validation} '{value}'` | Assert attribute |
+| `I expect '{prop}' property of '{locator}' {validation} '{value}'` | Assert property |
+| `I expect '{expr}' custom property of '{locator}' {validation} '{value}'` | Assert via JS function (e.g. `$js(e => e.prop('value'))`) |
+| `I expect '{prop}' css property of '{locator}' {validation} '{value}'` | Assert CSS property |
+| `I expect current url {validation} '{value}'` | Assert current URL |
+| `I expect page title {validation} '{value}'` | Assert page title |
+| `I expect number of elements in '{locator}' collection {validation} '{value}'` | Assert collection count |
+| `I expect every element in '{locator}' collection {condition}` | Assert all elements in collection |
+| `I expect text of alert {validation} '{value}'` | Assert alert text |
+
+**Conditions:** `to be visible`, `not to be visible`, `to be hidden`, `to be present`, `not to be present`, `to be enabled`, `to be disabled`, `to be in viewport`, `to be clickable`
+
+**Validations:** `equal`, `strictly equal`, `deeply equal`, `contain`, `match`, `above`, `below`, `greater than`, `less than`, `have type`, `have property`, `have member`, `include members`, `case insensitive equal`, `satisfy`
+
+### Memory Steps
+
+| Step | Description |
+|------|-------------|
+| `I save text of '{locator}' as '{key}'` | Save element text |
+| `I save value of '{locator}' as '{key}'` | Save input value |
+| `I save '{attr}' attribute of '{locator}' as '{key}'` | Save attribute value |
+| `I save '{prop}' property of '{locator}' as '{key}'` | Save property value |
+| `I save '{expr}' custom property of '{locator}' as '{key}'` | Save JS expression result |
+| `I save text of every element of '{locator}' collection as '{key}'` | Save array of texts |
+| `I save current url as '{key}'` | Save current URL |
+| `I save page title as '{key}'` | Save page title |
+| `I save bounding rect of '{locator}' as '{key}'` | Save element bounding rect |
+| `I save '{value}' to memory as '{key}'` | Store a literal value |
+| `I set '{key}' = '{value}'` | Alias for save to memory |
+| `I save json to memory as '{key}':` + docstring | Store a JSON object |
+| `I save key-value pairs to memory as '{key}':` + table | Store a map |
+| `I save multiline string to memory as '{key}':` + docstring | Store a multiline string |
+
+### Mouse Interactions
+
+| Step | Description |
+|------|-------------|
+| `I press {mouseButton} mouse button on '{value}'` | Press mouse button at `x, y` |
+| `I release {mouseButton} mouse button on '{value}'` | Release mouse button at `x, y` |
+| `I move mouse to '{value}'` | Move mouse to `x, y` |
+| `I scroll mouse wheel by '{value}' on '{value}'` | Scroll wheel at `x, y` |
+
+**Mouse buttons:** `left`, `right`, `middle`
+
+### JavaScript Execution
+
+| Step | Description |
+|------|-------------|
+| `I execute '{script}' function` | Execute JS in page context |
+| `I execute '{script}' function and save result as '{key}'` | Execute and save return value |
+| `I execute '{script}' function on '{locator}'` | Execute JS with element as `arguments[0]` |
+| `I execute '{script}' function on '{locator}' and save result as '{key}'` | Execute on element and save result |
+
+### Storage & Cookies
+
+| Step | Description |
+|------|-------------|
+| `I set '{name}' cookie '{value}'` | Set a cookie |
+| `I save value of '{name}' cookie as '{key}'` | Read a cookie |
+| `I set '{key}' local storage value as '{value}'` | Set localStorage item |
+| `I set '{key}' session storage value as '{value}'` | Set sessionStorage item |
+| `I save value of '{key}' local storage as '{memKey}'` | Read localStorage item |
+| `I save value of '{key}' session storage as '{memKey}'` | Read sessionStorage item |
+
+### HTTP Requests
+
+| Step | Description |
+|------|-------------|
+| `I create '{method}' request '{key}'` | Create HTTP request object (GET, POST, etc.) |
+| `I create GraphQL request '{key}'` | Create GraphQL request object |
+| `I add '{url}' url to '{request}'` | Set request URL |
+| `I add headers to '{request}':` + table | Add headers (key/value table) |
+| `I add body to '{request}':` + docstring | Set request body (JSON) |
+| `I add form data body to '{request}':` + table | Set multipart form data |
+| `I add query to GraphQL '{request}':` + docstring | Set GraphQL query |
+| `I add variables to GraphQL '{request}':` + docstring | Set GraphQL variables |
+| `I send '{request}' request and save response as '{key}'` | Send request and save response |
+
+---
+
+## Example Feature
+
+```gherkin
+Feature: Search
+
+  Scenario: User searches for a product
+    Given I open '$baseUrl' url
+    When I type 'laptop' to 'Search Input'
+    And I click 'Search Button'
+    Then I expect number of elements in 'Results' collection above '0'
+    And I save text of 'Results' as 'firstResult'
+    And I expect '$firstResult' to contain 'laptop'
 ```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
 npm run test
-```
 
-Debug tests
-```
+# Open Cypress GUI
 npm run debug
 ```

package/defineQavajs.d.ts

@@ -0,0 +1,27 @@
+/** Options passed to {@link defineQavajs} to wire up the qavajs runtime. */
+export interface QavajsOptions {
+    /** Root page-object instance or class used to resolve element aliases. */
+    pageObject: object;
+    /** Memory instance used for expression interpolation and value storage. */
+    memory: object;
+}
+
+/**
+ * Initialise the qavajs runtime by attaching the page-object and memory
+ * instances to the Cypress `window` object so step definitions can access them.
+ * Call this once in your Cypress support file before any tests run.
+ *
+ * @param options - Page-object and memory configuration.
+ *
+ * @example
+ * ```ts
+ * import defineQavajs from '@qavajs/cypress/defineQavajs';
+ * import App from './page_object';
+ * import Memory from './memory';
+ *
+ * defineQavajs({ pageObject: new App(), memory: new Memory() });
+ * ```
+ */
+export declare function defineQavajs(options: QavajsOptions): void;
+
+export default defineQavajs;

package/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Side-effect import that registers all qavajs Cucumber step definitions
+ * (actions, validations, memory, HTTP, mouse, storage, etc.) with the
+ * `@qavajs/cypress-runner-adapter` runtime.
+ *
+ * Import this once in your Cypress support file:
+ * ```ts
+ * import '@qavajs/cypress';
+ * ```
+ */
+export {};

package/lib/actions.js

@@ -68,7 +68,7 @@ When('I clear {locator}', function (locator) {
 
 /**
  * Refresh current page
- * @example I r efresh page
+ * @example I refresh page
  */
 When('I refresh page', function () {
     cy.reload();

package/lib/conditionExpect.js

@@ -1,3 +1,13 @@
+chai.Assertion.addMethod('beClickable', function () {
+    const subject = this._obj;
+    this.assert(
+        subject.is(':visible') && !subject.is(':disabled'),
+        'expected #{this} to be clickable',
+        'expected #{this} not to be clickable',
+        subject
+    );
+});
+
 chai.Assertion.addMethod('inViewport', function (ER) {
     const subject = this._obj;
 
@@ -21,6 +31,7 @@ chai.Assertion.addMethod('inViewport', function (ER) {
 
 export const conditionValidations = {
     PRESENT: 'present',
+    CLICKABLE: 'clickable',
     VISIBLE: 'visible',
     INVISIBLE: 'invisible',
     ENABLED: 'enabled',
@@ -37,6 +48,7 @@ export const conditionWaitRegexp = new RegExp(`(${notClause}${toBeClause}${valid
 
 const expects = {
     [conditionValidations.PRESENT]: 'exist',
+    [conditionValidations.CLICKABLE]: 'beClickable',
     [conditionValidations.VISIBLE]: 'be.visible',
     [conditionValidations.INVISIBLE]: 'be.hidden',
     [conditionValidations.ENABLED]: 'be.enabled',

package/lib/execute.js

@@ -1,5 +1,14 @@
 import { When } from '@qavajs/cypress-runner-adapter';
 
+function toFunction(fnContent) {
+    if (typeof fnContent !== 'string') return fnContent;
+    try {
+        return new Function(`return ${fnContent}`);
+    } catch (e) {
+        throw new Error(`Failed to parse function expression: "${fnContent}"\n${e.message}`);
+    }
+}
+
 /**
  * Execute client function
  * @param {string} functionKey - memory key of function
@@ -8,7 +17,7 @@ import { When } from '@qavajs/cypress-runner-adapter';
  */
 When('I execute {value} function', function (functionKey) {
     const fnContent = functionKey.value();
-    const fn = typeof fnContent === 'string' ? new Function(`return ${fnContent}`): fnContent;
+    const fn = toFunction(fnContent);
     cy.window().then(win => {
         fn.apply(win);
     });
@@ -23,7 +32,7 @@ When('I execute {value} function', function (functionKey) {
  */
 When('I execute {value} function and save result as {value}', function (functionKey, memoryKey) {
     const fnContent = functionKey.value();
-    const fn = typeof fnContent === 'string' ? new Function(`return ${fnContent}`): fnContent;
+    const fn = toFunction(fnContent);
     cy.window().then(win => {
         memoryKey.set(fn.apply(win));
     });
@@ -38,7 +47,7 @@ When('I execute {value} function and save result as {value}', function (function
  */
 When('I execute {value} function on {locator}', function (functionKey, locator) {
     const fnContent = functionKey.value();
-    const fn = typeof fnContent === 'string' ? new Function(`return ${fnContent}`): fnContent;
+    const fn = toFunction(fnContent);
     cy.window().then(win => {
         locator.then((e) => {
             fn.apply(win, e);
@@ -57,7 +66,7 @@ When(
     'I execute {value} function on {locator} and save result as {value}',
     function (functionKey, locator, memoryKey) {
         const fnContent = functionKey.value();
-        const fn = typeof fnContent === 'string' ? new Function(`return ${fnContent}`): fnContent;
+        const fn = toFunction(fnContent);
         cy.window().then(win => {
             locator.then((e) => {
                 memoryKey.set(fn.apply(win, e));

package/lib/pageObjects.js

@@ -86,7 +86,7 @@ export function element(path) {
         };
 
         const applyNative = (item) => {
-            logChain += `.native(${item.selector.toString()})`;
+            logChain += `.native([function])`;
             current = item.selector({
                 parent: current,
                 cy: this.cy,

package/lib/valueValidation.js

@@ -155,8 +155,7 @@ Then(
         cy.then(() => {
             const actualValue = actual.value();
             const expectedValues = dataTable2Array(this, expected);
-            const validation = (AR, ER) => valueExpect(AR, ER, validation);
-            validateAnyOf(actualValue, expectedValues, validation);
+            validateAnyOf(actualValue, expectedValues, valueExpect);
         });
 }
 );
@@ -222,7 +221,6 @@ function validateAllOf(AR, ERs, validation){
     for (const ER of ERs) {
         try {
             validation(AR, ER);
-            return;
         } catch (err) {
             errorCollector.push(err);
         }

package/package.json

@@ -1,8 +1,23 @@
 {
   "name": "@qavajs/cypress",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "qavajs for cypress runner",
   "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./po": {
+      "types": "./po.d.ts",
+      "default": "./po.js"
+    },
+    "./defineQavajs": {
+      "types": "./defineQavajs.d.ts",
+      "default": "./defineQavajs.js"
+    }
+  },
   "scripts": {
     "debug": "cypress open --config-file test-e2e/cypress.config.js",
     "debug:it": "MODE=it cypress open --config-file test-e2e/cypress.config.js",
@@ -28,9 +43,12 @@
   "homepage": "https://github.com/qavajs/cypress#readme",
   "author": "Alexandr Galichenko",
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
   "devDependencies": {
-    "@qavajs/cypress-runner-adapter": "^1.8.0",
-    "@qavajs/memory": "^1.10.3",
-    "cypress": "^15.11.0"
+    "@qavajs/cypress-runner-adapter": "^1.11.0",
+    "@qavajs/memory": "^1.11.0",
+    "cypress": "^15.15.0"
   }
 }

package/po.d.ts

@@ -0,0 +1,53 @@
+/** Determines how a selector is resolved against the DOM. */
+export type SelectorType = 'simple' | 'template' | 'native';
+
+/** Represents a page-object element definition. */
+export declare class Selector {
+    /** selector string */
+    selector: string | null;
+    /** Resolution strategy used when traversing the element chain. */
+    type: SelectorType;
+    /** Optional component class whose properties describe child elements. */
+    component?: new () => object;
+
+    constructor(selector: string | null, type?: SelectorType);
+
+    /**
+     * Attach a component class to this selector so its properties can be
+     * used as child element aliases.
+     * @param component - Component class whose instance defines child aliases.
+     */
+    as(component: new () => object): this;
+}
+
+export interface LocatorFn {
+    /**
+     * Create a simple selector entry.
+     * @param selector - Selector string.
+     */
+    (selector: string): Selector;
+
+    /**
+     * Create a template selector whose final value is produced by calling
+     * `Alias (argument)` at query time, allowing dynamic substitution.
+     * @param selector - Function that receives the runtime argument and returns the selector string.
+     */
+    template(selector: (argument: string) => string): Selector;
+
+    /**
+     * Create a native selector resolved via a custom Cypress command chain.
+     * The function receives context at query time and must return a Chainable.
+     * @param selector - Function that builds and returns a Cypress Chainable.
+     */
+    native(selector: (ctx: { parent: Cypress.Chainable; cy: Cypress.cy; argument: string }) => Cypress.Chainable): Selector;
+
+    /**
+     * Create a component-only node with no selector of its own.
+     * Useful when the root of a sub-tree is already in scope.
+     * @param component - Component class whose instance defines child aliases.
+     */
+    as(component: new () => object): Selector;
+}
+
+/** Factory for building page-object element definitions. */
+export declare const locator: LocatorFn;

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "strict": true,
+    "types": ["cypress"],
+    "noEmit": true
+  },
+  "include": ["*.d.ts"]
+}