@vardot/varbase-e2e 2.0.0

package/bin/postinstall.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { run } = require('./init-varbase-e2e');
+
+const packagePath = path.join(__dirname, '..');
+const projectPath = process.env.INIT_CWD || process.cwd();
+
+// Skip when invoked from varbase-e2e itself (development / CI).
+if (
+  projectPath === packagePath ||
+  projectPath.startsWith(path.join(packagePath, 'node_modules'))
+) {
+  process.exit(0);
+}
+
+// Only run on a fresh project — cucumber.js absence marks an uninitialized project.
+// Re-installs (npm install, npm ci) will not overwrite user customizations.
+if (fs.existsSync(path.join(projectPath, 'cucumber.js'))) {
+  process.exit(0);
+}
+
+run(['--cwd', projectPath]);

package/cucumber.js

@@ -0,0 +1,125 @@
+module.exports = {
+  default: {
+    // Cucumber step timeout must exceed Playwright's default 30s so the
+    // try/catch wrappers in step files always see the Playwright error
+    // first (and emit a friendly message) rather than cucumber's raw
+    // "function timed out" stack.
+    timeout: 45000,
+    // tsx/cjs registers a require() hook so cucumber-js can load both
+    // `.js` and `.ts` step files with zero build step. If you ship only
+    // JavaScript, drop `requireModule` and the `.ts` half of the glob.
+    requireModule: ['tsx/cjs'],
+    require: [
+      'tests/step-definitions/**/*.js',
+    ],
+    paths: ['tests/features/**/*.feature'],
+    format: [
+      '@cucumber/pretty-formatter',
+      'json:tests/reports/cucumber_report.json',
+    ],
+    formatOptions: {
+      // Color toggle is controlled via the FORCE_COLOR env var (per
+      // cucumber-js v10+); the deprecated `colorsEnabled` option is gone.
+      theme: {
+        'feature keyword': ['bold', 'blue'],
+        'feature name': ['blue', 'underline'],
+        'feature description': ['blueBright'],
+        'scenario keyword': ['bold', 'magenta'],
+        'scenario name': ['magenta', 'underline'],
+        'step keyword': ['bold', 'green'],
+        'step text': ['greenBright', 'italic'],
+      },
+    },
+    worldParameters: {
+      launchUrl: process.env.LAUNCH_URL || 'http://localhost:8080',
+      minWaitTime: {
+        page: 3000,
+        before_scenario: 0,
+        after_scenario: 0,
+        before_step: 0,
+        after_step: 0,
+      },
+      selectors: {
+        // Named CSS selectors — layout components and element locators in one registry.
+        // Register inline: When I add "name" selector for "css" css selector
+        // Or in bulk:      Given I define css selectors:
+        //                    | name | css selector |
+        css: {
+          // 'header':                'header.page-header',
+          // 'main nav':              'nav[role="navigation"]',
+          // 'breadcrumb':            '.breadcrumb',
+          // 'breadcrumb first link': '.breadcrumb li:nth-child(1) a',
+          // 'message':               '.messages',
+          // 'error message':         '.messages.error',
+          // 'success message':       '.messages.status',
+          // 'warning message':       '.messages.warning',
+        },
+        // Named XPath selectors — use with: When I add "name" selector for "xpath" xpath selector
+        xpath: {
+          // 'page title': '//h1[contains(@class,"page-header")]',
+        },
+        // Load additional selectors from JSON files at scenario start.
+        filesPath: './tests/selectors/',             // base path for selector files
+        files: [],                                   // e.g. ['homepage-selectors.json'] or ['front-end-selectors.json', 'back-end-selectors.json']
+        // Relative-position scroll offset (px) — VARBASE_E2E_SELECTORS_OFFSET
+        offset: 60,
+        // Viewport breakpoints — VARBASE_E2E_SELECTORS_BREAKPOINTS (JSON string)
+        breakpoints: {
+          xs:   { width: 375,  height: 667  },                    // phone portrait
+          sm:   { width: 576,  height: 800  },                    // large phone / phablet
+          md:   { width: 768,  height: 1024 },                    // tablet portrait
+          lg:   { width: 992,  height: 768  },                    // small laptop / tablet landscape
+          xl:   { width: 1200, height: 900, default: true },      // desktop
+          xxl:  { width: 1400, height: 900  },                    // wide desktop / HD
+          xxxl: { width: 1920, height: 1080 },                    // Full HD / large monitor
+        },
+      },
+      screenshot: {
+        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}.{feature_file}.feature_{step_line}.{ext}', // VARBASE_E2E_SCREENSHOT_PATTERN
+        filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}', // VARBASE_E2E_SCREENSHOT_PATTERN_FAIL
+        infoTypes: '',                               // VARBASE_E2E_SCREENSHOT_INFO_TYPES  e.g. "url,feature,step,datetime"
+      },
+      video: {
+        // Record the browser as a webm video.
+        //   'off' (default) — no recording.
+        //   'on'            — record every scenario.
+        //   'on-failure'    — record every scenario, keep only failures.
+        //   'tag'           — record only scenarios tagged @video.
+        // Override per scenario with tags:
+        //   @video    — force recording on (independent of mode).
+        //   @no-video — suppress recording for this scenario.
+        // Override per run with env: VARBASE_E2E_VIDEO.
+        mode: 'off',                                 // VARBASE_E2E_VIDEO
+        dir: './videos',                             // VARBASE_E2E_VIDEO_DIR
+        size: { width: 1280, height: 720 },          // viewport size of the recording
+        // Filename template tokens: {datetime} {feature_file} {feature} {scenario}
+        // {status} {ext}. Sanitised to filesystem-safe characters.
+        filenamePattern: '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
+      },
+      javascript: {
+        // How to report collected JavaScript errors at scenario end.
+        //   'warn' (default) — log a yellow warning, scenario still passes.
+        //   'fail'           — fail the scenario.
+        //   'off'            — silent.
+        // Override per scenario with tags: @js-fail, @js-warn, @js-off.
+        // Override per run with env: VARBASE_E2E_JS_ERROR_MODE.
+        mode: 'warn',                                // VARBASE_E2E_JS_ERROR_MODE
+        // Console levels to capture in addition to `pageerror`.
+        // Common: ['error'], ['error','warning'], ['error','warning','info'].
+        levels: ['error'],                           // VARBASE_E2E_JS_ERROR_LEVELS (csv)
+        // Regex string. Errors whose message matches are ignored.
+        ignore: '',                                  // VARBASE_E2E_JS_ERROR_IGNORE
+        // Snapshot any pre-existing errors at scenario start.
+        beforeScenario: false,                       // VARBASE_E2E_JS_ERROR_BEFORE
+        // Report collected errors at scenario end (default true).
+        afterScenario: true,                         // VARBASE_E2E_JS_ERROR_AFTER
+      },
+    },
+  },
+};

package/docs/00-quick-start.md

@@ -0,0 +1,102 @@
+# Quick Start (5 minutes)
+
+Brand new to varbase-e2e? Read this page once. You'll be writing tests in
+five minutes.
+
+## What you write
+
+Plain English scenarios. No JavaScript required.
+
+```gherkin
+Feature: Sign in
+
+  Scenario: Successful login
+    Given I am on "/login"
+    When I fill in "Email" with "alice@example.com"
+     And I fill in "Password" with "s3cret"
+     And I press "Sign in"
+    Then I should see "Welcome, Alice"
+```
+
+That's a complete test. Every line maps to a built-in step. No setup
+code. No selector jargon.
+
+## What you get
+
+* **Real browser** — runs in Chromium, Firefox, or WebKit via Playwright.
+* **Automatic smart waits** — every action waits for the page to
+  settle. No `sleep` / `wait 5s` needed in the happy path.
+* **HTML report** — runs auto-generate `tests/reports/cucumber_report.html`.
+* **Screenshots on failure** — saved to `screenshots/` for instant
+  debugging.
+
+## 30-second install
+
+```bash
+npm install @vardot/varbase-e2e --save-dev
+```
+
+The post-install script copies a starter `cucumber.js`,
+`playwright.config.ts`, and `tests/` skeleton.
+
+## 60-second first test
+
+1. Drop your scenario into `tests/features/smoke.feature`.
+2. Make sure your dev server is running on `http://localhost:8080`
+   (or set `LAUNCH_URL` to point elsewhere).
+3. Run:
+
+```bash
+npm test
+```
+
+If your scenario passes, you're done. If it fails, the Cucumber output
+names the step that failed and the expected vs actual.
+
+## Where to go next
+
+| Want to… | Read |
+| --- | --- |
+| Understand smart waits (no `sleep`) | [02 BBR smart waits](02-bbr-smart-waits.md) |
+| Use named selectors instead of long CSS | [03 Selector registry](03-selector-registry.md) |
+| See every built-in step | [04 Step reference](04-step-reference.md) |
+| Test forms / clicks / modals | [04 Step reference](04-step-reference.md) |
+| Mock APIs / dialogs | [06 Networking & dialogs](06-network-and-dialogs.md) |
+| Accessibility audits | [10 Accessibility](10-accessibility.md) |
+| Use AI to generate tests | [12 AI agent guide](12-ai-agent-guide.md) |
+| FAQ | [13 FAQ](13-faq.md) |
+| Recipes cookbook | [14 Recipes cookbook](14-recipes-cookbook.md) |
+
+## The mental model
+
+* `Given` — set up the scene (navigate, restore auth, seed data).
+* `When` — do something (click, fill, submit).
+* `Then` — check what should be true (text visible, URL changed).
+* `And` / `But` — continuation. Pick whichever reads naturally.
+* `Background:` — steps shared across every scenario in a feature.
+* `Scenario Outline:` + `Examples:` — same scenario with different data.
+
+## The golden rule
+
+**Wait for events, not time.** Varbase E2E does this for you in the
+common case. If you ever feel tempted to add `wait 5 seconds` because
+something flaked, look for an event-based wait first:
+
+```gherkin
+# Bad — slow, brittle.
+When I press "Save"
+ And I wait 5 seconds
+Then I should see "Saved"
+
+# Good — instant when fast, patient when slow.
+When I press "Save"
+Then I should see "Saved"
+
+# Best when "Save" navigates.
+When I press "Save"
+ And I wait until the URL contains "/saved"
+Then I should see "Saved"
+```
+
+That's the entire philosophy. Read [02 BBR smart waits](02-bbr-smart-waits.md)
+when you're ready to internalise the details.

package/docs/01-getting-started.md

@@ -0,0 +1,102 @@
+# Getting Started
+
+Varbase E2E is an automated functional testing harness built on Playwright + Cucumber-js. You write feature files in plain Gherkin; varbase-e2e handles the browser, smart waits, screenshots, reports, and CMS-aware selectors out of the box.
+
+## Install
+
+```bash
+npm install @vardot/varbase-e2e --save-dev
+```
+
+The post-install script copies a starter `cucumber.js`, `playwright.config.ts`, and `tests/` skeleton into your project on first install.
+
+## Project layout
+
+```
+your-project/
+├── cucumber.js                      # Profiles + worldParameters
+├── playwright.config.ts             # Browser launch + context options
+└── tests/
+    ├── features/                    # *.feature files (Gherkin)
+    ├── selectors/                   # CMS / framework selector JSON
+    └── step-definitions/            # *.js or *.ts (loaded automatically)
+```
+
+## TypeScript and JavaScript together
+
+Step definitions can be plain JavaScript (`.js`) or TypeScript (`.ts`) — mix freely in the same project. The default `cucumber.js` registers the [`tsx`](https://tsx.is) require hook, so `.ts` files run with zero build step:
+
+```js
+// cucumber.js (default)
+requireModule: ['tsx/cjs'],
+require: ['tests/step-definitions/**/*.{js,ts}'],
+```
+
+Add a TypeScript step alongside JS ones:
+
+```ts
+// tests/step-definitions/custom.steps.ts
+import { Then } from '@cucumber/cucumber';
+import assert from 'node:assert';
+
+Then(/^(I |we )*see a TypeScript step$/, async function (this: { page: import('playwright').Page }) {
+  assert.ok(this.page);
+});
+```
+
+Pure-JS shops can drop both `requireModule` and the `.ts` half of the glob.
+
+## Run the suite
+
+```bash
+# Default — full pretty output, optional auto-screenshots on failure.
+npm test
+
+# Fast run — no slow-mo.
+npm run test:fast
+
+# Watch the browser interactively.
+npm run test:headed
+
+# Pick a single browser.
+BROWSER=firefox npm test
+BROWSER=webkit  npm test
+
+# Parallel + retry (CLI flags — no separate profile needed).
+npx cucumber-js --parallel 4 --retry 1 --retry-tag-filter @flaky
+```
+
+## Environment variables
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `LAUNCH_URL` | `http://localhost:8080` | Base URL for `Given I am on "/path"` |
+| `BROWSER` | `chromium` | `chromium` / `firefox` / `webkit` |
+| `HEADLESS` | `true` | Set to `false` for headed mode |
+| `SLOW_MO` | `300` headed: `800` | Per-action delay (ms); set `0` for fast runs |
+| `VARBASE_E2E_AUTO_SETTLE` | on | Set to `off` to disable auto edge-wait after actions |
+
+## First feature file
+
+```gherkin
+Feature: Smoke
+
+  Scenario: Homepage loads
+    Given I am on the homepage
+     Then the page should declare a language
+      And the page should have exactly one h1
+      And there should be no JavaScript errors
+```
+
+## Next reading
+
+- [BBR smart waits](02-bbr-smart-waits.md) — why we never `sleep N seconds`.
+- [Selector registry](03-selector-registry.md) — named selectors + CMS presets.
+- [Step reference](04-step-reference.md) — every built-in step, by topic.
+- [Web-first assertions](05-web-first-assertions.md) — auto-retrying matchers.
+- [Networking & dialogs](06-network-and-dialogs.md) — mocks, routes, alerts.
+- [Auth state](07-auth-state.md) — save / restore login.
+- [Clock mocking](08-clock-mocking.md) — control time.
+- [API testing](09-api-testing.md) — direct HTTP from BDD.
+- [Accessibility](10-accessibility.md) — POUR smoke checks.
+- [Debugging](11-debugging.md) — screenshots, headed mode, traces.

package/docs/02-bbr-smart-waits.md

@@ -0,0 +1,77 @@
+# BBR Smart Waits
+
+Varbase E2E follows a **Behavior-Based Robotics** philosophy: **react to the environment, not the clock.** A test never sleeps for a fixed N seconds. Instead, every wait step returns as soon as the page is at the **edge** of activity — DOM ready, no in-flight network, no pending timers, no live mutations.
+
+## What gets tracked
+
+Varbase E2E installs a small init script in every browser context. It exposes four signals:
+
+| Signal | Counter / time | Source |
+| --- | --- | --- |
+| Fetch / XHR in flight | `window.__varbaseE2eAjaxCount` | wraps `window.fetch` and `XMLHttpRequest.send` |
+| Pending `setTimeout` | `window.__varbaseE2ePendingTimers` | wraps `window.setTimeout` / `clearTimeout` |
+| Last DOM mutation | `window.__varbaseE2eLastMutation` | `MutationObserver` on `<html>` |
+| Network idle | (Playwright internal) | `page.waitForLoadState('networkidle')` |
+
+`smartSettle(page, budget)` polls all four atomically and returns when:
+
+```
+__varbaseE2eAjaxCount === 0
+  && __varbaseE2ePendingTimers === 0
+  && (Date.now() - __varbaseE2eLastMutation) >= 250 ms
+```
+
+…or when `budget` elapses, whichever comes first. Each phase is best-effort, so a slow network does not stall the others.
+
+## Step phrasings
+
+```gherkin
+# Bounded smart wait (returns early on idle).
+When I wait 5 seconds
+When I wait max of 5 seconds
+When I wait for 3 seconds for AJAX to finish
+
+# Pure edge waits.
+When I wait until the page is loaded
+When I wait for AJAX to finish
+When I wait until pending timers settle
+When I wait until the network is idle
+
+# Targeted edge waits.
+When I wait for "#dashboard" to appear
+When I wait for "#loading" to disappear
+When I wait for the text "Welcome" to appear
+When I wait until the URL contains "/dashboard"
+When I wait until the page title contains "Dashboard"
+When I wait until 5 elements match ".product-card"
+When I wait until at least 3 elements match ".item"
+
+# Modal-specific.
+When I wait for the modal to appear
+When I wait for the modal to disappear
+
+# Body + DOMContentLoaded only (cheaper than full smart settle).
+When I wait until the page is interactive
+
+# Polling text assertion — re-runs the matcher until the deadline.
+Then eventually I should see "Done"
+Then eventually I should see "Done" within 10 seconds
+```
+
+## Auto-settle after actions
+
+After every state-changing step (click, press, fill, submit, select, check, uncheck, choose, attach, reload, navigate), varbase-e2e silently runs `smartSettle(page, 1500)`. Tests do not need an explicit wait between an action and its follow-up assertion in the typical case. Disable per-run with `VARBASE_E2E_AUTO_SETTLE=off`.
+
+## What this kills
+
+- **Sleep-driven testing** — `wait 3s` no longer means "sleep three seconds." It means "wait up to three seconds for the page to become quiet."
+- **`networkidle` blind spots** — animations and `setTimeout`-driven UI changes that did not trigger a network request still register on the DOM-mutation and timer-pending signals.
+- **Race-condition flake** — a click followed by an assertion that runs before the DOM finishes updating is now caught by the auto-settle hook.
+
+## When to override
+
+You generally don't. A few legitimate cases:
+
+- **Real animation** with a known duration (`wait 3 seconds` is fine — smart wait will exit early but the budget is still honored).
+- **Polling backend** that mutates without fetch/XHR (e.g. raw WebSocket pushes). Use a targeted edge wait: `wait for the text "..." to appear`.
+- **Off-by-design UI** that runs an `setInterval` heartbeat. The pending-timer counter only tracks `setTimeout`, so heartbeats do not block `smartSettle`.

package/docs/03-selector-registry.md

@@ -0,0 +1,95 @@
+# Selector Registry
+
+Long, brittle CSS strings poison feature files. Varbase E2E solves this with a **named selector registry**: register a CSS or XPath string once, refer to it by a friendly name in every step.
+
+## Three ways to register
+
+### 1. Inline (one selector at a time)
+
+```gherkin
+Scenario: Add to cart
+  Given I am on "/products/101"
+  When I add "buy button" selector for ".product__buy button[type=submit]" css selector
+  And I click "buy button" by attr
+```
+
+### 2. Bulk (Gherkin data table)
+
+```gherkin
+Scenario: Layout assertions
+  Given I define css selectors:
+    | header   | header.site                |
+    | nav      | nav[role="navigation"]     |
+    | main     | main                       |
+    | footer   | footer                     |
+   Then "main" should be visible
+```
+
+### 3. JSON file (project-wide preset)
+
+```js
+// cucumber.js
+worldParameters: {
+  selectors: {
+    filesPath: './tests/selectors/',
+    files: ['cms-drupal-cms-gin.json'],
+  }
+}
+```
+
+Every scenario starts with a fresh registry. Later entries with the same name override earlier ones (last wins).
+
+## Built-in CMS / framework presets
+
+Varbase E2E ships ready-made selector packs:
+
+```
+tests/selectors/
+├── _canonical-keys.json        # Index of canonical keys + naming rules
+├── back-end-selectors.json     # Generic admin layout
+├── front-end-selectors.json    # Generic public layout
+├── cms-drupal-cms-gin.json     # Drupal CMS (Gin admin theme)
+├── cms-drupal-core-claro.json  # Drupal Core (Claro admin theme)
+├── cms-generic-admin.json      # Pattern-matching generic CMS admin
+├── cms-ghost-admin.json        # Ghost
+├── cms-joomla-admin.json       # Joomla
+├── cms-magento2-admin.json     # Magento 2
+├── cms-prestashop-admin.json   # PrestaShop
+├── cms-shopify-admin.json      # Shopify Polaris admin
+├── cms-strapi-admin.json       # Strapi
+├── cms-typo3-admin.json        # TYPO3
+├── cms-contentful-admin.json   # Contentful
+├── cms-craft-admin.json        # Craft CMS
+├── cms-wordpress-admin.json    # WordPress
+├── cms-woocommerce-front.json  # WooCommerce storefront
+├── framework-ant-design.json   # Ant Design
+├── framework-bootstrap.json    # Bootstrap
+├── framework-bulma.json        # Bulma
+├── framework-chakra.json       # Chakra UI
+├── framework-foundation.json   # Foundation
+├── framework-material-ui.json  # MUI
+├── framework-shadcn.json       # shadcn / Radix
+├── framework-tailwind.json     # Tailwind common patterns
+└── framework-vuetify.json      # Vuetify
+```
+
+## Canonical key set
+
+To keep tests portable, every preset exposes the same core names. See `tests/selectors/_canonical-keys.json` for the full list. Highlights:
+
+- **Layout** — `main nav`, `main nav item`, `sidebar`, `header bar`, `main content`, `page title`, `breadcrumb`, `user menu`
+- **Modal** — `modal`, `modal overlay`, `modal title`, `modal body`, `modal footer`, `modal close`
+- **Buttons** — `primary button`, `secondary button`, `danger button`, `save button`, `cancel button`, `delete button`
+- **Notices** — `notice success`, `notice error`, `notice warning`, `notice info`, `toast`
+- **Forms** — `form`, `form item`, `form label`, `form input`, `form select`, `form textarea`, `form actions`
+- **Tables** — `data table`, `table header`, `table row`, `table first row`, `table row cell`
+- **Tabs** — `tabs`, `tab item`, `active tab`, `tab content`
+- **Search** — `search input`
+- **Pagination** — `pagination`
+
+## Naming rules
+
+- Lowercase words separated by single spaces (`primary button`, not `primary-button`).
+- Modifier first (`active tab`, `danger button`, `first list item`).
+- Synonyms collapse to canonical names (`alert success` / `notification success` / `callout success` → `notice success`).
+- `data table` for HTML tables; `data list` for `ul`/`ol` collections.