@specwright/plugin 0.1.0

package/e2e-tests/features/playwright-bdd/shared/global-hooks.js

@@ -0,0 +1,44 @@
+/**
+ * Global BDD Hooks — auto-loaded via playwright config glob.
+ * DO NOT import this file manually — it causes duplicate hooks.
+ */
+import { Before, After } from '../../../playwright/fixtures.js';
+import { extractModuleName, loadScopedTestData, deriveDataScope } from '../../../playwright/fixtures.js';
+
+/**
+ * Before each scenario:
+ * - Reset page.testData to empty object (scenario-scoped)
+ * - Derive featureKey from directory path
+ * - Hydrate in-memory cache if needed
+ */
+Before(async function ({ page, testData, $tags, $testInfo }) {
+  // Reset scenario-scoped test data
+  Object.keys(testData).forEach((key) => delete testData[key]);
+
+  // Extract module name from feature URI for cache key
+  const featureUri = $testInfo?.titlePath?.[1] || '';
+  const featureKey = extractModuleName(featureUri);
+
+  if (featureKey) {
+    // Initialize in-memory feature data cache if not present
+    if (!globalThis.__rt_featureDataCache) {
+      globalThis.__rt_featureDataCache = {};
+    }
+    if (!globalThis.__rt_featureDataCache[featureKey]) {
+      // Try to load from file-backed storage
+      const scope = deriveDataScope(featureUri, $tags || []);
+      globalThis.__rt_featureDataCache[featureKey] = loadScopedTestData(scope);
+    }
+  }
+});
+
+/**
+ * After each scenario:
+ * - Capture screenshot on failure (if enabled via env)
+ */
+After(async function ({ page, $testInfo }) {
+  if ($testInfo?.status === 'failed' && process.env.ENABLE_SCREENSHOTS === 'true') {
+    const screenshotName = `failure-${$testInfo.title.replace(/[^a-z0-9]/gi, '-')}`;
+    await page.screenshot({ path: `reports/screenshots/${screenshotName}.png` });
+  }
+});

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

@@ -0,0 +1,47 @@
+/**
+ * Shared navigation 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 on the {string} page', async ({ page, testConfig }, pageName) => {
+  const route = testConfig.routes[pageName];
+  if (!route) {
+    throw new Error(`Unknown page name: "${pageName}". Available: ${Object.keys(testConfig.routes).join(', ')}`);
+  }
+  await page.goto(route);
+  await page.waitForLoadState('networkidle', { timeout: testConfig.timeout.loadState });
+});
+
+When('I navigate to {string}', async ({ page, testConfig }, urlPath) => {
+  await page.goto(urlPath);
+  await page.waitForLoadState('networkidle', { timeout: testConfig.timeout.loadState });
+});
+
+When('I click the link {string}', async ({ page }, linkText) => {
+  await page.getByRole('link', { name: linkText }).click();
+});
+
+When('I click the button {string}', async ({ page }, buttonText) => {
+  await page.getByRole('button', { name: buttonText }).click();
+});
+
+Then('the URL should contain {string}', async ({ page }, urlPart) => {
+  await expect(page).toHaveURL(new RegExp(urlPart));
+});
+
+Then('I should see the text {string}', async ({ page }, text) => {
+  await expect(page.getByText(text, { exact: false }).first()).toBeVisible();
+});
+
+Then('the element with test ID {string} should be visible', async ({ page }, testId) => {
+  await expect(page.getByTestId(testId)).toBeVisible();
+});
+
+Then('the element with test ID {string} should be disabled', async ({ page }, testId) => {
+  await expect(page.getByTestId(testId)).toBeDisabled();
+});
+
+Then('the element with test ID {string} should be enabled', async ({ page }, testId) => {
+  await expect(page.getByTestId(testId)).toBeEnabled();
+});

package/e2e-tests/instructions.example.js

@@ -0,0 +1,110 @@
+/**
+ * instructions.js — Usage Examples
+ *
+ * Copy any entry below into instructions.js to generate BDD tests.
+ * Run with: /e2e-automate (Claude Code skill)
+ *
+ * After generation, run:
+ *   pnpm bddgen          # regenerate .features-gen/
+ *   pnpm test:bdd         # run all BDD tests
+ */
+
+export default [
+  // ─────────────────────────────────────────────────────────────
+  // Example 1: Text instructions — describe what to test
+  // ─────────────────────────────────────────────────────────────
+  {
+    filePath: '',
+    moduleName: '@YourModule',
+    category: '@Modules',
+    subModuleName: [],
+    fileName: 'your_feature',
+    instructions: [
+      'Navigate to the target page (authenticated)',
+      'Verify the main content loads correctly',
+      'Fill out a form and submit',
+      'Verify the result appears',
+      'Test with invalid input and verify error messages',
+    ],
+    pageURL: 'http://localhost:5173/your-page', // Update: your app's URL
+    inputs: {},
+    explore: true,
+    runExploredCases: false,
+    runGeneratedCases: false,
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Example 2: Jira-driven test generation
+  // ─────────────────────────────────────────────────────────────
+  {
+    filePath: '',
+    moduleName: '@YourModule',
+    category: '@Modules',
+    subModuleName: [],
+    fileName: 'your_feature',
+    instructions: [],
+    pageURL: 'http://localhost:5173/your-page', // Update: your app's URL
+    inputs: {
+      jira: {
+        url: 'https://your-org.atlassian.net/browse/PROJ-123', // Update: your Jira URL
+      },
+    },
+    explore: true,
+    runExploredCases: false,
+    runGeneratedCases: false,
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Example 3: CSV file-based test generation
+  // ─────────────────────────────────────────────────────────────
+  {
+    filePath: 'e2e-tests/files/test-cases.csv', // Update: your CSV path
+    moduleName: '@YourModule',
+    category: '@Modules',
+    subModuleName: [],
+    fileName: 'your_feature',
+    instructions: [],
+    pageURL: 'http://localhost:5173/your-page',
+    inputs: {},
+    explore: false,
+    runExploredCases: false,
+    runGeneratedCases: true,
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Example 4: Cross-module workflow
+  // ─────────────────────────────────────────────────────────────
+  {
+    filePath: '',
+    moduleName: '@YourWorkflow',
+    category: '@Workflows',
+    subModuleName: ['@Step1', '@Step2'],
+    fileName: 'workflow_name',
+    instructions: [
+      'Precondition: Create required data',
+      'Step 1: Process the created data',
+      'Step 2: Verify the result',
+    ],
+    pageURL: 'http://localhost:5173/your-page',
+    inputs: {},
+    explore: true,
+    runExploredCases: false,
+    runGeneratedCases: false,
+  },
+];
+
+/**
+ * Field Reference:
+ *
+ * filePath      — Source file (CSV, Excel, PDF, JSON). Leave "" for instruction/Jira-based.
+ * moduleName    — Target module directory name (e.g., "@Dashboard", "@Settings").
+ * category      — "@Modules" (default) or "@Workflows".
+ * subModuleName — Array of nested subdirectories.
+ * fileName      — Output filename stem (e.g., "dashboard" → dashboard.feature + steps.js).
+ * instructions  — Free-text test descriptions.
+ * pageURL       — App URL for exploration. Required when explore: true.
+ * inputs.jira.url — Jira ticket URL for requirements extraction.
+ * explore       — Enable live browser exploration for selector discovery.
+ * runExploredCases  — Run explored seed tests before BDD generation (Phase 5).
+ * runGeneratedCases — Run generated BDD tests after creation (Phase 8).
+ */

package/e2e-tests/instructions.js

@@ -0,0 +1,9 @@
+/**
+ * instructions.js — Test Automation Pipeline Configuration
+ *
+ * Add your test generation configs here.
+ * See instructions.example.js for examples.
+ * Run with: /e2e-automate (Claude Code skill)
+ */
+
+export default [];

package/e2e-tests/playwright/auth.setup.js

@@ -0,0 +1,74 @@
+/**
+ * Authentication Setup — react-template two-step localStorage login
+ *
+ * Flow:
+ * 1. Navigate to /signin
+ * 2. Fill email → click email submit
+ * 3. Wait for password field → fill password → click login submit
+ * 4. Handle 2FA if twoFactorCodeInput appears
+ * 5. Wait for redirect to /home
+ * 6. Save storageState (captures localStorage: tfauth-token, tfcurrent-user)
+ */
+import { test as setup } from '@playwright/test';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { authenticationData } from '../data/authenticationData.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const authFile = path.join(__dirname, './auth-storage/.auth/user.json');
+
+setup('authenticate', async ({ page }) => {
+  console.log('Starting authentication setup...');
+
+  const { validCredentials, locators, timeouts, twoFactor } = authenticationData;
+
+  // Step 1: Navigate to sign-in page
+  await page.goto(`${authenticationData.baseUrl}/signin`);
+  await page.waitForLoadState('networkidle', { timeout: timeouts.loadState });
+  console.log('Navigated to /signin');
+
+  // Step 2: Fill email and submit
+  const emailInput = page.getByTestId(locators.emailInput.testId);
+  await emailInput.waitFor({ state: 'visible', timeout: timeouts.elementWait });
+  await emailInput.fill(validCredentials.email);
+  console.log(`Filled email: ${validCredentials.email}`);
+
+  const emailSubmit = page.getByTestId(locators.emailSubmitButton.testId);
+  await emailSubmit.click();
+  console.log('Clicked email submit');
+
+  // Step 3: Wait for password field, fill, and submit
+  const passwordInput = page.getByTestId(locators.passwordInput.testId);
+  await passwordInput.waitFor({ state: 'visible', timeout: timeouts.elementWait });
+  await passwordInput.fill(validCredentials.password);
+  console.log('Filled password');
+
+  const loginSubmit = page.getByTestId(locators.loginSubmitButton.testId);
+  await loginSubmit.click();
+  console.log('Clicked login submit');
+
+  // Step 4: Handle 2FA if it appears
+  try {
+    const twoFactorInput = page.getByTestId(twoFactor.locators.codeInput.testId);
+    await twoFactorInput.waitFor({ state: 'visible', timeout: 5000 });
+    console.log('2FA detected, entering code...');
+    await twoFactorInput.fill(twoFactor.code);
+    const proceedButton = page.getByTestId(twoFactor.locators.proceedButton.testId);
+    await proceedButton.click();
+    console.log('2FA code submitted');
+  } catch {
+    // No 2FA prompt — expected for most test accounts
+    console.log('No 2FA prompt detected, continuing...');
+  }
+
+  // Step 5: Wait for redirect to /home
+  await page.waitForURL('**/home**', { timeout: timeouts.login });
+  await page.waitForLoadState('networkidle', { timeout: timeouts.loadState });
+  console.log('Login successful — redirected to /home');
+
+  // Step 6: Save authentication state (captures localStorage)
+  await page.context().storageState({ path: authFile });
+  console.log(`Authentication state saved to: ${authFile}`);
+});

package/e2e-tests/playwright/fixtures.js

@@ -0,0 +1,264 @@
+import { test as base, createBdd } from 'playwright-bdd';
+import { authenticationData } from '../data/authenticationData.js';
+import { testConfig as fullTestConfig } from '../data/testConfig.js';
+import dotenv from 'dotenv';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Load environment variables
+dotenv.config();
+
+// Get current directory for resolving test data path
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Test data directory
+const testDataDir = path.join(__dirname, './test-data');
+
+// ==================== SCOPED TEST DATA API ====================
+// Replaces single globalTestData.json with one file per feature/scope.
+// Shared scopes (@cross-feature-data) → flat file at root (e.g., test-data/eobs.json)
+// Feature-specific scopes → hierarchical path (e.g., test-data/auth/login.json)
+
+/**
+ * Extract module name from feature URI based on directory structure.
+ * Single source of truth — imported by global-hooks.js and step files.
+ *
+ * @param {string} featureUri - Feature file path
+ * @returns {string|null} Module name (lowercase)
+ *
+ * Examples:
+ *   "@Workflows/@Authentication/file.feature" → "authentication"
+ *   "@Modules/@HomePage/file.feature" → "homepage"
+ */
+export function extractModuleName(featureUri) {
+  if (!featureUri) return null;
+
+  const parts = featureUri.split('/');
+  const categoriesWithModules = ['@Workflows', '@Modules'];
+
+  for (const category of categoriesWithModules) {
+    const categoryIndex = parts.indexOf(category);
+    if (categoryIndex !== -1 && parts[categoryIndex + 1]) {
+      return parts[categoryIndex + 1].replace('@', '').toLowerCase();
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Convert feature URI to a hierarchical scope path.
+ * Strips @-prefixes and .feature extension, joins with "/".
+ *
+ * @param {string} featureUri - Feature file path
+ * @returns {string} Hierarchical scope path
+ */
+export function featureUriToScopePath(featureUri) {
+  const parts = featureUri.split('/');
+  const catIdx = parts.findIndex((p) => p === '@Modules' || p === '@Workflows');
+  if (catIdx === -1) return parts[parts.length - 1].replace(/\.feature.*$/, '');
+
+  return parts
+    .slice(catIdx + 1)
+    .map((p) => p.replace(/^@/, '').replace(/\.feature.*$/, ''))
+    .filter(Boolean)
+    .map((p) => p.toLowerCase().replace(/[^a-z0-9_]+/g, '-'))
+    .join('/');
+}
+
+/**
+ * Derive the data scope for a feature.
+ * - @cross-feature-data → flat module name (e.g., "auth")
+ * - Otherwise → hierarchical path (e.g., "homepage/navigation")
+ *
+ * @param {string} featureUri - Feature file path
+ * @param {string[]} tags - Test tags array
+ * @returns {string} Scope string (used as file path relative to test-data/)
+ */
+export function deriveDataScope(featureUri, tags = []) {
+  const isCrossFeature = tags.some((t) => t.includes('cross-feature-data'));
+  if (isCrossFeature) {
+    return extractModuleName(featureUri) || 'shared';
+  }
+  return featureUriToScopePath(featureUri);
+}
+
+/**
+ * Resolve scope string to absolute file path.
+ * @param {string} scope - Scope string (flat or hierarchical with "/")
+ * @returns {string} Absolute path to JSON file
+ */
+function scopeToFilePath(scope) {
+  return path.join(testDataDir, `${scope}.json`);
+}
+
+/**
+ * Load test data for a specific scope.
+ * @param {string} scope - Scope string (e.g., "auth" or "homepage/navigation")
+ * @returns {Object} Parsed data or empty object
+ */
+export function loadScopedTestData(scope) {
+  const filePath = scopeToFilePath(scope);
+  if (fs.existsSync(filePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * Save test data to a scoped file. Creates directories recursively.
+ * @param {string} scope - Scope string
+ * @param {Object} data - Data to save
+ */
+export function saveScopedTestData(scope, data) {
+  const filePath = scopeToFilePath(scope);
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  data.updatedAt = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Check if scoped test data file exists.
+ * @param {string} scope - Scope string
+ * @returns {boolean}
+ */
+export function scopedTestDataExists(scope) {
+  return fs.existsSync(scopeToFilePath(scope));
+}
+
+// ==================== FEATURE-LEVEL BROWSER REUSE ====================
+// For serial-execution projects, the browser page persists across scenarios
+// within the same feature file. A new page is created only when the test
+// file changes (i.e., next feature file starts).
+//
+// Benefits:
+// - Page + context created once per feature file (not per scenario)
+// - Client-side state (Zustand store, localStorage) persists across scenarios
+// - Background steps can skip redundant navigation if already on target page
+// - Authentication state persists via storageState on context creation
+
+let _featurePage = null;
+let _featureContext = null;
+let _lastTestFile = null;
+
+const REUSABLE_PROJECTS = ['serial-execution'];
+
+// Extend base test with custom fixtures
+export const test = base.extend({
+  authData: async ({}, use) => {
+    await use(authenticationData);
+  },
+
+  testConfig: async ({}, use) => {
+    await use({
+      ...fullTestConfig,
+      baseUrl: process.env.BASE_URL || fullTestConfig.baseUrl,
+      timeout: {
+        loadState: 60000,
+        elementWait: 10000,
+        networkIdle: 15000,
+      },
+    });
+  },
+
+  testData: async ({}, use) => {
+    await use({});
+  },
+
+  scenarioContext: async ({}, use) => {
+    await use({});
+  },
+
+  // Feature-level page reuse for serial-execution projects.
+  // For these projects, the browser page persists across scenarios within the
+  // same feature file. A fresh context + page is created only when testInfo.file changes.
+  // All other projects retain standard per-scenario isolation.
+  page: async ({ browser }, use, testInfo) => {
+    const { viewport, baseURL, storageState, locale, timezoneId, ignoreHTTPSErrors, video } =
+      testInfo.project.use || {};
+    const contextOptions = {
+      viewport,
+      baseURL,
+      storageState,
+      locale,
+      timezoneId,
+      ignoreHTTPSErrors,
+      ...(video && video !== 'off' ? { recordVideo: { dir: testInfo.outputDir } } : {}),
+    };
+
+    if (REUSABLE_PROJECTS.includes(testInfo.project.name)) {
+      const currentFile = testInfo.file;
+
+      // New feature file → create fresh context + page
+      if (currentFile !== _lastTestFile || !_featurePage || _featurePage.isClosed()) {
+        if (_featureContext) {
+          await _featureContext.close().catch(() => {});
+        }
+        _featureContext = await browser.newContext(contextOptions);
+        _featurePage = await _featureContext.newPage();
+        _lastTestFile = currentFile;
+        console.log(`[BrowserReuse] New page for: ${currentFile.split('/').slice(-2).join('/')}`);
+      } else {
+        console.log(`[BrowserReuse] Reusing page for: ${currentFile.split('/').slice(-2).join('/')}`);
+      }
+
+      await use(_featurePage);
+
+      // Video attachment for reusable projects: on failure, close the shared
+      // context to finalize the video, attach it, then null out refs.
+      const retainAll = process.env.RETAIN_VIDEO_ON_SUCCESS === 'true';
+      const isFailed = testInfo.status !== testInfo.expectedStatus;
+      if (video && video !== 'off' && (isFailed || retainAll)) {
+        try {
+          const videoObj = _featurePage?.video?.();
+          if (videoObj && _featureContext) {
+            await _featureContext.close();
+            const savedPath = testInfo.outputPath('video.webm');
+            await videoObj.saveAs(savedPath);
+            await testInfo.attach('video', { path: savedPath, contentType: 'video/webm' });
+          }
+        } catch (err) {
+          console.log(`[Video][BrowserReuse] Could not attach video: ${err.message}`);
+        }
+        _featurePage = null;
+        _featureContext = null;
+        _lastTestFile = null;
+      }
+    } else {
+      // Default: fresh context + page per scenario (standard Playwright behavior)
+      const context = await browser.newContext(contextOptions);
+      const page = await context.newPage();
+      await use(page);
+
+      const videoObj = video && video !== 'off' ? page.video() : null;
+      await context.close();
+
+      const retainAll = process.env.RETAIN_VIDEO_ON_SUCCESS === 'true';
+      const isFailed = testInfo.status !== testInfo.expectedStatus;
+      if (videoObj && (isFailed || retainAll)) {
+        try {
+          const savedPath = testInfo.outputPath('video.webm');
+          await videoObj.saveAs(savedPath);
+          await testInfo.attach('video', { path: savedPath, contentType: 'video/webm' });
+        } catch (err) {
+          console.log(`[Video] Could not attach video: ${err.message}`);
+        }
+      }
+    }
+  },
+});
+
+// Create BDD functions with custom fixtures
+export const { Given, When, Then, Before, After, BeforeAll, AfterAll } = createBdd(test);
+
+// Export expect from Playwright
+export { expect } from '@playwright/test';

package/e2e-tests/playwright/global.setup.js

@@ -0,0 +1,49 @@
+/**
+ * Global Setup — runs once before all test projects.
+ * Uses a .cleanup-done marker file to detect fresh vs. in-progress runs.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const markerFile = path.join(__dirname, '.cleanup-done');
+const testDataDir = path.join(__dirname, 'test-data');
+const reportsDir = path.join(__dirname, '../../reports');
+
+export default async function globalSetup() {
+  console.log('[global.setup] Starting global setup...');
+
+  if (!fs.existsSync(markerFile)) {
+    // New run — clean previous data
+    console.log('[global.setup] Fresh run detected. Cleaning previous data...');
+
+    // Clean test-data directory (but keep the directory)
+    if (fs.existsSync(testDataDir)) {
+      const files = fs.readdirSync(testDataDir);
+      for (const file of files) {
+        const filePath = path.join(testDataDir, file);
+        fs.rmSync(filePath, { recursive: true, force: true });
+      }
+    } else {
+      fs.mkdirSync(testDataDir, { recursive: true });
+    }
+
+    // Ensure reports directories exist
+    const reportDirs = ['json', 'cucumber-bdd', 'playwright', 'screenshots'];
+    for (const dir of reportDirs) {
+      const dirPath = path.join(reportsDir, dir);
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+      }
+    }
+  } else {
+    console.log('[global.setup] Run in progress — preserving data.');
+  }
+
+  // Place marker
+  fs.writeFileSync(markerFile, new Date().toISOString());
+  console.log('[global.setup] Setup complete.');
+}

package/e2e-tests/playwright/global.teardown.js

@@ -0,0 +1,23 @@
+/**
+ * Global Teardown — runs once after all test projects complete.
+ * Removes the .cleanup-done marker so the next run starts fresh.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const markerFile = path.join(__dirname, '.cleanup-done');
+
+export default async function globalTeardown() {
+  console.log('[global.teardown] Starting global teardown...');
+
+  if (fs.existsSync(markerFile)) {
+    fs.unlinkSync(markerFile);
+    console.log('[global.teardown] Marker file removed.');
+  }
+
+  console.log('[global.teardown] Teardown complete.');
+}