@vardot/varbase-e2e 2.0.0

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

@@ -0,0 +1,458 @@
+'use strict';
+
+// -----------------------------------------------------------------------------
+// Varbase step definitions: the Varbase testing users registry, the welcome
+// tour, the default theme settings (sticky header), the international phone
+// field, the editorial accessibility checker, the responsive warm-up pass and
+// the working header / footer checklists.
+//
+// Ported from the Varbase Project BDD suites (11.0.x, 10.1.x, 9.2.x) so every
+// Varbase site gets them from @vardot/varbase-e2e instead of copying them into
+// each project's own tests/step-definitions/.
+// -----------------------------------------------------------------------------
+
+const { Given, When, Then } = require('@cucumber/cucumber');
+const assert = require('assert');
+const { smartSettle, friendly } = require('./varbase-e2e');
+const { budget, defaultThemeSettingsPath } = require('./drupal-helpers');
+
+/**
+ * Authenticate a Varbase user defined in cucumber.js worldParameters.users.
+ *
+ * Example #1: Given I am a logged in user with the "webmaster" user
+ * Example #2: Given I am a logged in user with the "Content admin" user
+ * Example #3: Given I am a logged in user with the username "editor"
+ * Example #4: Given I am a logged in user with "admin"
+ * Example #5: And I am a logged in user with the "webmaster" user
+ */
+Given(/^I am a logged in user with( the)*( username)* "([^"]*)?"( user)*$/, async function (theCase, usernameCase, username, userCase) {
+  const users = this.parameters.users;
+
+  if (!(username in users)) {
+    throw friendly(
+      `User "${username}" is not configured.`,
+      `Add it to worldParameters.users in cucumber.js. Known users: ${Object.keys(users).join(', ')}.`
+    );
+  }
+
+  const loginName = users[username].username || username;
+  const password = users[username].password;
+  if (password == null) return;
+
+  await this.page.goto(this.launchUrl + '/user/login', { waitUntil: 'domcontentloaded' });
+  // Wait for the username field to be actionable, fill, then submit by
+  // triggering the button's native click in-page. The Varbase login form is
+  // a standard POST; an in-page submit cannot be intercepted by the floating
+  // AI chatbot widget (a Playwright click would hit a 30s actionability
+  // timeout when the widget overlaps the button).
+  await this.page.waitForSelector('#edit-name', { state: 'visible', timeout: 15000 });
+  await this.page.fill('#edit-name', loginName);
+  await this.page.fill('#edit-pass', password);
+  await Promise.all([
+    this.page.waitForNavigation({ waitUntil: 'domcontentloaded' }).catch(() => {}),
+    this.page.evaluate(() => {
+      const submit = document.querySelector('#edit-submit');
+      if (submit) { submit.click(); return; }
+      const form = document.querySelector('#user-login-form') || document.forms[0];
+      if (form) form.submit();
+    }),
+  ]);
+  // Smart-settle the post-login page so the next step sees a stable page.
+  await smartSettle(this.page, (this.minWaitTime && this.minWaitTime.page) || 8000);
+});
+
+/**
+ * Fill an international telephone field (Webform `tel` element with
+ * `#international`, rendered by the intl-tel-input library). Setting the raw
+ * value with a plain "fill in" step is not enough: intl-tel-input validates
+ * the number with libphonenumber and rejects anything it cannot parse, so the
+ * webform's clientside/serverside validation fails. This step drives the
+ * intl-tel-input instance itself (`setNumber`) and dispatches input/blur so
+ * both the widget and the webform see a valid, formatted number.
+ *
+ * Pass the number in E.164 form (e.g. "+14155552671") for deterministic
+ * results regardless of the field's selected country.
+ *
+ * Example #1: When I fill in the international phone field with "+14155552671"
+ * Example #2: And I fill in the international phone number with "+442071838750"
+ * Example #3: When we fill in the international phone field with "+14155552671"
+ * Example #4: And I fill in the international phone field "Phone" with "+14155552671"
+ * Example #5: Given I fill in the international phone number with "+12025550143"
+ */
+When(/^(?:I |we )*fill in the international phone (?:field|number)(?: "[^"]*")? with "([^"]*)"$/, async function (number) {
+  const valid = await this.page.evaluate((num) => {
+    const g = window.intlTelInputGlobals;
+    if (!g || !g.instances) return null;
+    const keys = Object.keys(g.instances);
+    if (!keys.length) return null;
+    const inst = g.instances[keys[0]];
+    inst.setNumber(num);
+    const input = inst.telInput || document.querySelector('input[type="tel"]');
+    if (input) {
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+      input.dispatchEvent(new Event('change', { bubbles: true }));
+      input.dispatchEvent(new Event('blur', { bubbles: true }));
+    }
+    return inst.isValidNumber();
+  }, number);
+
+  if (valid === null) {
+    throw friendly(
+      'No intl-tel-input phone field was found on the page.',
+      'This step only works on a Webform "tel" element with #international enabled.'
+    );
+  }
+  if (!valid) {
+    throw friendly(
+      `"${number}" is not a valid phone number for this field.`,
+      'Pass a libphonenumber-valid number in E.164 form, e.g. "+14155552671".'
+    );
+  }
+});
+
+/**
+ * Go to the default theme's settings page, resolved by machine name (not
+ * hard-coded), so the test works whatever the default theme is.
+ *
+ * Example #1: When I go to the default theme settings page
+ * Example #2: And I go to the default theme settings
+ * Example #3: When we go to the default theme settings page
+ * Example #4: And we go to the default theme settings
+ * Example #5: Given I go to the default theme settings page
+ */
+When(/^(?:I |we )*go to the default theme settings(?: page)?$/, async function () {
+  const path = await defaultThemeSettingsPath(this.page, this.launchUrl);
+  if (!path) throw friendly('Could not find the default theme settings link.', 'Open /admin/appearance as a user who can administer themes.');
+  await this.page.goto(`${this.launchUrl.replace(/\/$/, '')}${path}`, { waitUntil: 'domcontentloaded' });
+  await smartSettle(this.page, (this.minWaitTime && this.minWaitTime.page) || 8000);
+});
+
+/**
+ * Enable or disable the default theme's "Sticky header" setting and save.
+ * The Gin-styled checkbox is visually hidden, so it is toggled in-page. Opens
+ * the default theme's settings form, sets the checkbox, and submits.
+ *
+ * Run a login step first (e.g. the webmaster).
+ *
+ * Example #1: When I enable the sticky header theme setting
+ * Example #2: And I disable the sticky header theme setting
+ * Example #3: When we enable the sticky header theme setting
+ * Example #4: And we disable the sticky header theme setting
+ * Example #5: Given I enable the sticky header theme setting
+ */
+When(/^(?:I |we )*(enable|disable) the sticky header theme setting$/, async function (action) {
+  const want = action === 'enable';
+  const settingsPath = await defaultThemeSettingsPath(this.page, this.launchUrl);
+  if (!settingsPath) throw friendly('Could not find the default theme settings link.', 'Open /admin/appearance as a user who can administer themes.');
+  await this.page.goto(`${this.launchUrl.replace(/\/$/, '')}${settingsPath}`, { waitUntil: 'domcontentloaded' });
+  const ok = await this.page.evaluate((on) => {
+    const cb = document.querySelector('input[name="sticky_header"]');
+    if (!cb) return false;
+    if (cb.checked !== on) cb.click();
+    const submit = document.getElementById('edit-submit') || [...document.querySelectorAll('input[type="submit"]')].find((b) => /save configuration/i.test(b.value));
+    if (!submit) return false;
+    submit.click();
+    return true;
+  }, want);
+  if (!ok) throw friendly('Could not toggle the "Sticky header" theme setting.', 'Open the default theme settings as a user who can administer the theme.');
+  await smartSettle(this.page, (this.minWaitTime && this.minWaitTime.page) || 8000);
+});
+
+/**
+ * Warm up a page across every viewport breakpoint in the testing settings.
+ *
+ * The default theme renders responsive images via drimage_improved, which builds
+ * a different WebP derivative per rendered width. This visits the page once at
+ * each breakpoint from worldParameters.selectors.breakpoints (scrolling to the
+ * bottom to trigger lazy images) so every derivative is generated and cached to
+ * disk before the health checks assert on console errors. It makes no
+ * assertions; it only primes the cache.
+ *
+ * Example #1: When I warm up "/" at all testing breakpoints
+ * Example #2: And I warm up "/features" at all testing breakpoints
+ * Example #3: When we warm up "/blog" at all testing breakpoints
+ * Example #4: And I warm up "/contact-us" at all testing breakpoints
+ * Example #5: Given I warm up "/about-varbase" at all testing breakpoints
+ */
+When(/^(?:I |we )*warm up "([^"]*)" at all testing breakpoints$/, async function (path) {
+  const base = this.launchUrl.replace(/\/$/, '');
+  const url = path.startsWith('http') ? path : base + (path.startsWith('/') ? path : '/' + path);
+  const configured = (this.parameters.selectors && this.parameters.selectors.breakpoints) || {};
+  const breakpoints = Object.values(configured);
+  if (!breakpoints.length) {
+    breakpoints.push({ width: 1920, height: 1080 });
+  }
+  const budget = (this.minWaitTime && this.minWaitTime.page) || 8000;
+  for (const breakpoint of breakpoints) {
+    await this.page.setViewportSize({ width: breakpoint.width, height: breakpoint.height });
+    await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+    await smartSettle(this.page, budget);
+    await this.page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+    await smartSettle(this.page, budget);
+  }
+});
+
+/**
+ * Click the "Next" button in the Varbase / Drupal Shepherd tour.
+ *
+ * Ports VarbaseContext::iClickNextInTour. The tour button lives in a
+ * shadow/overlay dialog; click it via an in-page native click after scrolling
+ * it into view.
+ *
+ * Example #1: When I click next button in tour
+ * Example #2: And I click next button in tour
+ * Example #3: When we click next button in tour
+ * Example #4: Given I click next button in tour
+ * Example #5: And we click next button in tour
+ */
+When(/^(?:I |we )*click next button in tour$/, async function () {
+  const ok = await this.page.evaluate(() => {
+    // Advance via the Shepherd API. The Drupal/Varbase tour renders each tip
+    // through Shepherd.js; its "Next" button's click handler does not reliably
+    // fire under a synthetic element.click() (the internal step pointer moves
+    // but the new tip does not render, or nothing happens at all), so drive the
+    // active tour directly — which shows the next step's tip exactly as the
+    // button is meant to. Fall back to clicking the button if the API is not
+    // exposed.
+    if (window.Shepherd && Shepherd.activeTour && typeof Shepherd.activeTour.next === 'function') {
+      Shepherd.activeTour.next();
+      return true;
+    }
+    const byText = [...document.querySelectorAll('button')].find((b) => b.textContent.trim() === 'Next');
+    const btn = byText || document.querySelector('.shepherd-button:not(.shepherd-button-secondary)');
+    if (!btn) return false;
+    btn.scrollIntoView({ block: 'center' });
+    btn.click();
+    return true;
+  });
+  if (!ok) throw friendly('The "Next" button in the tour was not found.');
+  await smartSettle(this.page, budget(this));
+});
+
+/**
+ * Close the Varbase / Drupal Shepherd tour.
+ *
+ * Ports VarbaseContext::iCloseTour: tries the cancel/close control, then falls
+ * back to dispatching Escape.
+ *
+ * Example #1: When I close the tour
+ * Example #2: And I close the tour
+ * Example #3: When we close the tour
+ * Example #4: Given I close the tour
+ * Example #5: And we close the tour
+ */
+When(/^(?:I |we )*close the tour$/, async function () {
+  await this.page.evaluate(() => {
+    const btn = document.querySelector('.shepherd-cancel-icon, button[aria-label="Close"], .shepherd-button:last-child');
+    if (btn) { btn.scrollIntoView({ block: 'center' }); btn.click(); return; }
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+  });
+  await smartSettle(this.page, budget(this));
+});
+
+/**
+ * Assert the Editoria11y accessibility checker panel is (or is not) present.
+ *
+ * Ports VarbaseContext::iShouldSeeTheAccessibilityChecker /
+ * iShouldNotSeeTheAccessibilityChecker. The checker mounts an
+ * <ed11y-element-panel> custom element.
+ *
+ * Example #1: Then I should see the accessibility checker
+ * Example #2: And I should see the a11y checker
+ * Example #3: Then should see a11y checker
+ * Example #4: And I should not see the accessibility checker
+ * Example #5: Then should not see a11y checker
+ */
+Then(/^(?:I |we )*should( not)? see (?:the )?(?:accessibility |a11y )?checker$/, async function (negate) {
+  const loc = this.page.locator('ed11y-element-panel');
+  const count = await loc.count().catch(() => 0);
+  if (negate) {
+    assert.strictEqual(count, 0, friendly('The accessibility checker panel was unexpectedly present.'));
+  } else {
+    assert.ok(count > 0, friendly('The accessibility checker panel was not found on the page.'));
+  }
+});
+
+/**
+ * Close the Editoria11y accessibility checker to clear space for more actions.
+ *
+ * Ports VarbaseContext::iCloseTheAccessibilityChecker: toggles the panel via
+ * its shadow-root toggle button.
+ *
+ * Example #1: When I close the accessibility checker
+ * Example #2: And I close the a11y checker
+ * Example #3: When we close the accessibility checker
+ * Example #4: Given I close the a11y checker
+ * Example #5: And we close the accessibility checker
+ */
+When(/^(?:I |we )*close (?:the )?(?:accessibility |a11y )?checker$/, async function () {
+  const ok = await this.page.evaluate(() => {
+    const panel = document.querySelector('ed11y-element-panel');
+    if (!panel || !panel.shadowRoot) return false;
+    const toggle = panel.shadowRoot.querySelector('#ed11y-toggle');
+    if (!toggle) return false;
+    toggle.click();
+    return true;
+  });
+  if (!ok) throw friendly('The accessibility checker toggle was not found.');
+  await smartSettle(this.page, budget(this));
+});
+
+/**
+ * Verify the page header is "working".
+ *
+ * On a Varbase site the Main navigation menu is rendered through the Drupal
+ * Canvas global Header region, so a working header means those primary links
+ * are present. Alter the links below to match your own site's main menu.
+ *
+ * Example: Then the page should have a working header
+ *
+ * Example #1: Then the page should have a working header
+ * Example #2: And I should have a working header
+ * Example #3: Then I should have a working header
+ * Example #4: And we should have a working header
+ * Example #5: Then the page should have a working header
+ */
+Then(/^(?:the page should have|(?:I |we )*should have) a working header$/, async function () {
+  // Smart-wait for the page to reach a quiet edge before reading the header.
+  await smartSettle(this.page, (this.minWaitTime && this.minWaitTime.page) || 8000);
+
+  // `banner` is the ARIA role of the site header (<header role="banner">).
+  const header = this.page.getByRole('banner').first();
+  const text = (await header.textContent().catch(() => '')) || '';
+
+  // Main navigation menu links expected in the header (one per line):
+  if (!text.includes('About Varbase')) throw friendly('Header is missing the "About Varbase" link.', 'Check the Main navigation menu in the Canvas Header region.');
+  if (!text.includes('Features')) throw friendly('Header is missing the "Features" link.', 'Check the Main navigation menu in the Canvas Header region.');
+  if (!text.includes('Blog')) throw friendly('Header is missing the "Blog" link.', 'Check the Main navigation menu in the Canvas Header region.');
+  if (!text.includes('Contact Us')) throw friendly('Header is missing the "Contact Us" link.', 'Check the Main navigation menu in the Canvas Header region.');
+});
+
+/**
+ * Verify the page footer is "working".
+ *
+ * On a Varbase site the Secondary, Footer and Social media menus are rendered
+ * through the Drupal Canvas global Footer region. A working footer means the
+ * footer link text is present, the social profiles are linked, and the credits
+ * and logos show. Alter the lines below to match your own site.
+ *
+ * Example: Then the page should have a working footer
+ *
+ * Example #1: Then the page should have a working footer
+ * Example #2: And I should have a working footer
+ * Example #3: Then I should have a working footer
+ * Example #4: And we should have a working footer
+ * Example #5: Then the page should have a working footer
+ */
+Then(/^(?:the page should have|(?:I |we )*should have) a working footer$/, async function () {
+  // Smart-wait for the page to reach a quiet edge before reading the footer.
+  await smartSettle(this.page, (this.minWaitTime && this.minWaitTime.page) || 8000);
+
+  // `contentinfo` is the ARIA role of the site footer (<footer role="contentinfo">).
+  // Scope to the role so card/section <footer> elements elsewhere are ignored.
+  const footer = this.page.getByRole('contentinfo').first();
+  const text = (await footer.textContent().catch(() => '')) || '';
+
+  // Secondary menu (Footer sitemap / Quicklinks) link text (one per line):
+  if (!text.includes('Quicklinks')) throw friendly('Footer is missing the "Quicklinks" heading.', 'Check the Secondary menu in the Canvas Footer region.');
+  if (!text.includes('Features')) throw friendly('Footer is missing the "Features" link.', 'Check the Secondary menu in the Canvas Footer region.');
+  if (!text.includes('About Varbase')) throw friendly('Footer is missing the "About Varbase" link.', 'Check the Secondary menu in the Canvas Footer region.');
+
+  // Footer menu (Support) link text (one per line):
+  if (!text.includes('Support')) throw friendly('Footer is missing the "Support" heading.', 'Check the Footer menu in the Canvas Footer region.');
+  if (!text.includes('Documentation')) throw friendly('Footer is missing the "Documentation" link.', 'Check the Footer menu in the Canvas Footer region.');
+  if (!text.includes('Get Professional Support')) throw friendly('Footer is missing the "Get Professional Support" link.', 'Check the Footer menu in the Canvas Footer region.');
+  if (!text.includes('Community Support')) throw friendly('Footer is missing the "Community Support" link.', 'Check the Footer menu in the Canvas Footer region.');
+
+  // Footer credit and legal text (one per line):
+  if (!text.includes('Enjoy the free software, or')) throw friendly('Footer is missing the "Enjoy the free software, or get a quote ..." credit.');
+  if (!text.includes('get a quote')) throw friendly('Footer is missing the "get a quote" link text.');
+  if (!text.includes('Terms and Conditions')) throw friendly('Footer is missing the "Terms and Conditions" link.');
+  if (!text.includes('Powered by')) throw friendly('Footer is missing the "Powered by" credit.');
+
+  // Social media menu profiles - full links (one per line):
+  if ((await footer.locator('a[href="https://www.linkedin.com/company/vardot"]').count()) === 0) throw friendly('Footer is missing the LinkedIn link (https://www.linkedin.com/company/vardot).', 'Check the Social media menu in the Canvas Footer region.');
+  if ((await footer.locator('a[href="https://www.facebook.com/vardotters/"]').count()) === 0) throw friendly('Footer is missing the Facebook link (https://www.facebook.com/vardotters/).', 'Check the Social media menu in the Canvas Footer region.');
+  if ((await footer.locator('a[href="https://www.instagram.com/vardotters/"]').count()) === 0) throw friendly('Footer is missing the Instagram link (https://www.instagram.com/vardotters/).', 'Check the Social media menu in the Canvas Footer region.');
+  if ((await footer.locator('a[href="https://x.com/Vardot"]').count()) === 0) throw friendly('Footer is missing the X link (https://x.com/Vardot).', 'Check the Social media menu in the Canvas Footer region.');
+
+  // Footer logos (one per line):
+  if ((await footer.locator('img[alt="Varbase logo"]').count()) === 0) throw friendly('Footer is missing the Varbase logo.');
+  if ((await footer.locator('img[alt="Vardot"]').count()) === 0) throw friendly('Footer is missing the Vardot logo next to "Powered by".');
+});
+
+/**
+ * Press a responsive-preview device button (Drupal core Responsive preview).
+ *
+ * Ports VarbaseContext::iPressResponsivePreviewDeviceButton: clicks the control
+ * carrying data-responsive-preview-name.
+ *
+ * Example #1: When I press the "desktop" responsive preview device button
+ * Example #2: And I press the "mobile" responsive preview device button
+ * Example #3: When we press the "tablet" responsive preview device button
+ * Example #4: And I press the "widescreen" responsive preview device button
+ * Example #5: When I press the "mobile" responsive preview device button
+ */
+When(/^(?:I |we )*press the "([^"]*)" responsive preview device button$/, async function (deviceName) {
+  const ok = await this.page.evaluate((deviceName) => {
+    const btn = document.querySelector(`[data-responsive-preview-name="${deviceName}"]`);
+    if (!btn) return false;
+    btn.click();
+    return true;
+  }, deviceName);
+  if (!ok) throw friendly(`The "${deviceName}" responsive preview device option was not found.`);
+  await smartSettle(this.page, budget(this));
+});
+
+/**
+ * Assert an element renders as a sticky element (CSS position: sticky).
+ *
+ * Resolves a named selector from the registry (falling back to a raw CSS
+ * selector) and checks its computed position. Reads better in a feature than
+ * asserting on a raw "position:sticky;" CSS property string.
+ *
+ * Example #1: Then the "site header" should be sticky
+ * Example #2: And the "site header" should be sticky
+ * Example #3: Then the "site header" should not be sticky
+ * Example #4: And the "footer" should not be sticky
+ * Example #5: Then the "main content" should be sticky
+ */
+Then(/^the "([^"]*)" should( not)? be sticky$/, async function (name, negate) {
+  const selector = (this.__selectorsCss && this.__selectorsCss[name]) || name;
+  const position = await this.page.locator(selector).first().evaluate((el) => window.getComputedStyle(el).position);
+  if (negate) {
+    assert.notStrictEqual(position, 'sticky', friendly(`Expected "${name}" not to be sticky, but its computed position is "${position}".`));
+  } else {
+    assert.strictEqual(position, 'sticky', friendly(`Expected "${name}" to be sticky, but its computed position is "${position}".`));
+  }
+});
+
+/**
+ * Assert a named element gains (or loses) a CSS class, with auto-retry.
+ *
+ * Resolves a named selector from the registry (falling back to a raw CSS
+ * selector) and polls its class list. Use this instead of the raw-selector
+ * web-first step when the feature should read with a registered name.
+ *
+ * Example #1: Then the "site header" should have the "scrolled" class within 5 seconds
+ * Example #2: And the "site header" should have the "scrolled" class
+ * Example #3: Then the "site header" should not have the "scrolled" class
+ * Example #4: And the "main content" should have the "is-active" class within 3 seconds
+ * Example #5: Then the "footer" should not have the "scrolled" class
+ */
+Then(/^the "([^"]*)" should( not)? have the "([^"]*)" class(?: within (\d+) seconds?)?$/, async function (name, negate, cls, sec) {
+  const selector = (this.__selectorsCss && this.__selectorsCss[name]) || name;
+  const loc = this.page.locator(selector).first();
+  const timeout = (sec ? parseInt(sec, 10) : 5) * 1000;
+  const want = !negate;
+  const start = Date.now();
+  let classes = '';
+  do {
+    classes = (await loc.getAttribute('class')) || '';
+    if (classes.split(/\s+/).includes(cls) === want) {
+      return;
+    }
+    await this.page.waitForTimeout(100);
+  } while (Date.now() - start < timeout);
+  throw friendly(`Expected "${name}" ${want ? 'to have' : 'not to have'} the "${cls}" class within ${timeout / 1000}s; last class was "${classes}".`);
+});

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

@@ -0,0 +1,178 @@
+'use strict';
+
+const { friendly } = require('./varbase-e2e');
+
+// Video recording steps — start / stop / save mid-scenario.
+//
+// Playwright records video only at browser-context creation. Mid-scenario
+// `start` / `stop` therefore work by tearing down the current page +
+// context and reopening with the new recording flag. Page state is lost
+// across the boundary — call `start` BEFORE any navigation and `stop` only
+// when you no longer need the current page state.
+//
+// Default mode is 'off' (no recording). See cucumber.js → worldParameters.video.
+
+const { When, Then } = require('@cucumber/cucumber');
+const fs = require('fs');
+const path = require('path');
+
+function settings(world) {
+  const cfg = (world.parameters && world.parameters.video) || {};
+  return {
+    dir: process.env.VARBASE_E2E_VIDEO_DIR || cfg.dir || './videos',
+    size: cfg.size || { width: 1280, height: 720 },
+  };
+}
+
+async function rebuildContext(world, recordVideo) {
+  await world.closeBrowser();
+  if (recordVideo) {
+    const s = settings(world);
+    fs.mkdirSync(s.dir, { recursive: true });
+    world._videoRequested = true;
+    await world.openBrowser({ recordVideo: { dir: s.dir, size: s.size } });
+  } else {
+    world._videoRequested = false;
+    await world.openBrowser();
+  }
+}
+
+/**
+ * Start recording the browser as a webm video. Closes the current page +
+ * context and reopens with `recordVideo` enabled. Place BEFORE any
+ * navigation in the scenario.
+ *
+ * Example #1: When I start video recording
+ * Example #2: And I start video recording
+ * Example #3: Given I start video recording
+ * Example #4: But I start video recording
+ * Example #5: Then I start video recording
+ *
+ */
+When(/^(I |we )*start video recording$/, async function (pronoun) {
+  try {
+    await rebuildContext(this, true);
+  } catch (e) {
+    throw friendly({
+      action: 'start video recording',
+      cause: e,
+      hint: `the videos directory (${(this.parameters && this.parameters.video && this.parameters.video.dir) || './videos'}) must be writable.`,
+    });
+  }
+});
+
+/**
+ * Stop recording. Closes the current page + context (which flushes the
+ * webm to disk) and reopens a fresh, non-recording browser so the rest
+ * of the scenario can continue.
+ *
+ * Example #1: When I stop video recording
+ * Example #2: And I stop video recording
+ * Example #3: But I stop video recording
+ * Example #4: Then I stop video recording
+ * Example #5: Then I stop video recording
+ *
+ */
+When(/^(I |we )*stop video recording$/, async function (pronoun) {
+  try {
+    if (!this.page || !this._videoRequested) return;
+    const video = this.page.video();
+    // Close context first — flushes the webm — then saveAs while the
+    // browser is still alive, finally close the browser and reopen fresh.
+    try { await this.context.close(); } catch { /* ignore */ }
+    if (video) {
+      try {
+        const s = settings(this);
+        const name = this._videoSaveAsName || `manual.${Date.now()}.webm`;
+        const dest = path.join(s.dir, name);
+        await video.saveAs(dest);
+        await video.delete().catch(() => {});
+        process.stderr.write(`\n[varbase-e2e] video saved → ${dest}\n`);
+        // Reset so the After hook does not try to re-save.
+        this._videoSaveAsName = null;
+      } catch (e) {
+        process.stderr.write(`\n[varbase-e2e] video save failed: ${e.message}\n`);
+      }
+    }
+    if (this.playwrightBrowser) {
+      try { await this.playwrightBrowser.close(); } catch { /* ignore */ }
+      this.playwrightBrowser = null;
+    }
+    this.context = null;
+    this.page = null;
+    this._videoRequested = false;
+    await this.openBrowser();
+  } catch (e) {
+    throw friendly({
+      action: 'stop video recording',
+      cause: e,
+      hint: 'the scenario will continue with a fresh, non-recording browser.',
+    });
+  }
+});
+
+/**
+ * Reserve a custom filename for the current scenario's video. The actual
+ * save happens at scenario end (Playwright's `video.saveAs()` blocks
+ * until recording finishes, so we cannot copy bytes mid-flight). If the
+ * scenario calls `stop video recording` before scenario end, the manual
+ * webm uses this name instead of the automatic timestamped one.
+ *
+ * Example #1: When I save the current video as "checkout-flow.webm"
+ * Example #2: When I save the current video as "regression-21.webm"
+ * Example #3: And I save the current video as "smoke.webm"
+ * Example #4: Then I save the current video as "demo.webm"
+ * Example #5: But I save the current video as "rerun.webm"
+ *
+ */
+When(/^(I |we )*save the current video as "([^"]*)"$/, function (pronoun, name) {
+  try {
+    if (!this._videoRequested) {
+      throw new Error('recording is not active');
+    }
+    if (!name || !name.trim()) {
+      throw new Error('filename is empty');
+    }
+    this._videoSaveAsName = name;
+  } catch (e) {
+    throw friendly({
+      action: `save the current video as "${name}"`,
+      cause: e,
+      hint: 'call "When I start video recording" first, or set worldParameters.video.mode to "on".',
+    });
+  }
+});
+
+/**
+ * Print the path that the current video will be written to. Diagnostic
+ * only — never asserts, never fails.
+ *
+ * Example #1: Then print video path
+ * Example #2: And print video path
+ * Example #3: But print video path
+ * Example #4: Then print video path
+ * Example #5: Then print video path
+ *
+ */
+Then(/^print video path$/, async function () {
+  // Diagnostic only — swallow every error and report inline.
+  try {
+    if (!this.page || !this._videoRequested) {
+      console.log('\n--- Video path: recording is OFF ---');
+      return;
+    }
+    const video = this.page.video();
+    if (!video) {
+      console.log('\n--- Video path: no video object on this page ---');
+      return;
+    }
+    try {
+      const p = await video.path();
+      console.log(`\n--- Video path: ${p} ---`);
+    } catch (e) {
+      console.log(`\n--- Video path unavailable: ${e.message} ---`);
+    }
+  } catch (e) {
+    console.log(`\n--- Video path error: ${e.message} ---`);
+  }
+});