@vardot/varbase-e2e 2.0.0

package/docs/05-web-first-assertions.md

@@ -0,0 +1,91 @@
+# Web-first Assertions
+
+A "web-first" assertion is an auto-retrying matcher: it polls the page until the condition holds or a budget elapses, instead of taking a single snapshot. Varbase E2E exposes a thin BDD wrapper over Playwright's locator state-checks so feature files never need explicit waits between an action and its assertion.
+
+## Default timeout
+
+Every web-first step has a 5-second budget. Override per step with the trailing `within N seconds` clause:
+
+```gherkin
+Then "#dashboard" should be visible
+Then "#dashboard" should be visible within 12 seconds
+```
+
+## State matchers
+
+```gherkin
+Then "<sel>" should be visible
+Then "<sel>" should be hidden
+Then "<sel>" should be attached
+Then "<sel>" should be focused
+Then "<sel>" should be enabled
+Then "<sel>" should be disabled
+Then "<sel>" should be editable
+```
+
+Negated form:
+
+```gherkin
+Then "<sel>" should not be visible
+Then "<sel>" should not be focused
+```
+
+## Viewport
+
+```gherkin
+Then "<sel>" should be in the viewport
+Then "<sel>" should not be in the viewport within 3 seconds
+```
+
+## Count
+
+```gherkin
+Then "<sel>" should have a count of 5
+Then "<sel>" should have a count of 0 within 10 seconds
+```
+
+## Text / value
+
+```gherkin
+Then "<sel>" should have text "Total: $99.00"
+Then "<sel>" should contain text "$99"
+Then "<sel>" should have value "alice@example.com"
+```
+
+## Attributes / classes
+
+```gherkin
+Then "<sel>" should have attribute "data-state" with value "open"
+Then "<sel>" should have class "is-active"
+```
+
+## Role-based interactions
+
+When you want accessibility-aligned tests, use the role family. These resolve via `page.getByRole(role, { name })` — the same rules screen readers use:
+
+```gherkin
+When I click the "Sign in" button
+When I click the "Profile" link
+When I click the "Notifications" tab
+Then the "Save changes" button should be visible
+Then the "Privacy" tab should be visible within 3 seconds
+```
+
+Supported roles: `button`, `link`, `tab`, `menuitem`, `checkbox`, `radio`, `option`.
+
+## Why prefer web-first
+
+A boolean check + sleep is brittle:
+
+```gherkin
+# BAD — sleep then check; fails if the server is 1ms slower than expected.
+When I press "Save"
+And I wait 2 seconds
+Then "<sel>" should be visible
+
+# GOOD — wait IS the assertion; passes the moment the element appears.
+When I press "Save"
+Then "<sel>" should be visible within 5 seconds
+```
+
+The web-first wrapper is also strictly faster on the happy path: it returns the instant the matcher passes, instead of always sleeping the full configured duration.

package/docs/06-network-and-dialogs.md

@@ -0,0 +1,83 @@
+# Networking & Dialogs
+
+Varbase E2E makes it easy to stub external dependencies, simulate offline / slow networks, and respond to native browser dialogs from within a feature file.
+
+## Stubbing requests
+
+```gherkin
+Scenario: Dashboard renders mocked data
+  Given I am on the homepage
+   And the URL "**/api/users" returns the JSON:
+       """
+       {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+       """
+  When I go to "/dashboard"
+   And I wait for AJAX to finish
+  Then "<#user-list>" should contain text "Alice"
+```
+
+Patterns use Playwright `page.route()` matching: `**/path`, `*.gif`, regex inside CSS.
+
+## Simulating failure
+
+```gherkin
+Given the URL "**/api/login" returns status 401 with body "Unauthorized"
+Given the URL "**/analytics.js" is blocked
+Given the URL "**/api/**" is delayed by 1500 ms
+Given the network is offline
+Given the network is online
+```
+
+## Recording requests
+
+```gherkin
+Given I start recording network requests
+When I click "Buy now"
+Then a POST request to "**/api/checkout" should have been made
+ And no request to "**/tracking" should have been made
+```
+
+The matcher converts `*` to `.*` so URL patterns stay BDD-friendly.
+
+## Browser dialogs
+
+Native `alert`/`confirm`/`prompt` dialogs block tests until handled. Attach a handler **before** the action that triggers the dialog:
+
+```gherkin
+Given I will accept the next dialog
+When I click "Delete"
+Then the last dialog message should contain "Are you sure"
+
+Given I will dismiss the next dialog
+When I click "Leave page"
+
+Given I will accept the next dialog with "user@example.com"
+When I click "Reset password"
+Then the last dialog type should be "prompt"
+```
+
+The most recent dialog is captured on `this._lastDialog` for inspection inside custom step definitions.
+
+For scenarios that trigger many confirmation dialogs in a row, use a persistent handler instead of a single-shot `will accept the next dialog`:
+
+```gherkin
+Given I accept all confirmation dialogs
+# … many clicks that each fire a confirm() …
+Given I do not accept any confirmation dialogs
+```
+
+When recording requests you can match either any method or a specific verb:
+
+```gherkin
+Then a request to "**/api/users" should have been made
+ And a GET request to "**/api/users" should have been made
+```
+
+## When to stub vs hit a real backend
+
+| Stub | Real backend |
+| --- | --- |
+| Third-party APIs (payments, mail, maps) | Your own happy-path flows |
+| Slow/flaky external services | Schema validation tests |
+| Edge cases (5xx, timeouts, malformed JSON) | End-to-end smoke tests |
+| Tests run without internet | Pre-production smoke |

package/docs/07-auth-state.md

@@ -0,0 +1,75 @@
+# Auth State
+
+Logging in once per scenario adds 1–3 seconds per test. Varbase E2E uses Playwright's `storageState` API to **save the cookies + localStorage of an authenticated session** and replay it in later scenarios — instant sign-in, no UI flow.
+
+## Save once, restore everywhere
+
+### One-off setup feature
+
+`tests/features/_setup-auth.feature`:
+
+```gherkin
+@auth-setup
+Feature: Auth state setup
+
+  Scenario: Save admin auth state
+    Given I am on "/login"
+    When I fill in "admin@example.com" for "Email"
+     And I fill in "secret" for "Password"
+     And I press "Sign in"
+     And I wait until the URL contains "/dashboard"
+    Then I save the auth state to "tests/auth/admin.json"
+```
+
+Run once:
+
+```bash
+npx cucumber-js --tags @auth-setup
+```
+
+### Use in regular scenarios
+
+```gherkin
+Feature: Admin dashboard
+
+  Background:
+    Given I restore the auth state from "tests/auth/admin.json"
+     And I am on "/dashboard"
+
+  Scenario: Admin sees user list
+    Then "<#user-list>" should be visible
+     And "<#user-list>" should have a count of 5 within 5 seconds
+```
+
+`I restore the auth state from "..."` swaps the current browser context for a fresh one with the saved cookies/localStorage. The tracker init script is reinstalled automatically so smart waits keep working.
+
+## Clearing auth
+
+```gherkin
+Given I clear the auth state
+```
+
+Removes cookies and clears `localStorage` / `sessionStorage` on the current page.
+
+## Multiple roles
+
+Save one file per role:
+
+- `tests/auth/admin.json`
+- `tests/auth/editor.json`
+- `tests/auth/customer.json`
+
+Then pick a role per scenario:
+
+```gherkin
+Scenario: Editor cannot delete
+  Given I restore the auth state from "tests/auth/editor.json"
+  When I am on "/admin/products"
+  Then the "Delete" button should not be visible
+```
+
+## Caveats
+
+- Session keys signed against IP or User-Agent will reject the restored cookie. Use a longer session lifetime in test environments.
+- CSRF tokens stored on form pages need to be re-fetched after restore. Use `Given I am on "/path"` after the restore step.
+- Two-factor flows cannot be replayed — keep an environment-specific TOTP bypass behind a feature flag.

package/docs/08-clock-mocking.md

@@ -0,0 +1,59 @@
+# Clock Mocking
+
+Time-dependent UI is hard to test in real time: a "5 minutes ago" label takes 5 minutes to verify, a session-timeout warning sits idle for 14 minutes before firing. Varbase E2E wraps Playwright's `page.clock` API in BDD steps so scenarios can advance virtual time at full speed.
+
+## Install a fake clock
+
+```gherkin
+Given the system time is "2026-05-08T10:00:00Z"
+```
+
+After this step, `Date.now()` inside the page returns the fake time. Pending `setTimeout` and `setInterval` callbacks queue but do not fire until you advance the clock.
+
+## Advance time
+
+```gherkin
+When I advance the clock by 500 ms
+When I advance the clock by 30 seconds
+When I advance the clock by 15 minutes
+```
+
+Each advance fires every timer scheduled within the new interval, in order, in real-time speed (i.e. instantly).
+
+## Pause / resume / set
+
+```gherkin
+When I pause the clock
+When I resume the clock
+When I set the system time to "2026-12-31T23:59:55Z"
+```
+
+`pause` freezes time at the current value. `set` jumps to a new instant **without** firing the timers in between (use `advance` if you want them to fire).
+
+## Recipe: relative-time labels
+
+```gherkin
+Scenario: "5 minutes ago" updates as time passes
+  Given the system time is "2026-05-08T10:00:00Z"
+   And I am on "/feed"
+   And "<.timestamp>" should have text "just now"
+  When I advance the clock by 5 minutes
+  Then "<.timestamp>" should have text "5 minutes ago"
+```
+
+## Recipe: session timeout
+
+```gherkin
+Scenario: Idle warning fires at 14 minutes
+  Given the system time is "2026-05-08T10:00:00Z"
+   And I restore the auth state from "tests/auth/admin.json"
+   And I am on "/dashboard"
+  When I advance the clock by 14 minutes
+  Then "<#session-warning>" should be visible
+```
+
+## Caveats
+
+- `requestAnimationFrame` and `MutationObserver` are not on the fake clock. Animations driven by `rAF` keep playing in real time.
+- The Date constructor reads the fake clock, but server timestamps embedded at page load do not change.
+- Install the clock **before** loading the page if you need scripts to see the fake time on first execution.

package/docs/09-api-testing.md

@@ -0,0 +1,114 @@
+# API Testing
+
+Varbase E2E scenarios can talk to an HTTP API directly without leaving the cucumber-js runtime. The browser context's cookie jar is shared, so a UI login can be followed by REST-level assertions in the same scenario.
+
+## Setting headers and base URL
+
+```gherkin
+Given the API base URL is "https://api.example.com"
+ And I set the header "Authorization" to "Bearer abc123"
+ And I set the following headers:
+   | X-Request-ID | test-123          |
+   | Accept       | application/json  |
+```
+
+## Sending requests
+
+```gherkin
+When I send a GET request to "/users"
+When I send a POST request to "/users" with body:
+  """
+  {"name": "Alice", "email": "alice@example.com"}
+  """
+When I send a PUT request to "/users/1" with form data:
+  """
+  name=Alice&role=admin
+  """
+```
+
+## Asserting responses
+
+```gherkin
+Then the API response code should be 200
+ And the API response should contain "Alice"
+ And the API response should not contain "<script>"
+ And the response header "content-type" should contain "json"
+ And the response should be valid JSON
+ And the JSON property "user.name" should be "Alice"
+ And the JSON response should have property "user.id"
+ And the JSON response should not have property "password"
+```
+
+## Combining UI and API
+
+```gherkin
+Scenario: Order placed via UI shows up in API
+  Given I restore the auth state from "tests/auth/customer.json"
+   And I am on "/cart"
+  When I press "Place Order"
+   And I wait until the URL contains "/orders/"
+  When I send a GET request to "/api/orders?latest=1"
+  Then the API response code should be 200
+   And the JSON property "orders.0.status" should be "Pending"
+```
+
+## Date placeholders
+
+API bodies often need fresh dates. Use `[relative:OFFSET#FORMAT]` tokens — they're resolved before the request is sent:
+
+```gherkin
+Given I set the request body to '{"start": "[relative:now#YYYY-MM-DD]", "end": "[relative:+7 days#YYYY-MM-DD]"}'
+When I send a POST request to "/api/bookings"
+Then the API response code should be 201
+```
+
+## Other request shapes
+
+Use a data-table when the body is a flat key/value map:
+
+```gherkin
+When I send a POST request to "/users" with values:
+  | name  | Alice                |
+  | email | alice@example.com    |
+```
+
+Assert against an exact JSON shape with a doc string:
+
+```gherkin
+Then the API response should contain json:
+  """
+  {"id": 1, "name": "Alice"}
+  """
+```
+
+Substitute placeholders captured from earlier responses or scenario data:
+
+```gherkin
+Given I set placeholder "{{userId}}" to "42"
+When I send a GET request to "/users/{{userId}}"
+```
+
+For HTTP basic auth on the next page navigation, see also `path.steps.js`:
+
+```gherkin
+Given the basic authentication with the username "admin" and the password "secret"
+```
+
+## Short-form REST steps
+
+A parallel short-form lives in `rest.steps.js` for quick smoke tests:
+
+```gherkin
+Given a REST header "Authorization" with value "Bearer abc123"
+When I send a REST "GET" request to "/api/users"
+Then the REST response status code should be 200
+ And the REST response should contain "Alice"
+```
+
+## Print response (debugging only)
+
+```gherkin
+Then print API response
+```
+
+Outputs status, headers, and body to stdout. Strip before committing.

package/docs/10-accessibility.md

@@ -0,0 +1,167 @@
+# Accessibility (a11y)
+
+Varbase E2E ships **two layers** of accessibility coverage:
+
+1. **Custom JS probes** — fast, dependency-free assertions for POUR
+   fundamentals (Perceivable, Operable, Understandable, Robust). Each
+   probe maps to a specific WCAG 2.1 / 2.2 success criterion.
+2. **axe-core full audit** — official Deque engine (`@axe-core/playwright`
+   + `axe-core`). Runs ~100 rules covering WCAG 2.0 / 2.1 / 2.2 levels
+   A, AA, AAA plus best-practice and experimental rules. Each violation
+   carries an `impact` (`minor` / `moderate` / `serious` / `critical`)
+   for triage.
+
+## Standards & references
+
+* [WCAG 2.1](https://www.w3.org/TR/WCAG21/) — current baseline most laws cite.
+* [WCAG 2.2](https://www.w3.org/TR/WCAG22/) — September 2023 update.
+* [W3C WAI](https://www.w3.org/WAI/) — Web Accessibility Initiative overview.
+* [W3C Evaluation Tools List](https://www.w3.org/WAI/test-evaluate/tools/list/)
+* [MDN — Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
+* [axe-core rule descriptions](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)
+* [Deque Labs](https://github.com/dequelabs/) — axe-core, axe-linter, IDE plugins.
+
+## Page structure
+
+```gherkin
+Then the page should declare a language
+ And the page language should be "en"
+ And the page should have a main landmark
+ And the page should have a navigation landmark
+ And the page should have exactly one h1
+```
+
+## Images & form labels
+
+```gherkin
+Then every image should have an alt attribute
+ And every form field should have an accessible label
+```
+
+`every image` allows empty `alt=""` (decorative) and `role="presentation"`. Missing alt fails.
+
+`every form field` counts as labelled when **any** of the following is true:
+- An `aria-label` attribute is present
+- An `aria-labelledby` attribute resolves to an element
+- A `<label for="...">` matches the field's id
+- The field is wrapped by a `<label>`
+
+Submit/reset/button/image inputs and `type="hidden"` are exempt.
+
+## Focus assertions
+
+```gherkin
+When I focus on the element "#email"
+Then the focused element should match "#email"
+ And the focused element should be labeled "Email"
+```
+
+The labeled assertion resolves the accessible name in priority order:
+1. `aria-label`
+2. `aria-labelledby` referenced element
+3. `<label for="...">` text
+4. Wrapping `<label>` text
+5. `value` / `placeholder` / `title` / `textContent`
+
+## Keyboard navigation
+
+The `keyboard.steps.js` file exposes:
+
+```gherkin
+When I press the "Tab" key
+When I press the "Tab" key 3 times
+When I press the "Enter" key
+When I press the "Escape" key
+When I press the "ArrowDown" key
+```
+
+Combine with focus assertions:
+
+```gherkin
+Scenario: Tab order is correct
+  Given I am on "/login"
+   And I focus on the element "body"
+  When I press the "Tab" key
+  Then the focused element should match "#email"
+  When I press the "Tab" key
+  Then the focused element should match "#password"
+  When I press the "Tab" key
+  Then the focused element should match "button[type=submit]"
+```
+
+## WCAG hygiene probes
+
+Lightweight checks that map to specific WCAG criteria. No axe-core required.
+
+```gherkin
+Then the page should have a title
+ And user zoom should be allowed
+ And the heading hierarchy should be valid
+ And the page should have a skip link
+ And every button should have an accessible name
+ And every link should have an accessible name
+ And no element should have a positive tabindex
+ And every ARIA reference should resolve
+ And every ARIA role should be valid
+ And required fields should be consistently marked
+```
+
+| Step | WCAG SC |
+| --- | --- |
+| `the heading hierarchy should be valid` | 1.3.1, 2.4.6 |
+| `the page should have a skip link` | 2.4.1 |
+| `every button should have an accessible name` | 4.1.2 |
+| `every link should have an accessible name` | 2.4.4, 4.1.2 |
+| `no element should have a positive tabindex` | 2.4.3 |
+| `every ARIA reference should resolve` | 4.1.2 |
+| `every ARIA role should be valid` | 4.1.2 |
+| `the page should have a title` | 2.4.2 |
+| `user zoom should be allowed` | 1.4.4, 1.4.10 |
+| `required fields should be consistently marked` | 3.3.2 |
+
+## axe-core full audit
+
+```gherkin
+Then the page should pass an accessibility audit
+ And the page should pass an accessibility audit at level "AA"
+ And the page should pass an accessibility audit at level "AAA"
+ And the page should have no critical accessibility violations
+ And the page should have no serious accessibility violations
+ And the element "main" should pass an accessibility audit
+ And the page should pass an accessibility audit excluding "iframe.payment"
+ And the page should not violate the accessibility rule "color-contrast"
+ And the page should pass the accessibility rules "image-alt, label, button-name"
+ Then I print accessibility violations
+```
+
+Default audit level is **AA** — required by EU Web Accessibility
+Directive, US Section 508, UK PSBAR. Use `at level "AAA"` for stricter
+gates.
+
+Common axe rule ids worth pinning: `color-contrast`, `image-alt`,
+`label`, `link-name`, `button-name`, `heading-order`, `landmark-one-main`,
+`region`, `aria-valid-attr`, `tabindex`, `bypass`, `frame-title`,
+`meta-viewport`, `valid-lang`, `duplicate-id-aria`, `list`, `listitem`.
+
+## Recommended baseline
+
+For a public site under WCAG 2.1 AA obligations, gate every page on:
+
+```gherkin
+Then the page should pass an accessibility audit at level "AA"
+ And the page should have a title
+ And the page should have a main landmark
+ And the heading hierarchy should be valid
+ And user zoom should be allowed
+```
+
+For an admin / authenticated UI where some third-party widgets are
+known-bad, gate on the impact-based step instead:
+
+```gherkin
+Then the page should have no critical accessibility violations
+ And the page should have no serious accessibility violations
+```
+
+Tag scenarios `@a11y` so CI can run the accessibility suite in
+isolation: `npx cucumber-js --tags "@a11y"`.