@specwright/plugin 0.1.0

package/e2e-tests/utils/stepHelpers.js

@@ -0,0 +1,404 @@
+/**
+ * Step Definition Helper Functions
+ * Provides reusable utilities for BDD step implementations with data tables.
+ *
+ * Core exports:
+ * - FIELD_TYPES       — declarative field type constants
+ * - processDataTable  — fills forms from Gherkin 3-column data tables
+ * - validateExpectations — asserts displayed values from data tables
+ * - fillFieldByName   — fill a single field using selector priority hierarchy
+ * - selectDropDownByTestId — select option from a react-select dropdown
+ */
+
+import { expect } from '@playwright/test';
+import _ from 'lodash';
+import { generateValueForField } from './testDataGenerator.js';
+
+// ─────────────────────────────────────────────────────────────
+// FIELD_TYPES — declarative type constants
+// ─────────────────────────────────────────────────────────────
+export const FIELD_TYPES = {
+  // Interaction types (used in processDataTable fieldConfig)
+  FILL: 'FILL', // plain text input
+  FILL_AND_ENTER: 'FILL_AND_ENTER', // fill then press Enter (multi-select tags)
+  DROPDOWN: 'DROPDOWN', // react-select dropdown
+  COMBO_BOX: 'COMBO_BOX', // creatable select (creates new option)
+  CLICK: 'CLICK', // button / toggle via click
+  CHECKBOX_TOGGLE: 'CHECKBOX_TOGGLE', // checkbox by label text
+  TOGGLE: 'TOGGLE', // boolean toggle switch
+  CUSTOM: 'CUSTOM', // write a fieldHandler for truly unique interactions
+
+  // Validation types (used in validateExpectations validationConfig)
+  INPUT_VALUE: 'INPUT_VALUE', // assert text input .value (toHaveValue)
+  MULTI_SELECT_TAG: 'MULTI_SELECT_TAG', // react-select multi-value chip visible
+  DROPDOWN_SINGLE_VALUE: 'DROPDOWN_SINGLE_VALUE', // react-select single-value text
+  TEXT_VISIBLE: 'TEXT_VISIBLE', // assert text is visible by testID
+};
+
+// ─────────────────────────────────────────────────────────────
+// processDataTable — fills forms from 3-column Gherkin data tables
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Process a 3-column Gherkin data table (Field Name | Value | Type)
+ * and interact with each field based on its FIELD_TYPE configuration.
+ *
+ * Handles:
+ * - <gen_test_data> → generates faker value, caches in featureDataCache
+ * - <from_test_data> → reads previously cached value
+ * - Static values → uses as-is
+ *
+ * @param {Page} page - Playwright page
+ * @param {DataTable} dataTable - Gherkin data table
+ * @param {Object} config
+ * @param {Object} config.mapping - Field name → page.testData property name
+ * @param {Object} config.fieldConfig - Field name → { type: FIELD_TYPES.*, testID?, selector?, ... }
+ * @param {Object} config.fieldHandlers - Field name → async (page, value) => {} for CUSTOM types
+ * @param {Locator|Page} config.container - Scope all locators to this element (default: page)
+ */
+export async function processDataTable(page, dataTable, config = {}) {
+  const { mapping = {}, fieldConfig = {}, fieldHandlers = {}, container = page } = config;
+
+  const rows = dataTable.hashes();
+
+  for (const row of rows) {
+    const fieldName = row['Field Name'] || row['Field'] || row['Name'];
+    const valueType = (row['Type'] || 'Static').toLowerCase();
+    let value = row['Value'] || row['Expected Value'] || '';
+
+    // ── Step 1: Resolve value from placeholder ──
+    if (value === '<gen_test_data>') {
+      // Generate: check if mapping points to existing testData, otherwise generate with faker
+      if (mapping[fieldName] && page.testData?.[mapping[fieldName]] !== undefined) {
+        value = page.testData[mapping[fieldName]];
+      } else {
+        value = generateValueForField(fieldName);
+      }
+      // Cache SharedGenerated values for later <from_test_data> reads
+      if (valueType === 'sharedgenerated') {
+        const cacheKey = mapping[fieldName] || _.snakeCase(fieldName);
+        if (!page.testData) page.testData = {};
+        page.testData[cacheKey] = value;
+        // Also write to featureDataCache for cross-scenario persistence
+        const featureKey = getFeatureKey(page);
+        if (featureKey) {
+          if (!globalThis.__rt_featureDataCache) globalThis.__rt_featureDataCache = {};
+          if (!globalThis.__rt_featureDataCache[featureKey]) globalThis.__rt_featureDataCache[featureKey] = {};
+          globalThis.__rt_featureDataCache[featureKey][cacheKey] = value;
+        }
+        console.log(`🎲 Generated "${fieldName}" → ${cacheKey}: ${value}`);
+      }
+    } else if (value === '<from_test_data>') {
+      // Read: look up from page.testData or featureDataCache
+      const cacheKey = mapping[fieldName] || _.snakeCase(fieldName);
+      if (page.testData?.[cacheKey] !== undefined) {
+        value = page.testData[cacheKey];
+        console.log(`📖 Read "${fieldName}" → ${cacheKey}: ${value}`);
+      } else {
+        // Try featureDataCache
+        const featureKey = getFeatureKey(page);
+        const cached = featureKey && globalThis.__rt_featureDataCache?.[featureKey]?.[cacheKey];
+        if (cached) {
+          value = cached;
+          console.log(`📖 Read from cache "${fieldName}" → ${cacheKey}: ${value}`);
+        } else {
+          console.warn(`⚠️ No cached value for "${fieldName}" (key: ${cacheKey})`);
+        }
+      }
+    }
+    // Static values: use as-is
+
+    // ── Step 2: Interact with the field ──
+    if (fieldHandlers[fieldName]) {
+      await fieldHandlers[fieldName](page, value);
+    } else if (fieldConfig[fieldName]) {
+      await executeFieldInteraction(page, fieldName, value, fieldConfig[fieldName], container);
+    } else {
+      // Fallback: try to fill by testID derived from field name
+      await fillFieldByName(container, fieldName, value);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// validateExpectations — asserts displayed values from data tables
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate displayed values from a 3-column Gherkin data table.
+ * Reads <from_test_data> from page.testData or featureDataCache.
+ *
+ * @param {Page} page - Playwright page
+ * @param {DataTable} dataTable - Gherkin data table
+ * @param {Object} config
+ * @param {Object} config.mapping - Field name → page.testData property name
+ * @param {Object} config.validationConfig - Field name → { type: FIELD_TYPES.*, testID?, selector? }
+ * @param {Locator|Page} config.container - Scope assertions to this element (default: page)
+ */
+export async function validateExpectations(page, dataTable, config = {}) {
+  const { mapping = {}, validationConfig = {}, container = page } = config;
+
+  const rows = dataTable.hashes();
+
+  for (const row of rows) {
+    const fieldName = row['Field Name'] || row['Field'] || row['Element'];
+    let expectedValue = row['Expected Value'] || row['Value'] || '';
+
+    // ── Resolve <from_test_data> placeholder ──
+    if (expectedValue === '<from_test_data>') {
+      const cacheKey = mapping[fieldName] || _.snakeCase(fieldName);
+      if (page.testData?.[cacheKey] !== undefined) {
+        expectedValue = page.testData[cacheKey];
+        console.log(`✅ Validate "${fieldName}" → ${cacheKey}: ${expectedValue}`);
+      } else {
+        const featureKey = getFeatureKey(page);
+        const cached = featureKey && globalThis.__rt_featureDataCache?.[featureKey]?.[cacheKey];
+        if (cached) {
+          expectedValue = cached;
+          console.log(`✅ Validate from cache "${fieldName}" → ${cacheKey}: ${expectedValue}`);
+        } else {
+          throw new Error(
+            `No cached value for "${fieldName}" (key: ${cacheKey}). Was <gen_test_data> used in a prior fill step?`,
+          );
+        }
+      }
+    }
+
+    // ── Execute validation ──
+    const vConfig = validationConfig[fieldName];
+    if (vConfig) {
+      await executeValidation(page, fieldName, expectedValue, vConfig, container);
+    } else {
+      // Fallback: find element by text
+      await expect(page.getByText(expectedValue, { exact: false }).first()).toBeVisible();
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// fillFieldByName — fill a single field using selector priority
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Fill a field using Playwright's selector priority hierarchy.
+ * Tries: testID → name → placeholder → label → CSS fallback
+ */
+export async function fillFieldByName(container, fieldName, value) {
+  const fieldKebab = _.kebabCase(fieldName);
+
+  const strategies = [
+    () => container.getByTestId(fieldKebab),
+    () => container.getByTestId(`input-${fieldKebab}`),
+    () => container.locator(`input[name="${fieldName}"]`),
+    () => container.locator(`input[name="${fieldKebab}"]`),
+    () => container.getByPlaceholder(new RegExp(fieldName, 'i')),
+    () => container.getByLabel(fieldName),
+    () => container.getByRole('textbox', { name: fieldName }),
+  ];
+
+  for (const getLocator of strategies) {
+    try {
+      const element = getLocator();
+      if ((await element.count()) > 0) {
+        const target = (await element.count()) > 1 ? element.first() : element;
+        await target.fill(value);
+        return;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  throw new Error(`Could not find field "${fieldName}" using any selector strategy.`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// selectDropDownByTestId — select option from react-select
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Select an option from a React Select dropdown by testID.
+ * Opens the dropdown, finds the option by text, clicks it.
+ */
+export async function selectDropDownByTestId(page, fieldName, value, autoKebab = true) {
+  const testId = autoKebab ? _.kebabCase(fieldName) : fieldName;
+
+  const dropdownContainer = page.getByTestId(testId);
+  await dropdownContainer.waitFor({ state: 'visible', timeout: 5000 });
+
+  const control = dropdownContainer
+    .locator('.react-select__control, .react-select__dropdown-indicator, [class*="select__control"]')
+    .first();
+  await control.waitFor({ state: 'visible', timeout: 5000 });
+  await control.click();
+  await page.waitForTimeout(300);
+
+  // Portal renders at document.body — must use page root
+  const option = page.locator('.react-select__menu-list').locator('.react-select__option').filter({ hasText: value });
+
+  await option.waitFor({ state: 'visible', timeout: 5000 });
+  await option.click();
+
+  await page
+    .locator('.react-select__menu-list')
+    .waitFor({ state: 'detached', timeout: 3000 })
+    .catch(() => {});
+  await page.waitForTimeout(300);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Internal: executeFieldInteraction
+// ─────────────────────────────────────────────────────────────
+
+async function executeFieldInteraction(page, fieldName, value, config, container = page) {
+  switch (config.type) {
+    case FIELD_TYPES.FILL:
+      if (config.testID) {
+        const el = container.getByTestId(config.testID);
+        const count = await el.count();
+        await (count > 1 ? el.first() : el).fill(value);
+      } else if (config.selector) {
+        await container.locator(config.selector).fill(value);
+      } else if (config.placeholder) {
+        await container.getByPlaceholder(config.placeholder).fill(value);
+      } else {
+        await fillFieldByName(container, fieldName, value);
+      }
+      break;
+
+    case FIELD_TYPES.FILL_AND_ENTER: {
+      const input = container.getByRole(config.role || 'textbox', {
+        name: config.name || fieldName,
+      });
+      await input.fill(value);
+      await input.press('Enter');
+      break;
+    }
+
+    case FIELD_TYPES.DROPDOWN:
+      if (config.testID) {
+        const dropEl = container.getByTestId(config.testID);
+        const ctrl = dropEl.locator('.react-select__control, .react-select__dropdown-indicator').first();
+        await ctrl.waitFor({ state: 'visible', timeout: 5000 });
+        await ctrl.click();
+        await page.waitForTimeout(300);
+        const menuList = page.locator('.react-select__menu-list');
+        await expect(menuList).toBeVisible({ timeout: 5000 });
+        const opt = menuList.locator('.react-select__option').filter({ hasText: value });
+        const matched = (await opt.count()) > 0 ? opt.first() : menuList.locator('.react-select__option').first();
+        await matched.click();
+        await page
+          .locator('.react-select__menu-list')
+          .waitFor({ state: 'detached', timeout: 3000 })
+          .catch(() => {});
+        await page.waitForTimeout(300);
+      } else {
+        await selectDropDownByTestId(page, fieldName, value);
+      }
+      break;
+
+    case FIELD_TYPES.COMBO_BOX:
+      if (config.testID) {
+        await container.getByTestId(config.testID).fill(value);
+      } else if (config.placeholder) {
+        await container.getByPlaceholder(config.placeholder).fill(value);
+      } else {
+        await fillFieldByName(container, fieldName, value);
+      }
+      await page.getByRole('link', { name: `Create: ${value}` }).click();
+      break;
+
+    case FIELD_TYPES.CLICK:
+      if (config.testID) {
+        await container.getByTestId(config.testID).click();
+      } else if (config.selector) {
+        await container.locator(config.selector).click();
+      } else if (config.role) {
+        await container.getByRole(config.role, { name: config.name || value }).click();
+      } else {
+        await container.getByText(value).click();
+      }
+      break;
+
+    case FIELD_TYPES.CHECKBOX_TOGGLE:
+      if (config.testID) {
+        await container.getByTestId(config.testID).filter({ hasText: fieldName }).click();
+      } else {
+        await container.getByTestId('checkbox').filter({ hasText: fieldName }).click();
+      }
+      break;
+
+    case FIELD_TYPES.TOGGLE:
+      if (config.testID) {
+        await container.getByTestId(config.testID).click();
+      } else if (config.selector) {
+        await container.locator(config.selector).click();
+      }
+      break;
+
+    case FIELD_TYPES.CUSTOM:
+      console.warn(`CUSTOM field "${fieldName}" requires a fieldHandler. Skipping.`);
+      break;
+
+    default:
+      if (config.testID) {
+        await container.getByTestId(config.testID).fill(value);
+      } else {
+        await fillFieldByName(container, fieldName, value);
+      }
+      break;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Internal: executeValidation
+// ─────────────────────────────────────────────────────────────
+
+async function executeValidation(page, fieldName, expectedValue, config, container = page) {
+  switch (config.type) {
+    case FIELD_TYPES.INPUT_VALUE:
+      if (config.testID) {
+        await expect(container.getByTestId(config.testID)).toHaveValue(expectedValue, { timeout: 5000 });
+      } else if (config.selector) {
+        await expect(container.locator(config.selector)).toHaveValue(expectedValue, { timeout: 5000 });
+      }
+      break;
+
+    case FIELD_TYPES.MULTI_SELECT_TAG:
+      await expect(
+        container.locator('.react-select__multi-value__label').filter({ hasText: expectedValue }),
+      ).toBeVisible({ timeout: 5000 });
+      break;
+
+    case FIELD_TYPES.DROPDOWN_SINGLE_VALUE:
+      if (config.testID) {
+        await expect(container.locator(`[data-testid="${config.testID}"] .react-select__single-value`)).toContainText(
+          expectedValue,
+          { timeout: 5000 },
+        );
+      }
+      break;
+
+    case FIELD_TYPES.TEXT_VISIBLE:
+      if (config.testID) {
+        const el = container.getByTestId(config.testID);
+        await expect(el).toBeVisible();
+        await expect(el).toHaveText(expectedValue);
+      } else {
+        await expect(page.getByText(expectedValue, { exact: false }).first()).toBeVisible();
+      }
+      break;
+
+    default:
+      await expect(page.getByText(expectedValue, { exact: false }).first()).toBeVisible();
+      break;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Internal: getFeatureKey helper
+// ─────────────────────────────────────────────────────────────
+
+function getFeatureKey(page) {
+  return page.featureKey || null;
+}

package/e2e-tests/utils/testDataGenerator.js

@@ -0,0 +1,38 @@
+/**
+ * Test Data Generator — faker-based data utilities
+ * Used by processDataTable for dynamic value generation
+ */
+import { faker } from '@faker-js/faker';
+
+/**
+ * Generate a value based on the field name.
+ * Uses faker to produce realistic, type-appropriate data.
+ *
+ * @param {string} fieldName - Human-readable field name (e.g., "Name", "Email", "Phone")
+ * @returns {string} Generated value
+ */
+export function generateValueForField(fieldName) {
+  const field = fieldName.toLowerCase();
+
+  if (field.includes('email')) return faker.internet.email().toLowerCase();
+  if (field.includes('phone')) return faker.phone.number({ style: 'national' });
+  if (field.includes('name') && field.includes('company')) return faker.company.name();
+  if (field.includes('name')) return faker.person.fullName();
+  if (field.includes('catchphrase') || field.includes('catch phrase')) return faker.company.catchPhrase();
+  if (field.includes('address') || field.includes('street')) return faker.location.streetAddress();
+  if (field.includes('city')) return faker.location.city();
+  if (field.includes('zip') || field.includes('postal')) return faker.location.zipCode();
+  if (field.includes('country')) return faker.location.country();
+  if (field.includes('state')) return faker.location.state();
+  if (field.includes('website') || field.includes('url')) return faker.internet.url();
+  if (field.includes('description') || field.includes('comment')) return faker.lorem.sentence();
+  if (field.includes('id') || field.includes('number') || field.includes('code'))
+    return faker.string.alphanumeric(8).toUpperCase();
+  if (field.includes('tag')) return faker.string.alphanumeric(6).toUpperCase();
+  if (field.includes('date')) return faker.date.future().toISOString().split('T')[0];
+  if (field.includes('amount') || field.includes('price') || field.includes('quantity'))
+    return faker.number.int({ min: 1, max: 1000 }).toString();
+
+  // Default: random word with timestamp suffix for uniqueness
+  return `${faker.lorem.word()}_${Date.now().toString().slice(-6)}`;
+}

package/install.sh

@@ -0,0 +1,148 @@
+#!/bin/bash
+# E2E Automation Plugin — Installation Script
+# Run from your project root: bash path/to/e2e-plugin/install.sh
+# Options:
+#   --skip-auth    Skip installing authentication test module
+
+set -e
+
+PLUGIN_DIR="$(cd "$(dirname "$0")" && pwd)"
+TARGET_DIR=""
+SKIP_AUTH=false
+
+# Parse arguments — first non-flag argument is the target directory
+for arg in "$@"; do
+  case $arg in
+    --skip-auth) SKIP_AUTH=true ;;
+    -*) ;; # skip unknown flags
+    *) [ -z "$TARGET_DIR" ] && TARGET_DIR="$arg" ;;
+  esac
+done
+
+# Default to current directory if no target specified
+TARGET_DIR="${TARGET_DIR:-$(pwd)}"
+
+echo "╔══════════════════════════════════════════════╗"
+echo "║  E2E Automation Plugin — Installing          ║"
+echo "╚══════════════════════════════════════════════╝"
+echo ""
+echo "Source: $PLUGIN_DIR"
+echo "Target: $TARGET_DIR"
+if [ "$SKIP_AUTH" = true ]; then
+  echo "Option: --skip-auth (authentication module will NOT be installed)"
+fi
+echo ""
+
+# ── Step 1: Copy .claude/ directory ──
+echo "📦 Step 1: Installing .claude/ (agents, skills, rules)..."
+mkdir -p "$TARGET_DIR/.claude/agents/playwright"
+mkdir -p "$TARGET_DIR/.claude/skills"
+mkdir -p "$TARGET_DIR/.claude/rules"
+mkdir -p "$TARGET_DIR/.claude/memory"
+mkdir -p "$TARGET_DIR/.claude/agent-memory/playwright-test-planner"
+mkdir -p "$TARGET_DIR/.claude/agent-memory/playwright-test-healer"
+mkdir -p "$TARGET_DIR/.claude/agent-memory/execution-manager"
+
+cp -r "$PLUGIN_DIR/.claude_agents/"* "$TARGET_DIR/.claude/agents/"
+cp -r "$PLUGIN_DIR/.claude_skills/"* "$TARGET_DIR/.claude/skills/"
+cp -r "$PLUGIN_DIR/.claude_rules/"* "$TARGET_DIR/.claude/rules/"
+cp "$PLUGIN_DIR/.claude_README.md" "$TARGET_DIR/.claude/README.md"
+cp "$PLUGIN_DIR/.claude_memory_MEMORY.md" "$TARGET_DIR/.claude/memory/MEMORY.md"
+cp "$PLUGIN_DIR/.claude_agent-memory/playwright-test-planner/MEMORY.md" "$TARGET_DIR/.claude/agent-memory/playwright-test-planner/"
+cp "$PLUGIN_DIR/.claude_agent-memory/playwright-test-healer/MEMORY.md" "$TARGET_DIR/.claude/agent-memory/playwright-test-healer/"
+cp "$PLUGIN_DIR/.claude_agent-memory/execution-manager/MEMORY.md" "$TARGET_DIR/.claude/agent-memory/execution-manager/"
+echo "  ✅ .claude/ installed"
+
+# ── Step 2: Copy e2e-tests/ infrastructure ──
+echo "📦 Step 2: Installing e2e-tests/ infrastructure..."
+mkdir -p "$TARGET_DIR/e2e-tests/playwright/auth-storage/.auth"
+mkdir -p "$TARGET_DIR/e2e-tests/playwright/generated"
+mkdir -p "$TARGET_DIR/e2e-tests/playwright/test-data"
+mkdir -p "$TARGET_DIR/e2e-tests/features/playwright-bdd/shared"
+mkdir -p "$TARGET_DIR/e2e-tests/utils"
+mkdir -p "$TARGET_DIR/e2e-tests/data"
+
+cp "$PLUGIN_DIR/e2e-tests/playwright/fixtures.js" "$TARGET_DIR/e2e-tests/playwright/"
+cp "$PLUGIN_DIR/e2e-tests/playwright/auth.setup.js" "$TARGET_DIR/e2e-tests/playwright/"
+cp "$PLUGIN_DIR/e2e-tests/playwright/global.setup.js" "$TARGET_DIR/e2e-tests/playwright/"
+cp "$PLUGIN_DIR/e2e-tests/playwright/global.teardown.js" "$TARGET_DIR/e2e-tests/playwright/"
+cp "$PLUGIN_DIR/e2e-tests/utils/stepHelpers.js" "$TARGET_DIR/e2e-tests/utils/"
+cp "$PLUGIN_DIR/e2e-tests/utils/testDataGenerator.js" "$TARGET_DIR/e2e-tests/utils/"
+cp "$PLUGIN_DIR/e2e-tests/features/playwright-bdd/shared/"*.js "$TARGET_DIR/e2e-tests/features/playwright-bdd/shared/"
+cp "$PLUGIN_DIR/e2e-tests/data/authenticationData.js" "$TARGET_DIR/e2e-tests/data/"
+cp "$PLUGIN_DIR/e2e-tests/data/testConfig.js" "$TARGET_DIR/e2e-tests/data/"
+cp "$PLUGIN_DIR/e2e-tests/instructions.js" "$TARGET_DIR/e2e-tests/"
+cp "$PLUGIN_DIR/e2e-tests/instructions.example.js" "$TARGET_DIR/e2e-tests/"
+cp "$PLUGIN_DIR/e2e-tests/.env.testing" "$TARGET_DIR/e2e-tests/"
+
+# Gitkeep files + directory stubs
+touch "$TARGET_DIR/e2e-tests/playwright/auth-storage/.auth/.gitkeep"
+touch "$TARGET_DIR/e2e-tests/playwright/generated/.gitkeep"
+touch "$TARGET_DIR/e2e-tests/playwright/test-data/.gitkeep"
+mkdir -p "$TARGET_DIR/e2e-tests/features/playwright-bdd/@Modules"
+mkdir -p "$TARGET_DIR/e2e-tests/features/playwright-bdd/@Workflows"
+touch "$TARGET_DIR/e2e-tests/features/playwright-bdd/@Modules/.gitkeep"
+touch "$TARGET_DIR/e2e-tests/features/playwright-bdd/@Workflows/.gitkeep"
+echo "  ✅ e2e-tests/ infrastructure installed"
+
+# ── Step 3: Install authentication module (unless --skip-auth) ──
+if [ "$SKIP_AUTH" = true ]; then
+  echo "⏭️  Step 3: Authentication module — SKIPPED (--skip-auth)"
+else
+  echo "📦 Step 3: Installing authentication test module..."
+  mkdir -p "$TARGET_DIR/e2e-tests/features/playwright-bdd/@Modules/@Authentication"
+  cp "$PLUGIN_DIR/e2e-tests/features/playwright-bdd/@Modules/@Authentication/authentication.feature" \
+     "$TARGET_DIR/e2e-tests/features/playwright-bdd/@Modules/@Authentication/"
+  cp "$PLUGIN_DIR/e2e-tests/features/playwright-bdd/@Modules/@Authentication/steps.js" \
+     "$TARGET_DIR/e2e-tests/features/playwright-bdd/@Modules/@Authentication/"
+  echo "  ✅ @Authentication module installed (7 scenarios)"
+fi
+
+# ── Step 4: Copy playwright config ──
+echo "📦 Step 4: Installing playwright.config.ts..."
+if [ -f "$TARGET_DIR/playwright.config.ts" ]; then
+  echo "  ⚠️  playwright.config.ts already exists — backed up to playwright.config.ts.bak"
+  cp "$TARGET_DIR/playwright.config.ts" "$TARGET_DIR/playwright.config.ts.bak"
+fi
+cp "$PLUGIN_DIR/playwright.config.ts" "$TARGET_DIR/"
+echo "  ✅ playwright.config.ts installed"
+
+# ── Step 5: Copy documentation ──
+echo "📦 Step 5: Installing documentation..."
+cp "$PLUGIN_DIR/README-TESTING.md" "$TARGET_DIR/"
+echo "  ✅ README-TESTING.md installed"
+
+# ── Done ──
+echo ""
+echo "╔══════════════════════════════════════════════╗"
+echo "║  Installation Complete                        ║"
+echo "╚══════════════════════════════════════════════╝"
+echo ""
+echo "📋 Next steps:"
+echo ""
+echo "  1. Merge devDependencies + scripts from e2e-plugin/package.json.snippet"
+echo "     into your package.json, then run: pnpm install"
+echo ""
+echo "  2. Install Playwright browsers: pnpx playwright install"
+echo ""
+echo "  3. Append lines from e2e-plugin/.gitignore.snippet"
+echo "     to your .gitignore"
+echo ""
+echo "  4. Update e2e-tests/data/authenticationData.js"
+echo "     → Set your app's login form testIDs"
+echo ""
+echo "  5. Update e2e-tests/data/testConfig.js"
+echo "     → Set your app's routes"
+echo ""
+echo "  6. Set credentials in .env:"
+echo "     TEST_USER_EMAIL=your-email@example.com"
+echo "     TEST_USER_PASSWORD=your-password"
+echo "     BASE_URL=http://localhost:5173"
+echo ""
+echo "  7. Start dev server and run tests:"
+echo "     pnpm test:bdd:auth    # Run authentication tests"
+echo "     pnpm test:bdd         # Run all tests (except auth)"
+echo "     pnpm test:bdd:all     # Run everything including auth"
+echo ""
+echo "  8. Generate more tests: /e2e-automate (Claude Code CLI)"
+echo ""

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@specwright/plugin",
+  "version": "0.1.0",
+  "description": "Drop-in E2E test automation framework plugin — Playwright BDD + Claude Code agents",
+  "license": "MIT",
+  "bin": {
+    "specwright-plugin": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "install.sh",
+    "PLUGIN.md",
+    "README-TESTING.md",
+    "playwright.config.ts",
+    "package.json.snippet",
+    ".gitignore.snippet",
+    ".claude_*",
+    "e2e-tests/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "playwright",
+    "bdd",
+    "e2e",
+    "testing",
+    "automation",
+    "claude",
+    "ai",
+    "specwright"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SanthoshDhandapani/specwright.git",
+    "directory": "packages/plugin"
+  },
+  "homepage": "https://github.com/SanthoshDhandapani/specwright"
+}

package/package.json.snippet

@@ -0,0 +1,27 @@
+{
+  "// MERGE THESE into your project's package.json": "",
+  "// Scripts: add all entries under 'scripts'": "",
+  "// DevDependencies: add all entries under 'devDependencies'": "",
+
+  "scripts": {
+    "bddgen": "npx bddgen",
+    "test:bdd": "pnpm bddgen && playwright test --project setup --project serial-execution --project main-e2e",
+    "test:bdd:all": "pnpm bddgen && playwright test",
+    "test:bdd:auth": "pnpm bddgen && playwright test --project setup --project auth-tests",
+    "test:bdd:serial": "pnpm bddgen && playwright test --project setup --project serial-execution",
+    "test:bdd:debug": "pnpm bddgen && PWDEBUG=console playwright test --debug",
+    "test:playwright": "playwright test",
+    "test:playwright:headed": "playwright test --headed",
+    "test:playwright:debug": "playwright test --debug",
+    "report:playwright": "playwright show-report",
+    "test:clean": "rm -rf reports .features-gen test-results e2e-tests/playwright/test-data/*.json"
+  },
+
+  "devDependencies": {
+    "@faker-js/faker": "^10.3.0",
+    "@playwright/test": "^1.54.1",
+    "dotenv": "^17.2.0",
+    "lodash": "^4.17.23",
+    "playwright-bdd": "^8.5.0"
+  }
+}