@vardot/varbase-e2e 2.0.0

package/tests/step-definitions/wait.steps.js

@@ -0,0 +1,400 @@
+'use strict';
+
+// All wait/settle step definitions live in this file.
+//
+// Behavior-Based Robotics (BBR) principle: react to the environment, not the
+// clock. A wait step never blocks for a fixed duration — it returns as soon
+// as the page is at the *edge* of activity, bounded by a budget so a runaway
+// page cannot stall the run.
+//
+// Shared smartSettle and modal probes are imported from varbase-e2e.js
+// so this file never duplicates BBR plumbing.
+
+const { When } = require('@cucumber/cucumber');
+const { smartSettle, waitForModalState } = require('./varbase-e2e');
+
+/**
+ * Wait UP TO N seconds for the page to settle. Returns early on idle.
+ *
+ * "Settle" = DOM ready, no in-flight fetch/XHR, no pending setTimeout
+ * callbacks, and no MutationObserver activity for at least 250 ms.
+ *
+ * Example #1: When I wait for 1 second
+ * Example #2: When I wait for 5 seconds
+ * Example #3: And I wait for 3 seconds
+ * Example #4: When we wait for 2 seconds
+ * Example #5: And we wait for 10 seconds
+ * Example #6: When I press "Save"
+ *               And I wait for 2 seconds
+ *               Then I should see "Saved"
+ *
+ */
+When(/^(I |we )*wait for (\d+) seconds?$/, async function (pronoun, seconds) {
+  await smartSettle(this.page, parseInt(seconds, 10) * 1000);
+});
+
+/**
+ * Wait UP TO N seconds for the page (and AJAX) to settle. Returns early.
+ *
+ * Same probe as `wait for N seconds` — kept for legacy phrasing parity with
+ * older feature files that say "for AJAX to finish" explicitly.
+ *
+ * Example #1: When I wait for 1 second for AJAX to finish
+ * Example #2: When I wait for 3 seconds for AJAX to finish
+ * Example #3: And I wait for 5 seconds for AJAX to finish
+ * Example #4: When we wait for 2 seconds for AJAX to finish
+ * Example #5: When I press "Search"
+ *               And I wait for 5 seconds for AJAX to finish
+ *               Then I should see "Results"
+ *
+ */
+When(/^(I |we )*wait for (\d+) seconds? for AJAX to finish$/, async function (pronoun, seconds) {
+  await smartSettle(this.page, parseInt(seconds, 10) * 1000);
+});
+
+/**
+ * Wait UP TO a number of seconds for the page to settle.
+ *
+ * Example #1: When I wait 1 second
+ * Example #2: When I wait 5 seconds
+ * Example #3: When we wait 3s
+ * Example #4: And wait 2s
+ * Example #5: And wait 2 seconds
+ * Example #6: When we wait 1 second
+ * Example #7: When we wait 5 seconds
+ * Example #8: When we wait 4s
+ *
+ */
+When(/^(I |we )*wait (\d+)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
+  await smartSettle(this.page, parseInt(number, 10) * 1000);
+});
+
+/**
+ * Wait UP TO a maximum number of seconds for the page to settle.
+ *
+ * Example #1: When I wait max of 1 second
+ * Example #2: When I wait max of 5 seconds
+ * Example #3: When we wait max of 3s
+ * Example #4: And wait max of 2s
+ * Example #5: And wait max of 2 seconds
+ * Example #6: When we wait max of 1 second
+ * Example #7: When we wait max of 5 seconds
+ * Example #8: When we wait max of 4s
+ *
+ */
+When(/^(I |we )*wait max of (\d+)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
+  await smartSettle(this.page, parseInt(number, 10) * 1000);
+});
+
+/**
+ * Wait UP TO a number of minutes for the page to settle.
+ *
+ * Example #1: When I wait 1 minute
+ * Example #2: When I wait 10 minutes
+ * Example #3: When we wait 1m
+ * Example #4: And wait 2m
+ * Example #5: And wait 2 minutes
+ *
+ */
+When(/^(I |we )*wait (\d+)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
+  await smartSettle(this.page, parseInt(number, 10) * 1000 * 60);
+});
+
+/**
+ * Wait UP TO a maximum number of minutes for the page to settle.
+ *
+ * Example #1: When I wait max of 1 minute
+ * Example #2: When I wait max of 10 minutes
+ * Example #3: When we wait max of 1m
+ * Example #4: And wait max of 2m
+ * Example #5: And wait max of 2 minutes
+ *
+ */
+When(/^(I |we )*wait max of (\d+)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
+  await smartSettle(this.page, parseInt(number, 10) * 1000 * 60);
+});
+
+/**
+ * Wait until the page is loaded.
+ *
+ * Example #1: When I wait until the page is loaded
+ * Example #2: When we wait until the page is loaded
+ * Example #3: When wait until page loaded
+ *
+ */
+When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounCase, theCase, withIs) {
+  await smartSettle(this.page, 10000);
+});
+
+/**
+ * Wait for active XHR/fetch requests to complete.
+ *
+ * Example #1: When I wait for AJAX to finish
+ * Example #2: And I wait for AJAX to finish
+ * Example #3: When we wait for AJAX to finish
+ * Example #4: And wait for AJAX to finish
+ *
+ */
+When(/^(I |we )*wait for AJAX to finish$/, async function (pronounCase) {
+  await smartSettle(this.page, 10000);
+});
+
+/**
+ * Wait for a modal dialog to appear or disappear.
+ *
+ * Example #1: When I wait for the modal to appear
+ * Example #2: When I wait for the modal to disappear
+ * Example #3: When we wait for modal to appear
+ * Example #4: And I wait for the modal dialog to disappear
+ *
+ */
+When(/^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$/, async function (pronounCase, theCase, dialogCase, appearOrDisappear) {
+  const state = appearOrDisappear === 'appear' ? 'visible' : 'hidden';
+  await waitForModalState(this.page, state, 10000, this);
+});
+
+/**
+ * Wait until a CSS selector becomes visible. Returns the moment the
+ * matching element is on screen (display !== 'none', visibility !== 'hidden',
+ * has a non-zero box). This is the canonical "wait until X appears" probe.
+ *
+ * Example #1: When I wait for "#dashboard" to appear
+ * Example #2: When I wait for ".success-banner" to appear
+ * Example #3: And I wait for "[data-testid=user-list]" to appear
+ * Example #4: When we wait for ".modal.show" to appear
+ * Example #5: When I press "Save"
+ *               And I wait for ".toast-success" to appear
+ *
+ */
+When(/^(I |we )*wait for "([^"]*)" to appear$/, async function (pronounCase, selector) {
+  await this.page.waitForSelector(selector, { state: 'visible', timeout: 10000 });
+});
+
+/**
+ * Wait until a CSS selector becomes hidden (display:none, visibility:hidden,
+ * detached, or zero-size).
+ *
+ * Example #1: When I wait for "#loading-spinner" to disappear
+ * Example #2: When I wait for ".overlay" to disappear
+ * Example #3: And I wait for ".modal.show" to disappear
+ * Example #4: When we wait for "[data-testid=skeleton]" to disappear
+ * Example #5: When I press "Submit"
+ *               And I wait for ".loader" to disappear
+ *               Then I should see "Saved"
+ *
+ */
+When(/^(I |we )*wait for "([^"]*)" to disappear$/, async function (pronounCase, selector) {
+  await this.page.waitForSelector(selector, { state: 'hidden', timeout: 10000 });
+});
+
+/**
+ * Wait until visible text appears anywhere on the page.
+ *
+ * Polls `document.body.innerText` every 100 ms for up to 10 s. Match is
+ * case-sensitive substring.
+ *
+ * Example #1: When I wait for the text "Dashboard" to appear
+ * Example #2: When I wait for the text "Loading complete" to appear
+ * Example #3: And I wait for text "Welcome" to appear
+ * Example #4: When we wait for the text "Order #1234" to appear
+ * Example #5: When I press "Submit"
+ *               And I wait for the text "Thank you" to appear
+ *
+ */
+When(/^(I |we )*wait for( the)* text "([^"]*)" to appear$/, async function (pronounCase, theCase, text) {
+  await this.page.waitForFunction(
+    (t) => document.body && document.body.innerText.includes(t),
+    text, { timeout: 10000, polling: 100 }
+  );
+});
+
+/**
+ * Wait until visible text is gone from the page.
+ *
+ * Example #1: When I wait for the text "Loading…" to disappear
+ * Example #2: When I wait for the text "Saving" to disappear
+ * Example #3: And I wait for text "Pending" to disappear
+ * Example #4: When we wait for the text "Connecting" to disappear
+ * Example #5: When I press "Submit"
+ *               And I wait for the text "Validating" to disappear
+ *               Then I should see "Done"
+ *
+ */
+When(/^(I |we )*wait for( the)* text "([^"]*)" to disappear$/, async function (pronounCase, theCase, text) {
+  await this.page.waitForFunction(
+    (t) => !document.body || !document.body.innerText.includes(t),
+    text, { timeout: 10000, polling: 100 }
+  );
+});
+
+/**
+ * Wait until the current URL contains a fragment.
+ *
+ * Useful after a redirect, push-state navigation, or hash-based routing.
+ *
+ * Example #1: When I wait until the URL contains "/dashboard"
+ * Example #2: When I wait until the URL contains "?step=2"
+ * Example #3: And I wait until the URL contains "#confirmation"
+ * Example #4: When we wait until the URL contains "/orders/"
+ * Example #5: When I follow "Sign in"
+ *               And I wait until the URL contains "/auth/callback"
+ *
+ */
+When(/^(I |we )*wait until( the)* URL contains "([^"]*)"$/, async function (pronounCase, theCase, fragment) {
+  await this.page.waitForFunction(
+    (frag) => window.location.href.includes(frag),
+    fragment, { timeout: 10000, polling: 100 }
+  );
+});
+
+/**
+ * Wait until `document.title` equals (`is`) or contains the given value.
+ *
+ * Example #1: When I wait until the page title is "Dashboard - MyApp"
+ * Example #2: When I wait until the page title contains "Dashboard"
+ * Example #3: And I wait until the page title contains "(3 unread)"
+ * Example #4: When we wait until the page title is "Order Placed"
+ * Example #5: When I follow "Inbox"
+ *               And I wait until the page title contains "Inbox"
+ *
+ */
+When(/^(I |we )*wait until( the)* page title (is|contains) "([^"]*)"$/, async function (pronounCase, theCase, op, value) {
+  await this.page.waitForFunction(
+    ({ op, value }) => op === 'is' ? document.title === value : document.title.includes(value),
+    { op, value }, { timeout: 10000, polling: 100 }
+  );
+});
+
+/**
+ * Wait until exactly N elements match a CSS selector.
+ *
+ * Use 0 to wait for elements to disappear, or a positive count to wait for
+ * a specific number to render.
+ *
+ * Example #1: When I wait until 5 elements match ".product-card"
+ * Example #2: When I wait until 0 elements match ".loading-skeleton"
+ * Example #3: And I wait until 1 element matches ".active-row"
+ * Example #4: When we wait until 10 elements match "tr.user"
+ * Example #5: When I press "Load more"
+ *               And I wait until 20 elements match ".feed-item"
+ *
+ */
+When(/^(I |we )*wait until (\d+) elements? match(?:es)? "([^"]*)"$/, async function (pronounCase, count, selector) {
+  const expected = parseInt(count, 10);
+  await this.page.waitForFunction(
+    ({ sel, n }) => document.querySelectorAll(sel).length === n,
+    { sel: selector, n: expected }, { timeout: 10000, polling: 100 }
+  );
+});
+
+/**
+ * Wait until at least N elements match a CSS selector.
+ *
+ * Useful for infinite-scroll / pagination tests where the lower bound matters
+ * but the exact count may vary.
+ *
+ * Example #1: When I wait until at least 3 elements match ".item"
+ * Example #2: When I wait until at least 1 element matches ".notification"
+ * Example #3: And I wait until at least 10 elements match ".feed-item"
+ * Example #4: When we wait until at least 5 elements match "tr"
+ * Example #5: When I scroll to the bottom
+ *               And I wait until at least 25 elements match ".product-card"
+ *
+ */
+When(/^(I |we )*wait until at least (\d+) elements? match(?:es)? "([^"]*)"$/, async function (pronounCase, count, selector) {
+  const expected = parseInt(count, 10);
+  await this.page.waitForFunction(
+    ({ sel, n }) => document.querySelectorAll(sel).length >= n,
+    { sel: selector, n: expected }, { timeout: 10000, polling: 100 }
+  );
+});
+
+/**
+ * Wait until the network goes quiet (full smart settle, 10 s budget).
+ *
+ * Three equivalent phrasings.
+ *
+ * Example #1: When I wait until the network is idle
+ * Example #2: And I wait until requests are complete
+ * Example #3: When we wait until network goes quiet
+ * Example #4: When I press "Search"
+ *               And I wait until the network is idle
+ *               Then I should see "Results"
+ * Example #5: When I press "Refresh"
+ *               And I wait until requests are complete
+ *
+ */
+When(/^(I |we )*wait until (the network is idle|requests are complete|network goes quiet)$/, async function () {
+  await smartSettle(this.page, 10000);
+});
+
+/**
+ * Wait until the page is interactive (DOMContentLoaded + body attached).
+ *
+ * Lighter than `wait until the network is idle` — does not wait for late
+ * fetch/XHR. Useful when you need to interact with the document early.
+ *
+ * Example #1: When I wait until the page is interactive
+ * Example #2: Given I am on "/heavy-page"
+ *               When I wait until the page is interactive
+ * Example #3: And I wait until the page is interactive
+ * Example #4: When we wait until the page is interactive
+ * Example #5: Given I am on "/spa"
+ *               When I wait until the page is interactive
+ *               Then "<#root>" should be attached
+ *
+ */
+When(/^(I |we )*wait until( the)* page is interactive$/, async function () {
+  await this.page.waitForSelector('body', { state: 'attached', timeout: 10000 });
+  await this.page.waitForLoadState('domcontentloaded', { timeout: 10000 });
+});
+
+/**
+ * Wait until every tracked `setTimeout` callback has fired.
+ *
+ * Catches "fade-out then display:none" close transitions, debounced renders,
+ * and any UI flow that schedules a delayed update without making a network
+ * request. Reads `window.__varbaseE2ePendingTimers`, the counter installed by
+ * varbase-e2e.js's init script.
+ *
+ * Example #1: When I wait until pending timers settle
+ * Example #2: When I press "Close"
+ *               And I wait until pending timers settle
+ *               Then I should not see the modal
+ * Example #3: And I wait until pending timers settle
+ * Example #4: When we wait until pending timers settle
+ * Example #5: When I press "Toast"
+ *               And I wait until pending timers settle
+ *               Then I should not see "Saved"
+ *
+ */
+When(/^(I |we )*wait until pending timers settle$/, async function () {
+  await this.page.waitForFunction(
+    () => {
+      const t = window.__varbaseE2ePendingTimers;
+      return typeof t !== 'number' || t <= 0;
+    },
+    null, { timeout: 10000, polling: 100 }
+  );
+});
+
+/**
+ * Pollable text assertion — retries the inner step until passing or timeout.
+ *
+ * Use sparingly; prefer explicit edge waits (`wait for "X" to appear`).
+ *
+ * Example #1: Then eventually I should see "Done"
+ * Example #2: Then eventually I should see "Loaded" within 5 seconds
+ * Example #3: And eventually we should see "Saved"
+ * Example #4: Then eventually I should see "Order Confirmed" within 30 seconds
+ * Example #5: When I press "Submit"
+ *               Then eventually I should see "Submitted" within 8 seconds
+ *
+ */
+When(/^eventually (I |we )*should see "([^"]*)"(?: within (\d+) seconds?)?$/, async function (pronoun, text, seconds) {
+  const total = (seconds ? parseInt(seconds, 10) : 10) * 1000;
+  await this.page.waitForFunction(
+    (t) => document.body && document.body.innerText.includes(t),
+    text, { timeout: total, polling: 100 }
+  );
+});

package/tests/step-definitions/web-first.steps.js

@@ -0,0 +1,298 @@
+'use strict';
+
+const { friendly } = require('./varbase-e2e');
+
+// Web-first assertion steps — each matcher polls the live page until the
+// condition holds or the per-step timeout elapses. The assertion IS the
+// wait, so no `wait for AJAX` is required between an action and its check.
+//
+// Pattern (all steps):  "<selector>" should [not] be <state>  [within N seconds]
+// Default budget is 5s; override with the trailing "within N seconds" clause.
+
+const { Then, When } = require('@cucumber/cucumber');
+const assert = require('assert');
+
+function parseTimeout(secondsStr) {
+  const n = secondsStr ? parseInt(secondsStr, 10) : 0;
+  return n > 0 ? n * 1000 : 5000;
+}
+
+// Poll fn() until it returns truthy, or timeout. fn() returns a value;
+// `predicate` decides pass/fail. Returns the last value seen.
+async function poll(fn, predicate, timeout, message) {
+  const deadline = Date.now() + timeout;
+  let last;
+  while (Date.now() < deadline) {
+    try {
+      last = await fn();
+      if (predicate(last)) return last;
+    } catch (e) {
+      last = e;
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw friendly(`${message} (last seen: ${typeof last === 'object' ? JSON.stringify(last) : String(last)})`);
+}
+
+async function checkState(locator, state) {
+  switch (state) {
+    case 'visible':  return locator.first().isVisible();
+    case 'hidden':   return !(await locator.first().isVisible().catch(() => false));
+    case 'attached': return (await locator.count()) > 0;
+    case 'focused':  return locator.first().evaluate((el) => el === document.activeElement);
+    case 'enabled':  return locator.first().isEnabled();
+    case 'disabled': return locator.first().isDisabled();
+    case 'editable': return locator.first().isEditable();
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// State matchers
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-retrying state assertion. Polls the live page until the matcher passes
+ * or the budget elapses. Default budget 5 s.
+ *
+ * Example #1: Then "#dashboard" should be visible
+ * Example #2: Then ".success-banner" should be visible within 10 seconds
+ * Example #3: And "[data-testid=signup-cta]" should be focused
+ * Example #4: Then "button.submit" should be enabled
+ * Example #5: Then "input#email" should be editable
+ *
+ */
+Then(/^"([^"]*)" should be (visible|hidden|attached|focused|enabled|disabled|editable)(?: within (\d+) seconds?)?$/, async function (selector, state, sec) {
+  const loc = this.page.locator(selector);
+  await poll(
+    () => checkState(loc, state),
+    (v) => v === true,
+    parseTimeout(sec),
+    `Expected "${selector}" to be ${state}`
+  );
+});
+
+/**
+ * Auto-retrying negated state assertion.
+ *
+ * Example #1: Then "#loading-spinner" should not be visible
+ * Example #2: Then ".error" should not be visible within 5 seconds
+ * Example #3: And "button.submit" should not be disabled
+ * Example #4: Then "input#email" should not be editable
+ * Example #5: Then "[data-testid=password]" should not be focused
+ *
+ */
+Then(/^"([^"]*)" should not be (visible|hidden|attached|focused|enabled|disabled|editable)(?: within (\d+) seconds?)?$/, async function (selector, state, sec) {
+  const loc = this.page.locator(selector);
+  await poll(
+    () => checkState(loc, state),
+    (v) => v === false,
+    parseTimeout(sec),
+    `Expected "${selector}" to not be ${state}`
+  );
+});
+
+/**
+ * Assert an element's bounding box overlaps the visible viewport rectangle.
+ *
+ * Example #1: Then "#hero" should be in the viewport
+ * Example #2: Then "[data-testid=cta]" should be in the viewport within 3 seconds
+ * Example #3: When I scroll to the element "#footer"
+ *               Then "#footer" should be in the viewport
+ * Example #4: Then "h1" should be in the viewport
+ * Example #5: Then ".banner" should be in the viewport
+ *
+ */
+Then(/^"([^"]*)" should be in the viewport(?: within (\d+) seconds?)?$/, async function (selector, sec) {
+  const loc = this.page.locator(selector).first();
+  await poll(
+    async () => loc.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      return r.bottom > 0 && r.top < (window.innerHeight || 0)
+          && r.right > 0 && r.left < (window.innerWidth || 0);
+    }),
+    (v) => v === true,
+    parseTimeout(sec),
+    `Expected "${selector}" to be in viewport`
+  );
+});
+
+/**
+ * Assert an element is OUTSIDE the visible viewport rectangle.
+ *
+ * Example #1: Then "#footer" should not be in the viewport
+ * Example #2: Then "[data-testid=hidden]" should not be in the viewport within 3 seconds
+ * Example #3: And ".off-screen" should not be in the viewport
+ * Example #4: Then "section.below-fold" should not be in the viewport
+ * Example #5: When I scroll to the top
+ *               Then "#footer" should not be in the viewport
+ *
+ */
+Then(/^"([^"]*)" should not be in the viewport(?: within (\d+) seconds?)?$/, async function (selector, sec) {
+  const loc = this.page.locator(selector).first();
+  await poll(
+    async () => loc.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      return r.bottom > 0 && r.top < (window.innerHeight || 0)
+          && r.right > 0 && r.left < (window.innerWidth || 0);
+    }).catch(() => false),
+    (v) => v === false,
+    parseTimeout(sec),
+    `Expected "${selector}" to not be in viewport`
+  );
+});
+
+/**
+ * Assert exactly N elements match a selector (auto-retry).
+ *
+ * Example #1: Then ".product-card" should have a count of 12
+ * Example #2: Then ".error" should have a count of 0 within 5 seconds
+ * Example #3: And "tr" should have a count of 21
+ * Example #4: Then "[data-testid=item]" should have a count of 5
+ * Example #5: Then ".feed-item" should have a count of 25 within 10 seconds
+ *
+ */
+Then(/^"([^"]*)" should have a count of (\d+)(?: within (\d+) seconds?)?$/, async function (selector, count, sec) {
+  const expected = parseInt(count, 10);
+  const loc = this.page.locator(selector);
+  await poll(
+    () => loc.count(),
+    (v) => v === expected,
+    parseTimeout(sec),
+    `Expected "${selector}" count to be ${expected}`
+  );
+});
+
+/**
+ * Assert an element's textContent equals an expected string (trimmed).
+ *
+ * Example #1: Then "h1" should have text "Welcome"
+ * Example #2: Then ".badge" should have text "12" within 3 seconds
+ * Example #3: And ".total" should have text "$99.00"
+ * Example #4: Then "[data-testid=subtitle]" should have text "Premium"
+ * Example #5: Then ".alert" should have text "Saved"
+ *
+ */
+Then(/^"([^"]*)" should have text "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, text, sec) {
+  const loc = this.page.locator(selector).first();
+  await poll(
+    () => loc.textContent(),
+    (v) => (v || '').trim() === text,
+    parseTimeout(sec),
+    `Expected "${selector}" text to be "${text}"`
+  );
+});
+
+/**
+ * Assert an element's textContent contains an expected substring.
+ *
+ * Example #1: Then "h1" should contain text "Welcome"
+ * Example #2: Then ".badge" should contain text "unread" within 3 seconds
+ * Example #3: And ".total" should contain text "$99"
+ * Example #4: Then "[data-testid=subtitle]" should contain text "Premium"
+ * Example #5: Then ".alert" should contain text "Saved"
+ *
+ */
+Then(/^"([^"]*)" should contain text "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, text, sec) {
+  const loc = this.page.locator(selector).first();
+  await poll(
+    () => loc.textContent(),
+    (v) => (v || '').includes(text),
+    parseTimeout(sec),
+    `Expected "${selector}" to contain text "${text}"`
+  );
+});
+
+/**
+ * Assert an input's `value` property equals an expected string.
+ *
+ * Example #1: Then "#email" should have value "alice@example.com"
+ * Example #2: Then "input[name=q]" should have value "laptops"
+ * Example #3: And "[data-testid=phone]" should have value "0790000000"
+ * Example #4: Then "#bio" should have value "" within 3 seconds
+ * Example #5: Then "select#country" should have value "JO"
+ *
+ */
+Then(/^"([^"]*)" should have value "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, value, sec) {
+  const loc = this.page.locator(selector).first();
+  await poll(
+    () => loc.inputValue(),
+    (v) => v === value,
+    parseTimeout(sec),
+    `Expected "${selector}" value to be "${value}"`
+  );
+});
+
+/**
+ * Assert an element's attribute equals an expected value.
+ *
+ * Example #1: Then "#tab-1" should have attribute "aria-selected" with value "true"
+ * Example #2: Then "[data-testid=cta]" should have attribute "data-state" with value "open"
+ * Example #3: And "img.logo" should have attribute "alt" with value "Vardot"
+ * Example #4: Then "a.signup" should have attribute "href" with value "/signup"
+ * Example #5: Then "input#email" should have attribute "type" with value "email"
+ *
+ */
+Then(/^"([^"]*)" should have attribute "([^"]*)" with value "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, attr, value, sec) {
+  const loc = this.page.locator(selector).first();
+  await poll(
+    () => loc.getAttribute(attr),
+    (v) => v === value,
+    parseTimeout(sec),
+    `Expected "${selector}" attribute "${attr}" to be "${value}"`
+  );
+});
+
+/**
+ * Assert an element's `class` attribute contains a class token.
+ *
+ * Example #1: Then "#tab-1" should have class "is-active"
+ * Example #2: Then ".modal" should have class "show" within 3 seconds
+ * Example #3: And ".dropdown" should have class "open"
+ * Example #4: Then "tr.row-1" should have class "selected"
+ * Example #5: Then "[data-testid=card]" should have class "highlighted"
+ *
+ */
+Then(/^"([^"]*)" should have class "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, cls, sec) {
+  const loc = this.page.locator(selector).first();
+  await poll(
+    () => loc.getAttribute('class'),
+    (v) => (v || '').split(/\s+/).includes(cls),
+    parseTimeout(sec),
+    `Expected "${selector}" to have class "${cls}"`
+  );
+});
+
+/**
+ * Click an element by its accessible role + name (Playwright `getByRole`).
+ *
+ * Example #1: When I click the "Sign in" button
+ * Example #2: When I click the "Profile" link
+ * Example #3: And we click the "Notifications" tab
+ * Example #4: When I click the "Subscribe" checkbox
+ * Example #5: When I click the "Premium" radio
+ *
+ */
+When(/^(I |we )*click the "([^"]*)" (button|link|tab|menuitem|checkbox|radio|option)$/, async function (pronoun, name, role) {
+  await this.page.getByRole(role, { name }).first().click();
+});
+
+/**
+ * Assert a role-addressed element is visible (auto-retry).
+ *
+ * Example #1: Then the "Save changes" button should be visible
+ * Example #2: Then the "Profile" link should be visible within 5 seconds
+ * Example #3: And the "Privacy" tab should be visible
+ * Example #4: Then the "I agree" checkbox should be visible
+ * Example #5: Then the "Premium" radio should be visible
+ *
+ */
+Then(/^the "([^"]*)" (button|link|tab|menuitem|checkbox|radio|option) should be visible(?: within (\d+) seconds?)?$/, async function (name, role, sec) {
+  const loc = this.page.getByRole(role, { name }).first();
+  await poll(
+    () => loc.isVisible(),
+    (v) => v === true,
+    parseTimeout(sec),
+    `Expected ${role} "${name}" to be visible`
+  );
+});