@specwright/plugin 0.1.0

package/README-TESTING.md

@@ -0,0 +1,227 @@
+# E2E Testing Framework
+
+## Overview
+
+**playwright-bdd** (v8+) BDD-style end-to-end testing with AI-powered test generation and self-healing.
+
+- Gherkin `.feature` files compiled to Playwright specs via `bddgen`
+- Path-based tag scoping for module isolation
+- Default parallel execution, `@serial-execution` opt-out with browser reuse
+- 3-layer test data persistence (`page.testData` → `featureDataCache` → scoped JSON)
+- `processDataTable` / `validateExpectations` utilities for declarative form handling
+- 8 AI agents + 7 Claude Code skills for automated test generation and healing
+
+## Quick Start
+
+```bash
+# 1. Install dependencies + Playwright browsers
+pnpm install && pnpx playwright install
+
+# 2. Set credentials in .env
+TEST_USER_EMAIL=your-email@example.com
+TEST_USER_PASSWORD=your-password
+
+# 3. Start dev server
+pnpm dev
+
+# 4. Run authentication tests (out-of-the-box)
+pnpm test:bdd:auth
+
+# 5. View report
+pnpm report:playwright
+```
+
+**Never run `npx playwright test` directly** — it skips `bddgen` and uses stale specs.
+
+## Project Configuration
+
+| Project            | Purpose               | Behavior                                                 |
+| ------------------ | --------------------- | -------------------------------------------------------- |
+| `setup`            | Auth session creation | Runs first, creates auth session                         |
+| `auth-tests`       | Login/logout tests    | Clean browser state, no storageState                     |
+| `serial-execution` | Stateful features     | `@serial-execution` tag, workers: 1, browser reused      |
+| `main-e2e`         | Everything else       | `fullyParallel: true` (default), storageState from setup |
+
+## Directory Structure
+
+```
+e2e-tests/
+├── features/playwright-bdd/
+│   ├── @Modules/                   ← Single-module tests
+│   │   └── @Authentication/        ← Out-of-the-box auth tests (7 scenarios)
+│   ├── @Workflows/                 ← Cross-module workflow tests
+│   │   └── @YourWorkflow/          ← Precondition → consumers pattern
+│   │       ├── @0-Precondition/    ← Serial, creates shared data
+│   │       ├── @1-Consumer/        ← Loads predata, runs in parallel
+│   │       └── @2-Consumer/
+│   └── shared/                     ← Globally scoped steps (no @ prefix)
+│       ├── auth.steps.js
+│       ├── navigation.steps.js
+│       ├── common.steps.js
+│       └── global-hooks.js         ← Auto-loaded, NEVER import manually
+├── playwright/
+│   ├── fixtures.js                 ← Custom fixtures + browser reuse (import from HERE)
+│   ├── auth.setup.js               ← Two-step localStorage login
+│   ├── auth-storage/.auth/         ← Saved auth state (gitignored)
+│   ├── generated/                  ← Seed files from exploration
+│   └── test-data/                  ← Scoped JSON files (auto-created)
+├── utils/
+│   ├── stepHelpers.js              ← processDataTable, validateExpectations, FIELD_TYPES
+│   └── testDataGenerator.js        ← Faker-based value generation
+├── data/
+│   ├── authenticationData.js       ← Credentials from env vars (never hardcoded)
+│   └── testConfig.js               ← Routes, timeouts, baseUrl
+├── instructions.js                 ← Agent pipeline config (add your entries)
+├── instructions.example.js         ← Example configs (text, Jira, CSV, workflow)
+└── .env.testing                    ← Environment variable template
+```
+
+## Running Tests
+
+```bash
+## Predefined scripts
+pnpm test:bdd               # All tests except auth
+pnpm test:bdd:all            # Everything including auth
+pnpm test:bdd:auth           # Authentication tests only
+pnpm test:bdd:serial         # Serial execution tests only
+pnpm test:bdd:debug          # Debug mode (PWDEBUG)
+
+## Run by tag
+pnpm bddgen && npx playwright test --project setup --project main-e2e --grep @your-tag
+pnpm bddgen && npx playwright test --project setup --project serial-execution --grep @your-serial-tag
+
+## Run by file
+pnpm bddgen && npx playwright test --project setup --project main-e2e \
+  ".features-gen/e2e-tests/features/playwright-bdd/@Modules/@YourModule/feature.spec.js"
+
+## Run headed
+pnpm bddgen && npx playwright test --project setup --project main-e2e --grep @tag --headed
+
+## Run single scenario by title
+pnpm bddgen && npx playwright test --project setup --project main-e2e -g "Scenario title"
+
+## Reports
+pnpm report:playwright       # View HTML report
+pnpm test:clean              # Clean reports + .features-gen + test-data
+```
+
+**Tip:** Use `--project serial-execution` for `@serial-execution` features, `--project auth-tests` for `@Authentication`, `--project main-e2e` for everything else.
+
+## Writing Tests
+
+### Feature Files
+
+```gherkin
+@module-name
+Feature: Module Description
+  Background:
+    Given I am logged in
+    When I navigate to "PageName"
+
+  Scenario: Happy path
+    When I fill the form with:
+      | Field Name | Value           | Type            |
+      | Name       | <gen_test_data> | SharedGenerated |
+      | Email      | <gen_test_data> | SharedGenerated |
+    And I click the submit button
+    Then I should see the success message
+```
+
+### Step Definitions (with processDataTable)
+
+```javascript
+import { When, Then, expect } from '../../../../playwright/fixtures.js';
+import { FIELD_TYPES, processDataTable, validateExpectations } from '../../../../utils/stepHelpers.js';
+
+const FIELD_CONFIG = {
+  Name: { type: FIELD_TYPES.FILL, testID: 'user-name' },
+  Email: { type: FIELD_TYPES.FILL, testID: 'user-email' },
+};
+
+const VALIDATION_CONFIG = {
+  Name: { type: FIELD_TYPES.TEXT_VISIBLE, testID: 'display-name' },
+  Email: { type: FIELD_TYPES.TEXT_VISIBLE, testID: 'display-email' },
+};
+
+const fieldMapping = { Name: 'name', Email: 'email' };
+
+When('I fill the form with:', async ({ page }, dataTable) => {
+  await processDataTable(page, dataTable, { mapping: fieldMapping, fieldConfig: FIELD_CONFIG });
+});
+
+Then('I should see the details:', async ({ page }, dataTable) => {
+  await validateExpectations(page, dataTable, { mapping: fieldMapping, validationConfig: VALIDATION_CONFIG });
+});
+```
+
+### Data Table Placeholders
+
+| Placeholder        | Used in         | Meaning                        |
+| ------------------ | --------------- | ------------------------------ |
+| `<gen_test_data>`  | Form fill steps | Generate faker value, cache it |
+| `<from_test_data>` | Assertion steps | Read cached value              |
+| Static value       | Both            | Use as-is                      |
+
+### When to Use `@serial-execution`
+
+Add when:
+
+- `<gen_test_data>` in Scenario A and `<from_test_data>` in Scenario B
+- Scenarios rely on UI state from previous scenarios
+- Workflow precondition/consumer pattern
+
+No tag needed (parallel by default) when:
+
+- Each scenario is self-contained
+- Scenarios only READ predata independently
+
+### Adding a New Module
+
+1. Create: `e2e-tests/features/playwright-bdd/@Modules/@YourModule/`
+2. Add: `your-feature.feature` + `steps.js`
+3. Import: `import { When, Then } from '../../../../playwright/fixtures.js'`
+4. For data tables: `import { FIELD_TYPES, processDataTable } from '../../../../utils/stepHelpers.js'`
+5. Run: `pnpm test:bdd`
+
+### Adding a Workflow
+
+1. Create: `e2e-tests/features/playwright-bdd/@Workflows/@YourWorkflow/`
+2. `@0-Precondition/` — serial, creates data (`@precondition @cross-feature-data @serial-execution`)
+3. `@1-Consumer/` — loads predata via `Given I load predata from "workflow-name"` (`@workflow-consumer`)
+
+## Agent Pipeline
+
+| Command                | What it does                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| `/e2e-automate`        | Full 10-phase pipeline: config → explore → plan → approve → generate → execute |
+| `/e2e-plan <page>`     | Explore a page, discover selectors, generate test plan                         |
+| `/e2e-generate <plan>` | Generate .feature + steps.js from a plan                                       |
+| `/e2e-heal`            | Run tests, diagnose failures, auto-heal                                        |
+| `/e2e-run`             | Quick test execution with optional filters                                     |
+| `/e2e-validate`        | Validate seed file tests before BDD generation                                 |
+| `/e2e-process <input>` | Process Jira/files into test plan markdown                                     |
+
+Configure in `e2e-tests/instructions.js` (see `instructions.example.js` for examples).
+
+## Troubleshooting
+
+| Problem                              | Fix                                                                        |
+| ------------------------------------ | -------------------------------------------------------------------------- |
+| "Step not found" after editing steps | `rm -rf .features-gen/ && pnpm test:bdd`                                   |
+| Auth failures                        | `rm -f e2e-tests/playwright/auth-storage/.auth/user.json && pnpm test:bdd` |
+| Cross-module steps not visible       | Move from `@Module/steps.js` to `shared/`                                  |
+| Duplicate hook errors                | Never import `global-hooks.js` manually                                    |
+| Browser launch failures              | `pnpx playwright install`                                                  |
+
+## Environment Variables
+
+| Variable                 | Default                 | Description               |
+| ------------------------ | ----------------------- | ------------------------- |
+| `BASE_URL`               | `http://localhost:5173` | Application URL           |
+| `TEST_USER_EMAIL`        | —                       | Login email (required)    |
+| `TEST_USER_PASSWORD`     | —                       | Login password (required) |
+| `HEADLESS`               | `true`                  | Headless browser mode     |
+| `TEST_TIMEOUT`           | `90000`                 | Test timeout (ms)         |
+| `ENABLE_SCREENSHOTS`     | `true`                  | Screenshot on failure     |
+| `ENABLE_VIDEO_RECORDING` | `false`                 | Video on failure          |
+| `ENABLE_TRACING`         | `false`                 | Playwright traces         |

package/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const command = process.argv[2];
+const targetDir = process.argv[3] || process.cwd();
+
+if (command === 'init') {
+  const installScript = path.join(__dirname, 'install.sh');
+
+  if (!fs.existsSync(installScript)) {
+    console.error('Error: install.sh not found in plugin package.');
+    process.exit(1);
+  }
+
+  console.log(`\n  Specwright E2E Plugin Installer\n`);
+  console.log(`  Target: ${targetDir}\n`);
+
+  try {
+    execSync(`bash "${installScript}" "${targetDir}"`, { stdio: 'inherit' });
+    console.log(`\n  Done! Next steps:\n`);
+    console.log(`  1. pnpm install`);
+    console.log(`  2. npx playwright install`);
+    console.log(`  3. cp e2e-tests/instructions.example.js e2e-tests/instructions.js`);
+    console.log(`  4. pnpm test:bdd:auth\n`);
+  } catch (err) {
+    console.error('Installation failed:', err.message);
+    process.exit(1);
+  }
+} else {
+  console.log(`
+  @specwright/plugin — AI-powered E2E test automation
+
+  Usage:
+    npx @specwright/plugin init [target-dir]
+
+  This installs the Playwright BDD framework, Claude Code agents,
+  and shared step definitions into your project.
+
+  Options:
+    init [dir]    Install plugin into target directory (default: current dir)
+
+  After install:
+    pnpm install                    Install dependencies
+    npx playwright install          Install browsers
+    pnpm test:bdd:auth              Verify setup
+    claude → /e2e-automate          Generate tests with AI
+
+  More info: https://github.com/SanthoshDhandapani/specwright
+  `);
+}

package/e2e-tests/.env.testing

@@ -0,0 +1,29 @@
+# Base Environment Configuration
+BASE_ENV=qat
+BASE_URL=http://localhost:5173
+NODE_ENV=test
+
+# Browser Configuration
+HEADLESS=true
+BROWSER=chromium
+CHROME_ARGS="--no-sandbox,--disable-dev-shm-usage"
+
+# Reports Configuration
+CUCUMBER_REPORT_PATH="reports/cucumber-bdd/report.json"
+CODEGEN_OUTPUT_PATH="e2e-tests/playwright/generated"
+
+# Test Configuration
+TEST_TIMEOUT=120000
+
+# Visual Testing Configuration
+ENABLE_SCREENSHOTS=true
+ENABLE_VIDEO_RECORDING=true
+RETAIN_VIDEO_ON_SUCCESS=false
+ENABLE_TRACING=false
+
+# Test Credentials (REQUIRED — set your own values)
+# TEST_USER_EMAIL=your-test-email@example.com
+# TEST_USER_PASSWORD=your-test-password
+
+# Build Environment
+VITE_BUILD_ENVIRONMENT=testing

package/e2e-tests/data/authenticationData.js

@@ -0,0 +1,76 @@
+/**
+ * Authentication test data — TEMPLATE
+ *
+ * Update the locators below to match YOUR app's login form.
+ * Credentials are read from environment variables ONLY.
+ * Set TEST_USER_EMAIL and TEST_USER_PASSWORD in your .env file.
+ */
+
+const getCredentials = () => {
+  const email = process.env.TEST_USER_EMAIL;
+  const password = process.env.TEST_USER_PASSWORD;
+
+  if (!email || !password) {
+    throw new Error('E2E credentials not configured. Set TEST_USER_EMAIL and TEST_USER_PASSWORD in your .env file.');
+  }
+
+  return { email, password };
+};
+
+export const authenticationData = {
+  baseUrl: process.env.BASE_URL || 'http://localhost:5173',
+
+  environment: process.env.BASE_ENV || '',
+
+  validCredentials: getCredentials(),
+
+  invalidCredentials: {
+    email: 'invalid@email.com',
+    password: 'invalid_password',
+  },
+
+  // ┌──────────────────────────────────────────────────────────────┐
+  // │  UPDATE THESE LOCATORS to match your app's login form        │
+  // │  The testId values should match data-testid attributes       │
+  // │  in your login page components.                              │
+  // └──────────────────────────────────────────────────────────────┘
+  locators: {
+    emailInput: {
+      testId: 'loginEmail', // Update: your email input data-testid
+      label: 'Email',
+    },
+    emailSubmitButton: {
+      testId: 'loginEmailSubmit', // Update: your email submit button data-testid
+      label: 'Continue',
+    },
+    passwordInput: {
+      testId: 'loginPassword', // Update: your password input data-testid
+      label: 'Password',
+    },
+    loginSubmitButton: {
+      testId: 'loginSubmit', // Update: your login submit button data-testid
+      label: 'Sign In',
+    },
+    errorMessage: {
+      selector: '[data-testid="loginError"]', // Update: your error message selector
+      errorText: 'invalid email or password',
+    },
+  },
+
+  timeouts: {
+    login: 60000,
+    loadState: 50000,
+    elementWait: 10000,
+  },
+
+  // Two-factor authentication (remove if your app doesn't use 2FA)
+  twoFactor: {
+    code: '99999999',
+    locators: {
+      codeInput: { testId: 'twoFactorCodeInput' },
+      proceedButton: { testId: 'twfProceed' },
+    },
+  },
+};
+
+export default authenticationData;

package/e2e-tests/data/testConfig.js

@@ -0,0 +1,39 @@
+/**
+ * Test configuration — TEMPLATE
+ *
+ * Update the routes below to match YOUR app's URL structure.
+ */
+import { authenticationData } from './authenticationData.js';
+
+export const testConfig = {
+  baseUrl: authenticationData.baseUrl,
+
+  credentials: {
+    ...authenticationData.validCredentials,
+  },
+
+  // ┌──────────────────────────────────────────────────────────────┐
+  // │  UPDATE THESE ROUTES to match your app's URL structure       │
+  // │  These are used by shared/navigation.steps.js for            │
+  // │  `Given I am on the "PageName" page` steps.                  │
+  // └──────────────────────────────────────────────────────────────┘
+  routes: {
+    Home: '/home',
+    SignIn: '/signin',
+    // Add your app's routes here:
+    // Dashboard: '/dashboard',
+    // Settings: '/settings',
+    // Users: '/users',
+  },
+
+  timeouts: {
+    standard: 30000,
+    long: 60000,
+    element: 10000,
+    loadState: 60000,
+    navigation: 50000,
+    networkIdle: 15000,
+  },
+};
+
+export default testConfig;

package/e2e-tests/features/playwright-bdd/@Modules/@Authentication/authentication.feature

@@ -0,0 +1,64 @@
+@authentication @serial-execution
+Feature: Authentication
+  As a user of the application
+  I want to be able to log in and log out
+  So that I can securely access the application
+
+  @login-form
+  Scenario: Verify login form displays email input
+    Given I am on the sign-in page
+    Then I should see the heading "Welcome to FourKites!"
+    And the element with test ID "loginEmail" should be visible
+    And the element with test ID "loginEmailSubmit" should be disabled
+
+  @login-success
+  Scenario: Successful login flow
+    Given I am on the sign-in page
+    When I enter valid email
+    And I click the email submit button
+    Then the element with test ID "loginPassword" should be visible
+    When I enter valid password
+    And I click the login submit button
+    And I handle 2FA if prompted
+    Then I should be redirected to "/home"
+
+  @login-invalid-email
+  Scenario: Login with invalid email format
+    Given I am on the sign-in page
+    When I enter email "invalid-email"
+    And I click the email submit button
+    Then I should see the text "Enter a valid email address."
+
+  @login-invalid-credentials
+  Scenario: Login with invalid credentials
+    Given I am on the sign-in page
+    When I enter email "nonexistent@example.com"
+    And I click the email submit button
+    Then the element with test ID "loginPassword" should be visible
+    When I enter password "WrongPassword123"
+    And I click the login submit button
+    Then I should see the text "Email does not exist on FourKites"
+
+  @login-empty-email
+  Scenario: Empty email validation
+    Given I am on the sign-in page
+    Then the element with test ID "loginEmailSubmit" should be disabled
+
+  @logout
+  Scenario: Logout flow
+    Given I am on the sign-in page
+    When I enter valid email
+    And I click the email submit button
+    And I enter valid password
+    And I click the login submit button
+    And I handle 2FA if prompted
+    Then I should be redirected to "/home"
+    When I click the user menu button
+    And I click the button "Logout"
+    Then I should be redirected to "/signin"
+
+  @unauthenticated-access
+  Scenario: Unauthenticated access protection
+    Given I clear browser storage
+    When I navigate to "/home"
+    Then I should be redirected to "/signin"

package/e2e-tests/features/playwright-bdd/@Modules/@Authentication/steps.js

@@ -0,0 +1,27 @@
+/**
+ * Authentication module-specific steps.
+ * Co-located with authentication.feature — scoped to @Modules AND @Authentication.
+ *
+ * Reusable steps (login, navigation, assertions) live in shared/.
+ * Only module-specific steps that are NOT reusable belong here.
+ */
+import { When, Then, expect } from '../../../../playwright/fixtures.js';
+
+When('I click the user menu button', async ({ page }) => {
+  const userMenuButton = page.getByTestId('user-menu-button');
+  await userMenuButton.waitFor({ state: 'visible', timeout: 10000 });
+  await userMenuButton.click();
+});
+
+Then('the password field should be visible', async ({ page }) => {
+  const passwordInput = page.getByTestId('loginPassword');
+  await expect(passwordInput).toBeVisible();
+});
+
+Then('the Go Back button should be visible', async ({ page }) => {
+  await expect(page.getByRole('button', { name: 'Go Back' })).toBeVisible();
+});
+
+Then('the Forgot Password button should be visible', async ({ page }) => {
+  await expect(page.getByRole('button', { name: 'Forgot Password?' })).toBeVisible();
+});

package/e2e-tests/features/playwright-bdd/shared/auth.steps.js

@@ -0,0 +1,74 @@
+/**
+ * Shared authentication steps — reusable across all modules.
+ * Lives in shared/ (no @-prefix) so it is globally scoped.
+ */
+import { Given, When, Then, expect } from '../../../playwright/fixtures.js';
+
+Given('I am logged in', async ({ page, authData }) => {
+  // When using storageState from auth.setup, the user is already authenticated.
+  // In serial-execution mode, skip navigation if the page is already on an
+  // authenticated route to preserve cross-scenario state (e.g., submitted forms).
+  const currentUrl = page.url();
+  if (currentUrl && currentUrl !== 'about:blank' && !currentUrl.includes('/signin')) {
+    // Already on an authenticated page — no need to navigate away
+    return;
+  }
+  await page.goto('/home');
+  await page.waitForLoadState('networkidle', { timeout: authData.timeouts.loadState });
+});
+
+Given('I am on the sign-in page', async ({ page, authData }) => {
+  await page.goto('/signin');
+  await page.waitForLoadState('networkidle', { timeout: authData.timeouts.loadState });
+});
+
+When('I enter email {string}', async ({ page, authData }, email) => {
+  const emailInput = page.getByTestId(authData.locators.emailInput.testId);
+  await emailInput.waitFor({ state: 'visible', timeout: authData.timeouts.elementWait });
+  await emailInput.fill(email);
+});
+
+When('I enter valid email', async ({ page, authData }) => {
+  const emailInput = page.getByTestId(authData.locators.emailInput.testId);
+  await emailInput.waitFor({ state: 'visible', timeout: authData.timeouts.elementWait });
+  await emailInput.fill(authData.validCredentials.email);
+});
+
+When('I click the email submit button', async ({ page, authData }) => {
+  const emailSubmit = page.getByTestId(authData.locators.emailSubmitButton.testId);
+  await emailSubmit.click();
+});
+
+When('I enter password {string}', async ({ page, authData }, password) => {
+  const passwordInput = page.getByTestId(authData.locators.passwordInput.testId);
+  await passwordInput.waitFor({ state: 'visible', timeout: authData.timeouts.elementWait });
+  await passwordInput.fill(password);
+});
+
+When('I enter valid password', async ({ page, authData }) => {
+  const passwordInput = page.getByTestId(authData.locators.passwordInput.testId);
+  await passwordInput.waitFor({ state: 'visible', timeout: authData.timeouts.elementWait });
+  await passwordInput.fill(authData.validCredentials.password);
+});
+
+When('I click the login submit button', async ({ page, authData }) => {
+  const loginSubmit = page.getByTestId(authData.locators.loginSubmitButton.testId);
+  await loginSubmit.click();
+});
+
+When('I handle 2FA if prompted', async ({ page, authData }) => {
+  try {
+    const twoFactorInput = page.getByTestId(authData.twoFactor.locators.codeInput.testId);
+    await twoFactorInput.waitFor({ state: 'visible', timeout: 5000 });
+    await twoFactorInput.fill(authData.twoFactor.code);
+    const proceedButton = page.getByTestId(authData.twoFactor.locators.proceedButton.testId);
+    await proceedButton.click();
+  } catch {
+    // No 2FA prompt — expected for most test accounts
+  }
+});
+
+Then('I should be redirected to {string}', async ({ page, authData }, urlPath) => {
+  await page.waitForURL(`**${urlPath}**`, { timeout: authData.timeouts.login });
+  await page.waitForLoadState('networkidle', { timeout: authData.timeouts.loadState });
+});

package/e2e-tests/features/playwright-bdd/shared/common.steps.js

@@ -0,0 +1,52 @@
+/**
+ * Shared common steps — generic assertions and utilities.
+ * Lives in shared/ (no @-prefix) so it is globally scoped.
+ */
+import { Given, When, Then, Before, expect } from '../../../playwright/fixtures.js';
+
+Then('I should see the heading {string}', async ({ page }, headingText) => {
+  await expect(page.getByRole('heading', { name: headingText }).first()).toBeVisible();
+});
+
+Then('I should see a tab {string} that is active', async ({ page }, tabName) => {
+  const tab = page.getByRole('tab', { name: tabName });
+  await expect(tab).toBeVisible();
+  await expect(tab).toHaveAttribute('aria-selected', 'true');
+});
+
+When('I click the tab {string}', async ({ page }, tabName) => {
+  const tab = page.getByRole('tab', { name: tabName });
+  await tab.click();
+});
+
+When('I click the tab with test ID {string}', async ({ page }, testId) => {
+  await page.getByTestId(testId).click();
+});
+
+Then('the tab with test ID {string} should be active', async ({ page }, testId) => {
+  const tab = page.getByTestId(testId);
+  await expect(tab).toHaveAttribute('aria-selected', 'true');
+});
+
+Given('I clear browser storage', async ({ page, testConfig }) => {
+  // Navigate to the app origin first so localStorage/sessionStorage are accessible.
+  // On about:blank or cross-origin pages, browsers throw SecurityError when
+  // accessing storage APIs.
+  const currentUrl = page.url();
+  if (!currentUrl || currentUrl === 'about:blank' || !currentUrl.startsWith('http')) {
+    const baseUrl = testConfig?.baseUrl || process.env.BASE_URL || 'http://localhost:5173';
+    await page.goto(baseUrl, { waitUntil: 'commit' });
+  }
+
+  await page.evaluate(() => {
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+  // Clear cookies
+  const context = page.context();
+  await context.clearCookies();
+});
+
+Then('the page should have title containing {string}', async ({ page }, titlePart) => {
+  await expect(page).toHaveTitle(new RegExp(titlePart));
+});