@vardot/varbase-e2e 2.0.0

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

@@ -0,0 +1,228 @@
+'use strict';
+
+const { friendly } = require('./varbase-e2e');
+
+// Iframe / frame steps backed by Playwright's `frameLocator` API.
+//
+// Frames are addressed by CSS selector. Once switched, frame-scoped
+// interaction steps target the chosen frame instead of the main document.
+// Switch back with "I switch to the root document".
+
+const { When, Then } = require('@cucumber/cucumber');
+const assert = require('assert');
+
+function frameRoot(world) {
+  return world.frame || world.page;
+}
+
+function explain(action, detail, e) {
+  return friendly({
+    action,
+    cause: e,
+    hint: `wait for the iframe to load first ("When I wait for \\"iframe\\" to appear"). Detail: ${detail}.`,
+  });
+}
+
+/**
+ * Switch the active scope to an iframe addressed by CSS selector.
+ *
+ * Example #1: When I switch to iframe "iframe.payment"
+ * Example #2: When I switch to the iframe "#stripe-frame"
+ * Example #3: And we switch to iframe "iframe[name=widget]"
+ * Example #4: When I switch to iframe ".captcha-frame"
+ * Example #5: When I switch to the iframe "iframe[src*=embed]"
+ *
+ */
+When(/^(I |we )*switch to (the )?iframe "([^"]*)"$/, async function (pronoun, theCase, sel) {
+  try {
+    if (!this._rootPage) this._rootPage = this.page;
+    this.frame = this.page.frameLocator(sel);
+  } catch (e) {
+    throw explain(`switch to iframe "${sel}"`, `selector tried: ${sel}`, e);
+  }
+});
+
+/**
+ * Switch the active scope to an iframe by Playwright frame-locator string.
+ *
+ * Example #1: When I switch to iframe with locator "iframe.payment"
+ * Example #2: When I switch to iframe with locator "#stripe-frame"
+ * Example #3: And I switch to iframe with locator "iframe[name=widget]"
+ * Example #4: When I switch to iframe with locator ".captcha-frame"
+ * Example #5: When I switch to iframe with locator "iframe[src*=embed]"
+ *
+ */
+When(/^(I |we )*switch to iframe with locator "([^"]*)"$/, async function (pronoun, sel) {
+  try {
+    if (!this._rootPage) this._rootPage = this.page;
+    this.frame = this.page.frameLocator(sel);
+  } catch (e) {
+    throw explain(`switch to iframe with locator "${sel}"`, `locator: ${sel}`, e);
+  }
+});
+
+/**
+ * Return the active scope to the top document (clear the iframe scope).
+ *
+ * Example #1: When I switch to the root document
+ * Example #2: When I switch to iframe ".captcha"
+ *               And I click "I am not a robot" inside the iframe
+ *               And I switch to the root document
+ * Example #3: And we switch to the root document
+ * Example #4: When I switch to iframe "#payment"
+ *               And I press "Pay"
+ *               And I switch to the root document
+ *               Then I should see "Payment received"
+ * Example #5: When I switch to the root document
+ *               And I press "Refresh"
+ *
+ */
+When(/^(I |we )*switch to the root document$/, async function () {
+  this.frame = null;
+});
+
+/**
+ * Switch the active scope to an iframe by its `title` attribute.
+ *
+ * Example #1: When I switch to the iframe with title "Payment"
+ * Example #2: When I switch to the iframe with title "Captcha"
+ * Example #3: And we switch to the iframe with title "Widget"
+ * Example #4: When I switch to the iframe with title "Embedded video"
+ * Example #5: When I switch to the iframe with title "Stripe checkout"
+ *
+ */
+When(/^(I |we )*switch to the iframe with title "([^"]*)"$/, async function (pronoun, title) {
+  try {
+    if (!this._rootPage) this._rootPage = this.page;
+    this.frame = this.page.frameLocator(`iframe[title="${title}"]`);
+  } catch (e) {
+    throw explain(`switch to iframe by title "${title}"`, `selector: iframe[title="${title}"]`, e);
+  }
+});
+
+/**
+ * Switch the active scope to an iframe by its `name` attribute.
+ *
+ * Example #1: When I switch to the iframe with name "payment"
+ * Example #2: When I switch to the iframe with name "captcha"
+ * Example #3: And we switch to the iframe with name "widget"
+ * Example #4: When I switch to the iframe with name "embed"
+ * Example #5: When I switch to the iframe with name "stripe"
+ *
+ */
+When(/^(I |we )*switch to the iframe with name "([^"]*)"$/, async function (pronoun, name) {
+  try {
+    if (!this._rootPage) this._rootPage = this.page;
+    this.frame = this.page.frameLocator(`iframe[name="${name}"]`);
+  } catch (e) {
+    throw explain(`switch to iframe by name "${name}"`, `selector: iframe[name="${name}"]`, e);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Frame-scoped click + fill + assertions
+// ---------------------------------------------------------------------------
+
+/**
+ * Click visible text inside the active iframe.
+ *
+ * Example #1: When I click "Confirm" inside the iframe
+ * Example #2: When I click "Cancel" inside the iframe
+ * Example #3: And we click "Continue" inside the iframe
+ * Example #4: When I click "OK" inside the iframe
+ * Example #5: When I click "Close" inside the iframe
+ *
+ */
+When(/^(I |we )*click "([^"]*)" inside the iframe$/, async function (pronoun, text) {
+  try {
+    const root = frameRoot(this);
+    if (!root.locator) throw friendly('No active iframe. Switch first.');
+    await root.locator(`text="${text}"`).first().click();
+  } catch (e) {
+    throw friendly({
+      action: `click "${text}" inside the iframe`,
+      cause: e,
+      hint: `switch to the iframe first ("When I switch to iframe '<selector>'"), then check the visible text matches exactly.`,
+    });
+  }
+});
+
+/**
+ * Click an attribute-addressed element inside the active iframe.
+ *
+ * Tries id, class, name, and data-testid in that order.
+ *
+ * Example #1: When I click "submit-btn" by attr inside the iframe
+ * Example #2: When I click "cancel" by attr inside the iframe
+ * Example #3: And we click "continue" by attr inside the iframe
+ * Example #4: When I click "close" by attr inside the iframe
+ * Example #5: When I click "primary-cta" by attr inside the iframe
+ *
+ */
+When(/^(I |we )*click "([^"]*)" by attr inside the iframe$/, async function (pronoun, attrValue) {
+  try {
+    const root = frameRoot(this);
+    await root.locator(`#${attrValue}, .${attrValue}, [name="${attrValue}"], [data-testid="${attrValue}"]`).first().click();
+  } catch (e) {
+    throw friendly({
+      action: `click "${attrValue}" by attribute inside the iframe`,
+      cause: e,
+      hint: `switch to the iframe first; checked id, class, [name], [data-testid] — none matched.`,
+    });
+  }
+});
+
+/**
+ * Fill a field inside the active iframe by `[name]` or id.
+ *
+ * Example #1: When I fill in "card_number" with "4242 4242 4242 4242" inside the iframe
+ * Example #2: When I fill in "cvv" with "123" inside the iframe
+ * Example #3: And we fill in "exp_date" with "12/30" inside the iframe
+ * Example #4: When I fill in "email" with "alice@example.com" inside the iframe
+ * Example #5: When I fill in "name" with "Alice" inside the iframe
+ *
+ */
+When(/^(I |we )*fill in "([^"]*)" with "([^"]*)" inside the iframe$/, async function (pronoun, field, value) {
+  try {
+    const root = frameRoot(this);
+    await root.locator(`[name="${field}"], #${field}`).first().fill(value);
+  } catch (e) {
+    throw friendly({
+      action: `fill "${field}" inside the iframe`,
+      cause: e,
+      hint: `switch to the iframe first; checked [name] and id — neither matched.`,
+    });
+  }
+});
+
+/**
+ * Assert visible text exists inside the active iframe.
+ *
+ * Example #1: Then I should see "Payment received" inside the iframe
+ * Example #2: Then I should see "Welcome" inside the iframe
+ * Example #3: And I should see "Confirmed" inside the iframe
+ * Example #4: Then I should see "Email verified" inside the iframe
+ * Example #5: Then I should see "Subscribed" inside the iframe
+ *
+ */
+Then(/^I should see "([^"]*)" inside the iframe$/, async function (text) {
+  const root = frameRoot(this);
+  const count = await root.locator(`text="${text}"`).count();
+  assert.ok(count > 0, `Expected to see "${text}" inside the iframe.`);
+});
+
+/**
+ * Assert visible text does NOT exist inside the active iframe.
+ *
+ * Example #1: Then I should not see "Error" inside the iframe
+ * Example #2: Then I should not see "Declined" inside the iframe
+ * Example #3: And I should not see "Loading" inside the iframe
+ * Example #4: Then I should not see "Pending" inside the iframe
+ * Example #5: Then I should not see "Try again" inside the iframe
+ *
+ */
+Then(/^I should not see "([^"]*)" inside the iframe$/, async function (text) {
+  const root = frameRoot(this);
+  const count = await root.locator(`text="${text}"`).count();
+  assert.strictEqual(count, 0, `Expected NOT to see "${text}" inside the iframe.`);
+});

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

@@ -0,0 +1,202 @@
+'use strict';
+
+const { friendly } = require('./varbase-e2e');
+
+// Pointer input steps not covered by the core element/click steps:
+// hover variants, drag-and-drop, double-click, right-click, viewport size.
+
+const { When } = require('@cucumber/cucumber');
+
+function explainPtr(action, sel, e) {
+  return friendly({
+    action: `${action} "${sel}"`,
+    cause: e,
+    hint: `check the element exists on the page, is visible, and is not covered by an overlay.`,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Hover (variants)
+// ---------------------------------------------------------------------------
+
+/**
+ * Hover the mouse pointer over a CSS-addressed element.
+ *
+ * Example #1: When I hover over "#nav-products"
+ * Example #2: When I hover over ".tooltip-trigger"
+ * Example #3: And we hover over "[data-testid=user-menu]"
+ * Example #4: When I hover over "button.help"
+ * Example #5: When I hover over ".chart-bar:nth-child(3)"
+ *
+ */
+When(/^(I |we )*hover over "([^"]*)"$/, async function (pronoun, sel) {
+  try { await this.page.locator(sel).first().hover(); }
+  catch (e) { throw explainPtr('hover over', sel, e); }
+});
+
+/**
+ * Move the mouse pointer over a CSS-addressed element (alias for hover).
+ *
+ * Example #1: When I move the pointer to "#cta"
+ * Example #2: When we move the pointer to ".dropdown-trigger"
+ * Example #3: And I move the pointer to "[data-testid=avatar]"
+ * Example #4: When I move the pointer to "img.gallery-thumb"
+ * Example #5: When I move the pointer to ".legend-item"
+ *
+ */
+When(/^(I |we )*move the pointer to "([^"]*)"$/, async function (pronoun, sel) {
+  try { await this.page.locator(sel).first().hover(); }
+  catch (e) { throw explainPtr('move pointer to', sel, e); }
+});
+
+// ---------------------------------------------------------------------------
+// Click variants
+// ---------------------------------------------------------------------------
+
+/**
+ * Double-click on a CSS-addressed element.
+ *
+ * Example #1: When I double-click on "#row-1"
+ * Example #2: When I double click on ".file-tile"
+ * Example #3: And we double-click on "[data-testid=cell-A1]"
+ * Example #4: When I double-click on "img.editable"
+ * Example #5: When I double click on "td.editable-cell"
+ *
+ */
+When(/^(I |we )*double[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
+  try { await this.page.locator(sel).first().dblclick(); }
+  catch (e) { throw explainPtr('double-click', sel, e); }
+});
+
+/**
+ * Right-click (context menu) on a CSS-addressed element.
+ *
+ * Example #1: When I right-click on "#row-1"
+ * Example #2: When I right click on ".tree-node"
+ * Example #3: And we right-click on "[data-testid=image]"
+ * Example #4: When I right-click on "li.contact"
+ * Example #5: When I right click on "td.cell"
+ *
+ */
+When(/^(I |we )*right[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
+  try { await this.page.locator(sel).first().click({ button: 'right' }); }
+  catch (e) { throw explainPtr('right-click', sel, e); }
+});
+
+/**
+ * Middle-click on a CSS-addressed element.
+ *
+ * Example #1: When I middle-click on "a.external"
+ * Example #2: When I middle click on "#tab-2"
+ * Example #3: And we middle-click on "[data-testid=link]"
+ * Example #4: When I middle-click on "li.bookmark"
+ * Example #5: When I middle click on "a.product-link"
+ *
+ */
+When(/^(I |we )*middle[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
+  try { await this.page.locator(sel).first().click({ button: 'middle' }); }
+  catch (e) { throw explainPtr('middle-click', sel, e); }
+});
+
+/**
+ * Click on a CSS-addressed element while holding a modifier key.
+ *
+ * Modifier names follow Playwright: `Shift`, `Control`, `Alt`, `Meta`.
+ *
+ * Example #1: When I click on "#row-1" while holding "Shift"
+ * Example #2: When I click on ".checkbox" while holding "Control"
+ * Example #3: And we click on "a.external" while holding "Meta"
+ * Example #4: When I click on ".item" while holding "Alt"
+ * Example #5: When I click on "#tab-2" while holding "Shift"
+ *
+ */
+When(/^(I |we )*click on "([^"]*)" while holding "([^"]*)"$/, async function (pronoun, sel, key) {
+  try {
+    await this.page.locator(sel).first().click({ modifiers: [key] });
+  } catch (e) {
+    throw friendly({
+      action: `click "${sel}" while holding "${key}"`,
+      cause: e,
+      hint: `modifier must be one of: Shift, Control, Alt, Meta.`,
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Drag and drop
+// ---------------------------------------------------------------------------
+
+/**
+ * Drag a source element onto a target element.
+ *
+ * Example #1: When I drag "#card-1" to "#column-done"
+ * Example #2: When I drag ".file-tile" to "#trash"
+ * Example #3: And we drag "[data-testid=task-1]" to "[data-testid=in-progress]"
+ * Example #4: When I drag "#image" to "#canvas"
+ * Example #5: When I drag "li.draggable" to "ul.dropzone"
+ *
+ */
+When(/^(I |we )*drag "([^"]*)" to "([^"]*)"$/, async function (pronoun, source, target) {
+  try {
+    await this.page.locator(source).first().dragTo(this.page.locator(target).first());
+  } catch (e) {
+    throw friendly({
+      action: `drag "${source}" to "${target}"`,
+      cause: e,
+      hint: `both items must exist on the page; the target must accept drops.`,
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Viewport
+// ---------------------------------------------------------------------------
+
+/**
+ * Resize the browser viewport to a specific WxH.
+ *
+ * Example #1: When I set the viewport size to 1280x720
+ * Example #2: When I set the viewport size to 375x667
+ * Example #3: And we set the viewport size to 768x1024
+ * Example #4: When I set the viewport size to 1920x1080
+ * Example #5: When I set the viewport size to 320x568
+ *
+ */
+When(/^(I |we )*set the viewport size to (\d+)x(\d+)$/, async function (pronoun, w, h) {
+  try {
+    await this.page.setViewportSize({ width: parseInt(w, 10), height: parseInt(h, 10) });
+  } catch (e) {
+    throw friendly({
+      action: `set viewport size to ${w}x${h}`,
+      cause: e,
+      hint: `the browser was opened in fluid-viewport mode; set a fixed viewport in playwright.config.ts contextOptions.viewport.`,
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Tap (touch)
+// ---------------------------------------------------------------------------
+
+/**
+ * Touch-tap a CSS-addressed element. Falls back to a regular click if the
+ * browser context was not opened with `hasTouch: true`.
+ *
+ * Example #1: When I tap on "#cta"
+ * Example #2: When I tap on ".bottom-nav-item"
+ * Example #3: And we tap on "[data-testid=fab]"
+ * Example #4: When I tap on "button.menu"
+ * Example #5: When I tap on ".swipe-card"
+ *
+ */
+When(/^(I |we )*tap on "([^"]*)"$/, async function (pronoun, sel) {
+  try {
+    await this.page.locator(sel).first().tap();
+  } catch (e) {
+    if (/hasTouch/i.test(e.message)) {
+      await this.page.locator(sel).first().click();
+    } else {
+      throw e;
+    }
+  }
+});

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

@@ -0,0 +1,232 @@
+'use strict';
+
+// Auto-detect JavaScript errors during test execution.
+//
+// Listeners are attached on Before (order 200) once a page is open:
+//   page.on('pageerror')           → uncaught errors
+//   page.on('console', level)      → console messages (filtered by config)
+//
+// After every scenario the collector reports per the active "mode":
+//   - 'warn' (default)  → log a yellow warning, scenario still passes
+//   - 'fail'            → assert.fail with the error list
+//   - 'off'             → silent
+//
+// Mode resolution priority (first match wins):
+//   1. scenario tag       @js-fail / @js-warn / @js-off / @javascript / @js-errors
+//   2. env var            VARBASE_E2E_JS_ERROR_MODE = warn | fail | off
+//   3. worldParameters    parameters.javascript.mode
+//   4. default            'warn'
+//
+// Back-compat: @javascript → fail (legacy "always fail" tag). @js-errors → off.
+
+const { Before, After, Then } = require('@cucumber/cucumber');
+const assert = require('assert');
+
+const VALID_MODES = new Set(['warn', 'fail', 'off']);
+const DEFAULT_CONSOLE_LEVELS = ['error'];
+
+/**
+ * Resolve effective settings for the current scenario.
+ *
+ * @returns {{ mode: 'warn'|'fail'|'off', levels: string[], ignore: RegExp|null,
+ *             beforeScenario: boolean, afterScenario: boolean }}
+ */
+function resolveSettings(world, scope) {
+  const cfg = (world.parameters && world.parameters.javascript) || {};
+  const tag = (name) => hasTag(scope, name);
+
+  let mode;
+  if (tag('@js-fail') || tag('@javascript'))      mode = 'fail';
+  else if (tag('@js-warn'))                        mode = 'warn';
+  else if (tag('@js-off') || tag('@js-errors'))    mode = 'off';
+  else if (process.env.VARBASE_E2E_JS_ERROR_MODE)      mode = process.env.VARBASE_E2E_JS_ERROR_MODE;
+  else if (cfg.mode)                               mode = cfg.mode;
+  else                                             mode = 'warn';
+  if (!VALID_MODES.has(mode)) mode = 'warn';
+
+  const levelsRaw =
+    process.env.VARBASE_E2E_JS_ERROR_LEVELS ||
+    (Array.isArray(cfg.levels) ? cfg.levels.join(',') : cfg.levels) ||
+    DEFAULT_CONSOLE_LEVELS.join(',');
+  const levels = String(levelsRaw).split(',').map((s) => s.trim()).filter(Boolean);
+
+  const ignoreSrc = process.env.VARBASE_E2E_JS_ERROR_IGNORE || cfg.ignore || null;
+  let ignore = null;
+  if (ignoreSrc) {
+    try { ignore = new RegExp(ignoreSrc); }
+    catch { ignore = null; }
+  }
+
+  const beforeScenario =
+    process.env.VARBASE_E2E_JS_ERROR_BEFORE === '1'
+      ? true
+      : cfg.beforeScenario === true;
+  const afterScenario  =
+    process.env.VARBASE_E2E_JS_ERROR_AFTER === '0'
+      ? false
+      : cfg.afterScenario !== false;   // default true
+
+  return { mode, levels, ignore, beforeScenario, afterScenario };
+}
+
+function hasTag(scope, name) {
+  if (!scope || !Array.isArray(scope.pickle && scope.pickle.tags)) return false;
+  return scope.pickle.tags.some((t) => t.name === name);
+}
+
+function formatErrors(errs) {
+  return errs.map((e, i) => `  ${i + 1}. [${e.type}] ${e.message}`).join('\n');
+}
+
+function filterErrors(errs, ignore) {
+  if (!ignore) return errs;
+  return errs.filter((e) => !ignore.test(e.message));
+}
+
+function reportWarning(scope, errs) {
+  const name = (scope && scope.pickle && scope.pickle.name) || 'scenario';
+  // Yellow ANSI when FORCE_COLOR is on, plain otherwise — let the runtime
+  // decide. cucumber-js sets FORCE_COLOR=1 by default in interactive shells.
+  const head = `[varbase-e2e] JavaScript errors during "${name}" (mode=warn):`;
+  process.stderr.write(`\n\x1b[33m${head}\n${formatErrors(errs)}\x1b[0m\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Before — attach listeners + (optional) pre-snapshot.
+// ---------------------------------------------------------------------------
+
+Before({ order: 200 }, function (scope) {
+  this._jsErrors = [];
+  this._jsErrorsAsserted = false;
+  this._jsSettings = resolveSettings(this, scope);
+  if (this._jsSettings.mode === 'off') return;
+  if (!this.page) return;
+
+  const levels = new Set(this._jsSettings.levels);
+  this.page.on('pageerror', (err) => {
+    this._jsErrors.push({ type: 'pageerror', message: String(err && err.message || err) });
+  });
+  this.page.on('console', (msg) => {
+    if (levels.has(msg.type())) {
+      this._jsErrors.push({ type: `console.${msg.type()}`, message: msg.text() });
+    }
+  });
+
+  if (this._jsSettings.beforeScenario) {
+    // Pre-scenario snapshot — typically empty unless the same page is reused.
+    const errs = filterErrors(this._jsErrors, this._jsSettings.ignore);
+    if (errs.length > 0) {
+      process.stderr.write(
+        `\n\x1b[33m[varbase-e2e] Pre-scenario JavaScript errors:\n${formatErrors(errs)}\x1b[0m\n`
+      );
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Steps
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that no JavaScript errors have been collected so far.
+ *
+ * Always fails on error (ignoring the active mode) — this is the explicit
+ * "hard check" step. Calling it also prevents the auto-report at scenario
+ * end so a single error is not reported twice.
+ *
+ * Example #1: Then there should be no JavaScript errors
+ * Example #2: And there should be no JavaScript errors
+ * Example #3: But there should be no JavaScript errors
+ * Example #4: Then there should be no JavaScript errors
+ * Example #5: Then there should be no JavaScript errors
+ *
+ */
+Then(/^there should be no JavaScript errors$/, function () {
+  this._jsErrorsAsserted = true;
+  const errs = filterErrors(this._jsErrors || [], this._jsSettings && this._jsSettings.ignore);
+  if (errs.length === 0) return;
+  assert.fail(`JavaScript errors detected:\n${formatErrors(errs)}`);
+});
+
+/**
+ * Assert that no JavaScript console warnings were collected. Requires
+ * 'warning' to be in the captured console levels (see worldParameters or
+ * VARBASE_E2E_JS_ERROR_LEVELS).
+ *
+ * Example #1: Then there should be no JavaScript warnings
+ * Example #2: And there should be no JavaScript warnings
+ * Example #3: But there should be no JavaScript warnings
+ * Example #4: Then there should be no JavaScript warnings
+ * Example #5: Then there should be no JavaScript warnings
+ *
+ */
+Then(/^there should be no JavaScript warnings$/, function () {
+  this._jsErrorsAsserted = true;
+  const errs = (this._jsErrors || []).filter((e) => e.type === 'console.warning');
+  if (errs.length === 0) return;
+  assert.fail(`JavaScript warnings detected:\n${formatErrors(errs)}`);
+});
+
+/**
+ * Assert that no collected JavaScript error message matches a regular
+ * expression. Useful when some noise is unavoidable but a specific bug
+ * pattern must never appear.
+ *
+ * Example #1: Then JavaScript errors should not match "TypeError"
+ * Example #2: Then JavaScript errors should not match "is not a function"
+ * Example #3: And JavaScript errors should not match "Cannot read property"
+ * Example #4: Then JavaScript errors should not match "ReferenceError: .* is not defined"
+ * Example #5: Then JavaScript errors should not match "Uncaught"
+ *
+ */
+Then(/^JavaScript errors should not match "([^"]*)"$/, function (pattern) {
+  let re;
+  try { re = new RegExp(pattern); }
+  catch (e) {
+    assert.fail(`Invalid regular expression: "${pattern}" — ${e.message}`);
+  }
+  const errs = (this._jsErrors || []).filter((e) => re.test(e.message));
+  if (errs.length === 0) return;
+  assert.fail(`JavaScript errors matched /${pattern}/:\n${formatErrors(errs)}`);
+});
+
+/**
+ * Print the JavaScript errors collected so far. Diagnostic only — never
+ * asserts, never fails. Useful inside a scenario being debugged.
+ *
+ * Example #1: Then print JavaScript errors
+ * Example #2: And print JavaScript errors
+ * Example #3: But print JavaScript errors
+ * Example #4: Then print JavaScript errors
+ * Example #5: Then print JavaScript errors
+ *
+ */
+Then(/^print JavaScript errors$/, function () {
+  const errs = this._jsErrors || [];
+  if (errs.length === 0) {
+    console.log('\n--- JavaScript errors: none ---');
+    return;
+  }
+  console.log('\n--- JavaScript errors ---');
+  console.log(formatErrors(errs));
+});
+
+// ---------------------------------------------------------------------------
+// After — report per mode.
+// ---------------------------------------------------------------------------
+
+After({ order: 200 }, function (scope) {
+  const s = this._jsSettings || resolveSettings(this, scope);
+  if (s.mode === 'off') return;
+  if (!s.afterScenario) return;
+  if (this._jsErrorsAsserted) return;            // already handled by explicit step
+
+  const errs = filterErrors(this._jsErrors || [], s.ignore);
+  if (errs.length === 0) return;
+
+  if (s.mode === 'fail') {
+    assert.fail(`JavaScript errors detected during scenario:\n${formatErrors(errs)}`);
+  } else {
+    reportWarning(scope, errs);
+  }
+});