@vardot/varbase-e2e 2.0.0

package/docs/advanced-screenshots.md

@@ -0,0 +1,52 @@
+
+# Advanced Screenshots
+
+## Overview
+
+This documentation page covers screenshot capture functionality in Varbase E2E 2.0.x. The feature enables testers to capture PNG screenshots during Cucumber scenarios using Playwright, supporting fullscreen, custom viewport, and named captures.
+
+## Key Features
+
+**Auto-capture hooks** activate screenshots in two scenarios:
+- On failed steps (with `failedPrefix` prepended)
+- On every step when scenarios are tagged `@screenshots`
+
+**Filename tokens** can be used in `with name "..."` steps or configuration keys like `filenamePattern` and `filenamePatternFailed`.
+
+## Configuration
+
+Settings reside in `cucumber.js` under `worldParameters.screenshot`. Each key accepts environment variable overrides:
+
+```javascript
+worldParameters: {
+  screenshot: {
+    dir: './screenshots',
+    purge: false,
+    onFailed: true,
+    onEveryStep: false,
+    alwaysFullscreen: false,
+    failedPrefix: 'failed_',
+    filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
+    filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
+    infoTypes: '',
+  },
+}
+```
+
+## Priority Chain
+
+1. Environment variables (`VARBASE_E2E_SCREENSHOT_*`)
+2. cucumber.js project defaults
+3. Built-in defaults
+
+## Output
+
+Each capture generates two files:
+- `.png` — Screenshot via Playwright
+- `.html` — Raw page HTML with optional metadata
+
+## Sub-pages
+
+- [Then I save "width" x "height" screenshot](/docs/varbase-e2e/2.0.x/advanced-screenshots/then-i-save-width-x-height-screenshot)
+- [Then I save fullscreen screenshot](/docs/varbase-e2e/2.0.x/advanced-screenshots/then-i-save-fullscreen-screenshot)
+- [When I save screenshot with name "filename"](/docs/varbase-e2e/2.0.x/advanced-screenshots/when-i-save-screenshot-name-filename)

package/docs/advanced-selectors.md

@@ -0,0 +1,18 @@
+
+# Advanced Selectors
+
+## Overview
+
+This documentation page describes a unified selector system for Varbase E2E 2.0.x that consolidates CSS selectors, XPath selectors, layout components, viewport breakpoints, and relative-position assertions into a single module.
+
+## Key Features
+
+The advanced selectors system unifies multiple selector types through these capabilities:
+
+- **Unified Resolution**: Combines CSS and XPath selectors with consistent priority ordering where "css → xpath" applies, with latest registration overriding previous entries for identical names.
+
+- **Auto-Retrying Assertions**: Replaces manual visibility checks with "Playwright's auto-retrying wait states" rather than legacy DOM inspection methods.
+
+- **Accessibility-First Locators**: Leverages Playwright semantic helpers like `getByLabel`, `getByPlaceholder`, and `getByRole()` chained via `.or()` to match user interaction patterns.
+
+- **Standardized Breakpoints**: Implements xs/sm/md/lg/xl/xxl/xxxl viewport scales aligned with Bootstrap 5.3 conventions.

package/docs/api-step-definitions.md

@@ -0,0 +1,45 @@
+
+# API Step Definitions
+
+## Overview
+
+varbase-e2e ships native HTTP / REST API step definitions powered by
+Playwright's request fixture and `axios`. They share the browser
+context's cookie jar so the same scenario can mix UI actions and
+direct API calls.
+
+## Available API Step Definitions
+
+The documentation lists 22 distinct step definition categories:
+
+**Authentication & Headers:**
+- Given I am authenticating as "username" with "pa$$word" password
+- Given I set header "Header-Name" with value "Some-Value"
+- Given I set the following headers
+- Given I set the header "Header-Name" to "Header-Value"
+
+**Request Configuration:**
+- Given I set placeholder "{{placeholder}}" to "value"
+- Given I set the request body to 'JSON-data'
+- Given I set the request body with
+- Given the API base URL is "url"
+
+**HTTP Methods:**
+- When I send a METHOD request to "endpoint"
+- When I send a METHOD request to "endpoint" with body
+- When I send a METHOD request to "endpoint" with form data
+- When I send a METHOD request to "endpoint" with values
+
+**Response Assertions:**
+- Then print API response
+- Then the API response code should be {number}
+- Then the API response should contain "text"
+- Then the API response should contain json
+- Then the API response should not contain "text"
+- Then the response should be valid JSON
+- Then the response header "response header" should be "value"
+
+**JSON Response Validation:**
+- Then the JSON response should have "propertyPath" equal to "value"
+- Then the JSON response should have property "propertyPath"
+- Then the JSON response should not have property "propertyPath"

package/docs/global-settings.md

@@ -0,0 +1,267 @@
+# Global Settings
+
+Varbase E2E draws settings from three layers, evaluated in this order:
+
+1. **Environment variables** (CI / shell) — highest precedence.
+2. **`worldParameters` in `cucumber.js`** — project-level defaults.
+3. **Built-in defaults** — sane fallbacks shipped with the library.
+
+This page documents every supported setting plus its env-var override.
+
+---
+
+## Top-level `cucumber.js` keys
+
+| Key | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `timeout` | int (ms) | `30000` | Per-step timeout enforced by `setDefaultTimeout`. |
+| `requireModule` | array | `['ts-node/register']` | TypeScript runtime support. |
+| `require` | array | step-definition globs | Files Cucumber-js loads at startup. |
+| `paths` | array | `['tests/features/**/*.feature']` | Where to find feature files. |
+| `format` | array | pretty + JSON report | Output formatters. |
+| `formatOptions` | object | colour theme | Pretty-formatter colours. |
+| `worldParameters` | object | (sections below) | Everything passed to the Playwright World. |
+
+Single profile: `default`. Run with:
+
+```bash
+npx cucumber-js
+```
+
+To enable `parallel`, `retry`, or `retryTagFilter`, add them inside the
+`default` block (or pass `--parallel N`, `--retry N`, `--retry-tag-filter @flaky`
+on the command line).
+
+---
+
+## `worldParameters` — runtime configuration
+
+### `launchUrl`
+
+| Type | Default | Env override |
+| --- | --- | --- |
+| string | `http://localhost:8080` | `LAUNCH_URL` |
+
+Base URL prepended to every relative path in `Given I am on "/path"`.
+
+### `assetsFolder`
+
+Resolved automatically to `tests/assets/`. Used by `When I attach the
+file "...".`. Override per-World by extending the world constructor;
+no env var.
+
+### `minWaitTime` — pacing knobs
+
+```js
+minWaitTime: {
+  page: 3000,             // ms — page-settle budget for navigation steps
+  before_scenario: 0,     // ms — sleep before each Scenario starts
+  after_scenario: 0,      // ms — sleep after each Scenario ends
+  before_step: 0,         // ms — sleep before each Step
+  after_step: 0,          // ms — sleep after each Step
+}
+```
+
+| Key | Default | Purpose |
+| --- | --- | --- |
+| `page` | `3000` | Per-navigation budget for `smartSettle`. Bump for slow CI. |
+| `before_scenario` | `0` | Forces a fixed delay before each Scenario. Default off — BBR auto-settle replaces it. |
+| `after_scenario` | `0` | Same, after Scenario ends. |
+| `before_step` | `0` | Per-step sleep. Use only for visual debugging. |
+| `after_step` | `0` | Same, after each step. |
+
+> Best practice: leave the four `*_scenario` / `*_step` keys at `0` —
+> the BBR auto-settle hook handles real timing. Only raise them when
+> demoing a recording in headed mode.
+
+### `selectors` — named selector registry
+
+```js
+selectors: {
+  css: { /* name → CSS selector */ },
+  xpath: { /* name → XPath expression */ },
+  filesPath: './tests/selectors/',  // base path for JSON presets
+  files: [],                         // JSON files to auto-load per scenario
+  offset: 60,                        // px — scroll offset for relative-position assertions
+  breakpoints: {                     // viewport sizes (used by responsive.steps.js)
+    xs:   { width: 375,  height: 667  },
+    sm:   { width: 576,  height: 800  },
+    md:   { width: 768,  height: 1024 },
+    lg:   { width: 992,  height: 768  },
+    xl:   { width: 1200, height: 900, default: true },
+    xxl:  { width: 1400, height: 900  },
+    xxxl: { width: 1920, height: 1080 },
+  },
+}
+```
+
+| Key | Default | Env override |
+| --- | --- | --- |
+| `css` | `{}` | — |
+| `xpath` | `{}` | — |
+| `filesPath` | `./tests/selectors/` | — |
+| `files` | `[]` | — |
+| `offset` | `60` | `VARBASE_E2E_SELECTORS_OFFSET` |
+| `breakpoints` | xs..xxxl | `VARBASE_E2E_SELECTORS_BREAKPOINTS` (JSON string) |
+
+### `screenshot` — capture configuration
+
+```js
+screenshot: {
+  dir: './screenshots',
+  purge: false,
+  onFailed: true,
+  onEveryStep: false,
+  alwaysFullscreen: false,
+  failedPrefix: 'failed_',
+  filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
+  filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
+  infoTypes: '',
+}
+```
+
+| Key | Default | Env override |
+| --- | --- | --- |
+| `dir` | `./screenshots` | `VARBASE_E2E_SCREENSHOT_DIR` |
+| `purge` | `false` | `VARBASE_E2E_SCREENSHOT_PURGE` |
+| `onFailed` | `true` | `VARBASE_E2E_SCREENSHOT_ON_FAILED` |
+| `onEveryStep` | `false` | `VARBASE_E2E_SCREENSHOT_ON_EVERY_STEP` |
+| `alwaysFullscreen` | `false` | `VARBASE_E2E_SCREENSHOT_FULLSCREEN` |
+| `failedPrefix` | `failed_` | `VARBASE_E2E_SCREENSHOT_FAILED_PREFIX` |
+| `filenamePattern` | `{datetime}...` | `VARBASE_E2E_SCREENSHOT_PATTERN` |
+| `filenamePatternFailed` | `{failed_prefix}...` | `VARBASE_E2E_SCREENSHOT_PATTERN_FAIL` |
+| `infoTypes` | `''` | `VARBASE_E2E_SCREENSHOT_INFO_TYPES` (e.g. `"url,feature,step,datetime"`) |
+
+Filename pattern tokens: `{datetime}`, `{date}`, `{time}`, `{feature_file}`,
+`{feature}`, `{scenario}`, `{step_line}`, `{ext}`, `{failed_prefix}`,
+`{url}`, `{host}`, `{path}`.
+
+### `video` — Playwright video recording
+
+```js
+video: {
+  mode: 'off',                                   // VARBASE_E2E_VIDEO — 'off' | 'on' | 'on-failure' | 'tag'
+  dir: './videos',                               // VARBASE_E2E_VIDEO_DIR
+  size: { width: 1280, height: 720 },            // recording viewport
+  filenamePattern: '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
+}
+```
+
+Tag overrides per scenario:
+
+| Tag | Effect |
+| --- | --- |
+| `@video` | Force recording on. |
+| `@no-video` | Suppress recording. |
+
+Modes:
+
+| Mode | Behaviour |
+| --- | --- |
+| `off` (default) | No recording. |
+| `on` | Record every scenario. |
+| `on-failure` | Record every scenario, keep only failures. |
+| `tag` | Record only scenarios tagged `@video`. |
+
+Mid-scenario start / stop steps live in `video.steps.js`. Recording starts at context creation only — `When I start video recording` closes + reopens the context, losing page state. Call before any navigation.
+
+### `javascript` — page-error / console capture
+
+```js
+javascript: {
+  mode: 'warn',                  // VARBASE_E2E_JS_ERROR_MODE — 'warn' | 'fail' | 'off'
+  levels: ['error'],             // VARBASE_E2E_JS_ERROR_LEVELS (csv) — console levels to capture
+  ignore: '',                    // VARBASE_E2E_JS_ERROR_IGNORE — regex of messages to drop
+  beforeScenario: false,         // VARBASE_E2E_JS_ERROR_BEFORE — snapshot pre-existing errors
+  afterScenario: true,           // VARBASE_E2E_JS_ERROR_AFTER — report at scenario end
+}
+```
+
+Tags override `mode` per scenario:
+
+| Tag | Effect |
+| --- | --- |
+| `@js-fail` / `@javascript` (legacy) | force `fail` |
+| `@js-warn` | force `warn` |
+| `@js-off` / `@js-errors` (legacy) | force `off` |
+
+The explicit step `Then there should be no JavaScript errors` always asserts (independent of mode).
+
+---
+
+## `playwright.config.ts` — browser launch
+
+```ts
+const config = {
+  browser: process.env.BROWSER || 'chromium',
+  launchOptions: {
+    headless: process.env.HEADLESS !== 'false',
+    slowMo: parseInt(process.env.SLOW_MO || '300', 10),
+    args: [...],
+  },
+  contextOptions: {
+    viewport: null,
+    ignoreHTTPSErrors: true,
+  },
+};
+```
+
+| Key | Default | Env override |
+| --- | --- | --- |
+| `browser` | `chromium` | `BROWSER` (`chromium` / `firefox` / `webkit`) |
+| `launchOptions.headless` | `true` | `HEADLESS=false` for headed |
+| `launchOptions.slowMo` | `300` headed: `800` | `SLOW_MO` (ms) |
+| `launchOptions.args` | chromium-only flags | edit file directly |
+| `contextOptions.viewport` | `null` (use browser default) | edit file directly |
+| `contextOptions.ignoreHTTPSErrors` | `true` | edit file directly |
+
+---
+
+## Behaviour toggles
+
+| Env var | Effect |
+| --- | --- |
+| `VARBASE_E2E_AUTO_SETTLE` | Set to `off` to disable the BBR auto-settle hook (`smartSettle(page, 1500)` after every state-changing step). |
+| `VARBASE_E2E_REPORT_DISABLE` | Set to `1` to skip auto-generating the HTML report on cucumber-js process exit. |
+| `VARBASE_E2E_REPORT_ARGS` | Extra CLI flags forwarded to `bin/generate-reports.js`. e.g. `--theme hierarchy --layout 2`. |
+
+---
+
+## Run / pacing env vars
+
+| Env var | Default | Effect |
+| --- | --- | --- |
+| `LAUNCH_URL` | `http://localhost:8080` | Base URL for navigation steps. |
+| `BROWSER` | `chromium` | Browser engine. |
+| `HEADLESS` | `true` | `false` opens a visible browser. |
+| `SLOW_MO` | `300` (headed: `800`) | Per-action delay (ms). Set to `0` for fast runs. |
+
+---
+
+## npm scripts
+
+| Script | Description |
+| --- | --- |
+| `npm test` | Default profile, full pretty output, slow-mo on. |
+| `npm run test:headed` | `HEADLESS=false`. Watches the browser. |
+| `npm run test:fast` | `SLOW_MO=0` on the default profile. |
+| `npm run test:chromium` | `BROWSER=chromium npm test`. |
+| `npm run test:firefox` | `BROWSER=firefox npm test`. |
+| `npm run test:webkit` | `BROWSER=webkit npm test`. |
+| `npm start` | Static dev server on port 8080 (`http-server examples`). |
+| `npm run generate-reports` | Manually rebuild the HTML report from the JSON output. |
+
+---
+
+## Recipe — typical CI lane
+
+```bash
+LAUNCH_URL=https://staging.example.com \
+SLOW_MO=0 \
+BROWSER=chromium \
+VARBASE_E2E_SCREENSHOT_PURGE=1 \
+npx cucumber-js --tags "@critical and not @wip" --parallel 4 --retry 1 --retry-tag-filter @flaky
+```
+
+Translation: zero slow-mo, 4 parallel processes, retry `@flaky` once,
+fresh `screenshots/` each run, only `@critical` (excluding work-in-progress).

package/docs/install-varbase-e2e/ddev-varbase-e2e.md

@@ -0,0 +1,52 @@
+
+# DDEV Varbase E2E
+
+## Overview
+
+This add-on integrates "Varbase E2E — a Playwright + Cucumber-JS Automated Functional Acceptance Testing framework" into DDEV projects, enabling automated browser testing via Gherkin `.feature` files within the DDEV environment.
+
+## Installation
+
+Execute the command to add and configure the tool:
+
+```
+ddev add-on get Vardot/ddev-varbase-e2e
+```
+
+The installation automatically scaffolds required configuration files, creates a starter feature file, installs Playwright browsers, and restarts the DDEV environment.
+
+### Install Dependencies
+
+**Using npm:**
+```
+ddev npm install
+```
+
+**Using yarn:**
+```
+ddev yarn install
+```
+
+## Running Tests
+
+### With npm
+
+```
+ddev npm run test:chromium      # Run all tests with Chromium
+ddev npm run test:firefox       # Run all tests with Firefox
+ddev npm run test:webkit        # Run all tests with WebKit
+```
+
+### With yarn
+
+```
+ddev yarn test:chromium         # Run all tests with Chromium
+ddev yarn test:firefox          # Run all tests with Firefox
+ddev yarn test:webkit           # Run all tests with WebKit
+```
+
+### Running Specific Tests
+
+```
+ddev exec npx cucumber-js --config cucumber.js tests/features/example.feature
+```

package/docs/install-varbase-e2e.md

@@ -0,0 +1,34 @@
+
+# Install Varbase E2E
+
+**Install Varbase E2E on your project. Simply execute the following command:**
+
+```
+npm add varbase-e2e
+```
+
+## Automated Functional Acceptance Testing
+
+```
+npm test
+```
+
+### Boost your site's success with automated testing
+
+#### For Commercial Professional Support
+
+[Contact Us](/contact)
+
+## Documentation Structure
+
+The page is part of the Varbase E2E 2.0.x documentation section, which includes:
+
+- Global Settings
+- Step Definitions
+- API Step Definitions
+- Advanced Screenshots
+- Advanced Selectors
+- Assertions
+- Commands
+
+There is also a subsection on "[DDEV Varbase E2E](/docs/varbase-e2e/2.0.x/install-varbase-e2e/ddev-varbase-e2e)" available under the installation guide.

package/docs/overview.md

@@ -0,0 +1,40 @@
+
+# Varbase E2E 2.0.x
+
+Varbase E2E is an Automated Functional Acceptance Testing tool that streamlines end-to-end testing for web applications. It combines [Playwright](https://playwright.dev/) and [Cucumber-js](https://github.com/cucumber/cucumber-js) with custom step definitions.
+
+## Key Features
+
+**Test Script Creation:** Users can write scenarios mimicking real user interactions:
+
+```gherkin
+Feature: Login page
+  Scenario: Successful Login with Valid entries
+    Given I am on homepage
+     When I go to "login.html"
+      And I fill in "Username" with "Smith"
+      And I fill in "Password" with "1$34"
+      And I press "Login"
+     Then I should see "Welcome Smith"
+```
+
+**Test Execution:** The tool automates test script execution and verifies outcomes against actual results.
+
+**Test Data Management:** Functionality for defining and manipulating input data sets across different test scenarios.
+
+**Reporting and Analysis:** Generates detailed reports with passed/failed cases and exception documentation.
+
+## Benefits
+
+Varbase E2E offers "increased testing efficiency, reduced human error, improved test coverage, and faster time-to-market."
+
+## Documentation Sub-pages
+
+- [Install Varbase E2E](/docs/varbase-e2e/2.0.x/install-varbase-e2e)
+- [Global Settings](/docs/varbase-e2e/2.0.x/global-settings)
+- [Step Definitions](/docs/varbase-e2e/2.0.x/step-definitions)
+- [API Step Definitions](/docs/varbase-e2e/2.0.x/api-step-definitions)
+- [Advanced Screenshots](/docs/varbase-e2e/2.0.x/advanced-screenshots)
+- [Advanced Selectors](/docs/varbase-e2e/2.0.x/advanced-selectors)
+- [Assertions](/docs/varbase-e2e/2.0.x/assertions)
+- [Commands](/docs/varbase-e2e/2.0.x/commands)

package/docs/step-definitions/given-i-am-anonymous-user.md

@@ -0,0 +1,67 @@
+
+# Given I am an anonymous user
+
+## Step Definition
+
+```gherkin
+Given(/^(I am |we are )?an anonymous user)
+```
+
+## Description
+
+"This step ensures that the current user is not logged in." It configures the browser to simulate a guest visitor state without active session or authentication credentials.
+
+## Usage Examples
+
+```gherkin
+Given I am an anonymous user
+```
+
+```gherkin
+Given we are an anonymous user
+```
+
+```gherkin
+Given an anonymous user
+```
+
+## Purpose
+
+The step definition supports three syntactic variations to accommodate different BDD writing styles while accomplishing the same objective: establishing an unauthenticated user context for test execution.
+
+## More examples
+
+<!-- generated: extended-examples -->
+
+### Example 1
+
+```gherkin
+Given I am an anonymous user
+   When I am on "/dashboard"
+   Then I should see "Sign in"
+```
+
+### Example 2
+
+```gherkin
+Given I am an anonymous user
+   When I am on the homepage
+   Then I should not see "Logout"
+```
+
+### Example 3
+
+```gherkin
+Given I am an anonymous user
+   When I am on "/checkout"
+   Then I should be on "/login"
+```
+
+### Example 4
+
+```gherkin
+Given an anonymous user
+   When I am on "/admin"
+   Then the response status code should be 403
+```
+

package/docs/step-definitions/given-i-am-homepage.md

@@ -0,0 +1,68 @@
+
+# Given I am on homepage
+
+## Step Definition
+
+```
+Given (I am |we are )?on( the)* (homepage|frontpage)
+```
+
+## Description
+
+This step definition establishes the initial context for test scenarios by specifying that a user is currently viewing the website's homepage. When executed, it performs necessary actions to navigate to the homepage, which may include opening a browser, entering the URL, and waiting for the page to fully load. Implementation details vary based on the testing framework and application being tested.
+
+## Examples
+
+```
+Given I am on homepage
+
+Given I am on the homepage
+
+Given I am on frontpage
+
+Given I am on the frontpage
+
+Given we are on homepage
+
+Given on the homepage
+
+Given on homepage
+
+Given we are on the frontpage
+
+Given on frontpage
+```
+
+## More examples
+
+<!-- generated: extended-examples -->
+
+### Example 1
+
+```gherkin
+Given I am on the homepage
+   Then I should see "Welcome"
+```
+
+### Example 2
+
+```gherkin
+Given we are on homepage
+   Then "<header>" should be visible
+```
+
+### Example 3
+
+```gherkin
+Given on the frontpage
+   Then the page should have a main landmark
+```
+
+### Example 4
+
+```gherkin
+Given I am on the homepage
+   When I follow "About"
+   Then I should be on "/about"
+```
+