aigroup-workflow 2.2.1 → 2.2.3

package/skills/quality/senior-qa/scripts/e2e_test_scaffolder.py

@@ -1,820 +1,820 @@
-#!/usr/bin/env python3
-"""
-E2E Test Scaffolder
-
-Scans Next.js pages/app directory and generates Playwright test files
-with common interactions, Page Object Model classes, and configuration.
-
-Usage:
-    python e2e_test_scaffolder.py src/app/ --output e2e/
-    python e2e_test_scaffolder.py pages/ --include-pom --routes "/login,/dashboard"
-"""
-
-import os
-import sys
-import json
-import argparse
-import re
-from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Set
-from dataclasses import dataclass, field, asdict
-from datetime import datetime
-
-
-@dataclass
-class RouteInfo:
-    """Information about a detected route"""
-    path: str  # URL path e.g., /dashboard
-    file_path: str  # File system path
-    route_type: str  # 'page', 'layout', 'api', 'dynamic'
-    has_params: bool
-    params: List[str]
-    has_form: bool
-    has_auth: bool
-    interactions: List[str]
-
-
-@dataclass
-class TestSpec:
-    """A Playwright test specification"""
-    route: RouteInfo
-    test_cases: List[str]
-    imports: Set[str] = field(default_factory=set)
-
-
-@dataclass
-class PageObject:
-    """Page Object Model class definition"""
-    name: str
-    route: str
-    locators: List[Tuple[str, str, str]]  # (name, selector, description)
-    methods: List[Tuple[str, str]]  # (name, code)
-
-
-class RouteScanner:
-    """Scans Next.js directories for routes"""
-
-    # Pattern to detect page files
-    PAGE_PATTERNS = {
-        'page.tsx', 'page.ts', 'page.jsx', 'page.js',  # App Router
-        'index.tsx', 'index.ts', 'index.jsx', 'index.js'  # Pages Router
-    }
-
-    # Patterns indicating specific features
-    FORM_PATTERNS = [
-        r'<form', r'handleSubmit', r'onSubmit', r'useForm',
-        r'<input', r'<textarea', r'<select'
-    ]
-
-    AUTH_PATTERNS = [
-        r'auth', r'login', r'signin', r'signup', r'register',
-        r'useAuth', r'useSession', r'getServerSession', r'withAuth'
-    ]
-
-    INTERACTION_PATTERNS = {
-        'click': r'onClick|button|Button|<a\s|Link',
-        'type': r'<input|<textarea|onChange',
-        'select': r'<select|Dropdown|Select',
-        'navigation': r'useRouter|router\.push|Link',
-        'modal': r'Modal|Dialog|isOpen|onClose',
-        'toggle': r'toggle|Switch|Checkbox',
-        'upload': r'<input.*type=["\']file|upload|dropzone'
-    }
-
-    def __init__(self, source_path: Path, verbose: bool = False):
-        self.source_path = source_path
-        self.verbose = verbose
-        self.routes: List[RouteInfo] = []
-        self.is_app_router = self._detect_router_type()
-
-    def _detect_router_type(self) -> bool:
-        """Detect if using App Router or Pages Router"""
-        # App Router: has 'app' directory with page.tsx files
-        # Pages Router: has 'pages' directory with index.tsx files
-        app_dir = self.source_path / 'app'
-        if app_dir.exists() and list(app_dir.rglob('page.*')):
-            return True
-
-        return 'app' in str(self.source_path).lower()
-
-    def scan(self, filter_routes: Optional[List[str]] = None) -> List[RouteInfo]:
-        """Scan for all routes"""
-        self._scan_directory(self.source_path)
-
-        # Filter if specific routes requested
-        if filter_routes:
-            self.routes = [
-                r for r in self.routes
-                if any(fr in r.path for fr in filter_routes)
-            ]
-
-        return self.routes
-
-    def _scan_directory(self, directory: Path, url_path: str = ''):
-        """Recursively scan directory for routes"""
-        if not directory.exists():
-            return
-
-        for item in directory.iterdir():
-            if item.name.startswith('.') or item.name == 'node_modules':
-                continue
-
-            if item.is_dir():
-                # Handle route groups (parentheses) and dynamic routes
-                dir_name = item.name
-
-                if dir_name.startswith('(') and dir_name.endswith(')'):
-                    # Route group - doesn't add to URL path
-                    self._scan_directory(item, url_path)
-                elif dir_name.startswith('[') and dir_name.endswith(']'):
-                    # Dynamic route
-                    param_name = dir_name[1:-1]
-                    if param_name.startswith('...'):
-                        # Catch-all route
-                        new_path = f"{url_path}/[...{param_name[3:]}]"
-                    else:
-                        new_path = f"{url_path}/[{param_name}]"
-                    self._scan_directory(item, new_path)
-                elif dir_name == 'api':
-                    # API routes - scan but mark differently
-                    self._scan_api_directory(item, '/api')
-                else:
-                    new_path = f"{url_path}/{dir_name}"
-                    self._scan_directory(item, new_path)
-
-            elif item.is_file():
-                self._process_file(item, url_path)
-
-    def _process_file(self, file_path: Path, url_path: str):
-        """Process a potential page file"""
-        if file_path.name not in self.PAGE_PATTERNS:
-            return
-
-        # Skip if it's a layout or other special file
-        if any(x in file_path.name for x in ['layout', 'loading', 'error', 'template']):
-            return
-
-        try:
-            content = file_path.read_text(encoding='utf-8')
-        except Exception:
-            return
-
-        # Determine route path
-        if url_path == '':
-            route_path = '/'
-        else:
-            route_path = url_path
-
-        # Detect dynamic parameters
-        params = re.findall(r'\[([^\]]+)\]', route_path)
-        has_params = len(params) > 0
-
-        # Detect features
-        has_form = any(re.search(p, content) for p in self.FORM_PATTERNS)
-        has_auth = any(re.search(p, content, re.IGNORECASE) for p in self.AUTH_PATTERNS)
-
-        # Detect interactions
-        interactions = []
-        for interaction, pattern in self.INTERACTION_PATTERNS.items():
-            if re.search(pattern, content):
-                interactions.append(interaction)
-
-        route = RouteInfo(
-            path=route_path,
-            file_path=str(file_path),
-            route_type='dynamic' if has_params else 'page',
-            has_params=has_params,
-            params=params,
-            has_form=has_form,
-            has_auth=has_auth,
-            interactions=interactions
-        )
-
-        self.routes.append(route)
-
-        if self.verbose:
-            print(f"  Found route: {route_path}")
-
-    def _scan_api_directory(self, directory: Path, url_path: str):
-        """Scan API routes (mark them differently)"""
-        for item in directory.iterdir():
-            if item.is_dir():
-                new_path = f"{url_path}/{item.name}"
-                self._scan_api_directory(item, new_path)
-            elif item.is_file() and item.suffix in {'.ts', '.tsx', '.js', '.jsx'}:
-                # API routes don't get E2E tests typically
-                pass
-
-
-class TestGenerator:
-    """Generates Playwright test files"""
-
-    def __init__(self, include_pom: bool = False, verbose: bool = False):
-        self.include_pom = include_pom
-        self.verbose = verbose
-
-    def generate(self, route: RouteInfo) -> str:
-        """Generate a test file for a route"""
-        lines = []
-
-        # Imports
-        lines.append("import { test, expect } from '@playwright/test';")
-
-        if self.include_pom:
-            page_class = self._get_page_class_name(route.path)
-            lines.append(f"import {{ {page_class} }} from './pages/{page_class}';")
-
-        lines.append('')
-
-        # Test describe block
-        route_name = route.path if route.path != '/' else 'Home'
-        lines.append(f"test.describe('{route_name}', () => {{")
-
-        # Generate test cases based on route features
-        test_cases = self._generate_test_cases(route)
-
-        for test_case in test_cases:
-            lines.append('')
-            lines.append(test_case)
-
-        lines.append('});')
-        lines.append('')
-
-        return '\n'.join(lines)
-
-    def _generate_test_cases(self, route: RouteInfo) -> List[str]:
-        """Generate test cases based on route features"""
-        cases = []
-        url = self._get_test_url(route)
-
-        # Basic navigation test
-        cases.append(f'''  test('loads successfully', async ({{ page }}) => {{
-    await page.goto('{url}');
-    await expect(page).toHaveURL(/{re.escape(route.path.replace('[', '').replace(']', '.*'))}/);
-    // TODO: Add specific content assertions
-  }});''')
-
-        # Page title test
-        cases.append(f'''  test('has correct title', async ({{ page }}) => {{
-    await page.goto('{url}');
-    // TODO: Update expected title
-    await expect(page).toHaveTitle(/.*/);
-  }});''')
-
-        # Auth-related tests
-        if route.has_auth:
-            cases.append(f'''  test('redirects unauthenticated users', async ({{ page }}) => {{
-    await page.goto('{url}');
-    // TODO: Verify redirect to login
-    // await expect(page).toHaveURL('/login');
-  }});
-
-  test('allows authenticated access', async ({{ page }}) => {{
-    // TODO: Set up authentication
-    // await page.context().addCookies([{{ name: 'session', value: '...' }}]);
-    await page.goto('{url}');
-    await expect(page).toHaveURL(/{re.escape(route.path.replace('[', '').replace(']', '.*'))}/);
-  }});''')
-
-        # Form tests
-        if route.has_form:
-            cases.append(f'''  test('form submission works', async ({{ page }}) => {{
-    await page.goto('{url}');
-
-    // TODO: Fill in form fields
-    // await page.getByLabel('Email').fill('test@example.com');
-    // await page.getByLabel('Password').fill('password123');
-
-    // Submit form
-    // await page.getByRole('button', {{ name: 'Submit' }}).click();
-
-    // TODO: Assert success state
-    // await expect(page.getByText('Success')).toBeVisible();
-  }});
-
-  test('shows validation errors', async ({{ page }}) => {{
-    await page.goto('{url}');
-
-    // Submit without filling required fields
-    await page.getByRole('button', {{ name: /submit/i }}).click();
-
-    // TODO: Assert validation errors shown
-    // await expect(page.getByText('Required')).toBeVisible();
-  }});''')
-
-        # Click interaction tests
-        if 'click' in route.interactions:
-            cases.append(f'''  test('button interactions work', async ({{ page }}) => {{
-    await page.goto('{url}');
-
-    // TODO: Find and click interactive elements
-    // const button = page.getByRole('button', {{ name: '...' }});
-    // await button.click();
-    // await expect(page.getByText('...')).toBeVisible();
-  }});''')
-
-        # Navigation tests
-        if 'navigation' in route.interactions:
-            cases.append(f'''  test('navigation works correctly', async ({{ page }}) => {{
-    await page.goto('{url}');
-
-    // TODO: Click navigation links
-    // await page.getByRole('link', {{ name: '...' }}).click();
-    // await expect(page).toHaveURL('...');
-  }});''')
-
-        # Modal tests
-        if 'modal' in route.interactions:
-            cases.append(f'''  test('modal opens and closes', async ({{ page }}) => {{
-    await page.goto('{url}');
-
-    // TODO: Open modal
-    // await page.getByRole('button', {{ name: 'Open' }}).click();
-    // await expect(page.getByRole('dialog')).toBeVisible();
-
-    // TODO: Close modal
-    // await page.getByRole('button', {{ name: 'Close' }}).click();
-    // await expect(page.getByRole('dialog')).not.toBeVisible();
-  }});''')
-
-        # Dynamic route test
-        if route.has_params:
-            cases.append(f'''  test('handles dynamic parameters', async ({{ page }}) => {{
-    // TODO: Test with different parameter values
-    await page.goto('{url}');
-    await expect(page.locator('body')).toBeVisible();
-  }});''')
-
-        return cases
-
-    def _get_test_url(self, route: RouteInfo) -> str:
-        """Get a testable URL for the route"""
-        url = route.path
-
-        # Replace dynamic segments with example values
-        for param in route.params:
-            if param.startswith('...'):
-                url = url.replace(f'[...{param[3:]}]', 'example/path')
-            else:
-                url = url.replace(f'[{param}]', 'test-id')
-
-        return url
-
-    def _get_page_class_name(self, route_path: str) -> str:
-        """Get Page Object class name from route path"""
-        if route_path == '/':
-            return 'HomePage'
-
-        # Remove leading slash and convert to PascalCase
-        name = route_path.strip('/')
-        name = re.sub(r'\[.*?\]', '', name)  # Remove dynamic segments
-        parts = name.split('/')
-        return ''.join(p.title() for p in parts if p) + 'Page'
-
-
-class PageObjectGenerator:
-    """Generates Page Object Model classes"""
-
-    def __init__(self, verbose: bool = False):
-        self.verbose = verbose
-
-    def generate(self, route: RouteInfo) -> str:
-        """Generate a Page Object class for a route"""
-        class_name = self._get_class_name(route.path)
-        url = route.path
-
-        # Replace dynamic segments
-        for param in route.params:
-            url = url.replace(f'[{param}]', f'${{{param}}}')
-
-        lines = []
-
-        # Imports
-        lines.append("import { Page, Locator, expect } from '@playwright/test';")
-        lines.append('')
-
-        # Class definition
-        lines.append(f"export class {class_name} {{")
-        lines.append("  readonly page: Page;")
-
-        # Common locators
-        locators = self._get_locators(route)
-        for name, selector, _ in locators:
-            lines.append(f"  readonly {name}: Locator;")
-
-        lines.append('')
-
-        # Constructor
-        lines.append("  constructor(page: Page) {")
-        lines.append("    this.page = page;")
-        for name, selector, _ in locators:
-            lines.append(f"    this.{name} = page.{selector};")
-        lines.append("  }")
-        lines.append('')
-
-        # Navigation method
-        if route.has_params:
-            param_args = ', '.join(f'{p}: string' for p in route.params)
-            url_parts = url.split('/')
-            url_template = '/'.join(
-                f'${{{p}}}' if f'${{{p}}}' in part else part
-                for p, part in zip(route.params, url_parts)
-            )
-            lines.append(f"  async goto({param_args}) {{")
-            lines.append(f"    await this.page.goto(`{url_template}`);")
-        else:
-            lines.append("  async goto() {")
-            lines.append(f"    await this.page.goto('{route.path}');")
-        lines.append("  }")
-        lines.append('')
-
-        # Add methods based on features
-        methods = self._get_methods(route, locators)
-        for method_name, method_code in methods:
-            lines.append(method_code)
-            lines.append('')
-
-        lines.append('}')
-        lines.append('')
-
-        return '\n'.join(lines)
-
-    def _get_class_name(self, route_path: str) -> str:
-        """Get class name from route path"""
-        if route_path == '/':
-            return 'HomePage'
-
-        name = route_path.strip('/')
-        name = re.sub(r'\[.*?\]', '', name)
-        parts = name.split('/')
-        return ''.join(p.title() for p in parts if p) + 'Page'
-
-    def _get_locators(self, route: RouteInfo) -> List[Tuple[str, str, str]]:
-        """Get common locators for a page"""
-        locators = []
-
-        # Always add a heading locator
-        locators.append(('heading', "getByRole('heading', { level: 1 })", 'Main heading'))
-
-        if route.has_form:
-            locators.extend([
-                ('submitButton', "getByRole('button', { name: /submit/i })", 'Form submit button'),
-                ('form', "locator('form')", 'Main form element'),
-            ])
-
-        if route.has_auth:
-            locators.extend([
-                ('emailInput', "getByLabel('Email')", 'Email input field'),
-                ('passwordInput', "getByLabel('Password')", 'Password input field'),
-            ])
-
-        if 'navigation' in route.interactions:
-            locators.append(('navLinks', "getByRole('navigation').getByRole('link')", 'Navigation links'))
-
-        if 'modal' in route.interactions:
-            locators.append(('modal', "getByRole('dialog')", 'Modal dialog'))
-
-        return locators
-
-    def _get_methods(
-        self,
-        route: RouteInfo,
-        locators: List[Tuple[str, str, str]]
-    ) -> List[Tuple[str, str]]:
-        """Get methods for the page object"""
-        methods = []
-
-        # Wait for load method
-        methods.append(('waitForLoad', '''  async waitForLoad() {
-    await expect(this.heading).toBeVisible();
-  }'''))
-
-        if route.has_form:
-            methods.append(('submitForm', '''  async submitForm() {
-    await this.submitButton.click();
-  }'''))
-
-        if route.has_auth:
-            methods.append(('login', '''  async login(email: string, password: string) {
-    await this.emailInput.fill(email);
-    await this.passwordInput.fill(password);
-    await this.submitButton.click();
-  }'''))
-
-        if 'modal' in route.interactions:
-            methods.append(('waitForModal', '''  async waitForModal() {
-    await expect(this.modal).toBeVisible();
-  }'''))
-            methods.append(('closeModal', '''  async closeModal() {
-    await this.page.keyboard.press('Escape');
-    await expect(this.modal).not.toBeVisible();
-  }'''))
-
-        return methods
-
-
-class ConfigGenerator:
-    """Generates Playwright configuration"""
-
-    def generate_config(self) -> str:
-        """Generate playwright.config.ts"""
-        return '''import { defineConfig, devices } from '@playwright/test';
-
-/**
- * Playwright Test Configuration
- * @see https://playwright.dev/docs/test-configuration
- */
-export default defineConfig({
-  testDir: './e2e',
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: [
-    ['html', { open: 'never' }],
-    ['list'],
-  ],
-  use: {
-    baseURL: process.env.BASE_URL || 'http://localhost:3000',
-    trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
-  },
-  projects: [
-    {
-      name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
-    },
-    {
-      name: 'firefox',
-      use: { ...devices['Desktop Firefox'] },
-    },
-    {
-      name: 'webkit',
-      use: { ...devices['Desktop Safari'] },
-    },
-    {
-      name: 'Mobile Chrome',
-      use: { ...devices['Pixel 5'] },
-    },
-  ],
-  webServer: {
-    command: 'npm run dev',
-    url: 'http://localhost:3000',
-    reuseExistingServer: !process.env.CI,
-    timeout: 120 * 1000,
-  },
-});
-'''
-
-    def generate_auth_fixture(self) -> str:
-        """Generate authentication fixture"""
-        return '''import { test as base, Page } from '@playwright/test';
-
-interface AuthFixtures {
-  authenticatedPage: Page;
-}
-
-export const test = base.extend<AuthFixtures>({
-  authenticatedPage: async ({ page }, use) => {
-    // Option 1: Login via UI
-    // await page.goto('/login');
-    // await page.getByLabel('Email').fill(process.env.TEST_EMAIL || 'test@example.com');
-    // await page.getByLabel('Password').fill(process.env.TEST_PASSWORD || 'password');
-    // await page.getByRole('button', { name: 'Sign in' }).click();
-    // await page.waitForURL('/dashboard');
-
-    // Option 2: Login via API
-    // const response = await page.request.post('/api/auth/login', {
-    //   data: {
-    //     email: process.env.TEST_EMAIL,
-    //     password: process.env.TEST_PASSWORD,
-    //   },
-    // });
-    // const { token } = await response.json();
-    // await page.context().addCookies([
-    //   { name: 'auth-token', value: token, domain: 'localhost', path: '/' }
-    // ]);
-
-    await use(page);
-  },
-});
-
-export { expect } from '@playwright/test';
-'''
-
-
-class E2ETestScaffolder:
-    """Main scaffolder class"""
-
-    def __init__(
-        self,
-        source_path: str,
-        output_path: Optional[str] = None,
-        include_pom: bool = False,
-        routes: Optional[str] = None,
-        verbose: bool = False
-    ):
-        self.source_path = Path(source_path)
-        self.output_path = Path(output_path) if output_path else Path('e2e')
-        self.include_pom = include_pom
-        self.routes_filter = routes.split(',') if routes else None
-        self.verbose = verbose
-        self.results = {
-            'status': 'success',
-            'source': str(self.source_path),
-            'routes': [],
-            'generated_files': [],
-            'summary': {}
-        }
-
-    def run(self) -> Dict:
-        """Run the scaffolder"""
-        print(f"Scanning: {self.source_path}")
-
-        # Validate source path
-        if not self.source_path.exists():
-            raise ValueError(f"Source path does not exist: {self.source_path}")
-
-        # Scan for routes
-        scanner = RouteScanner(self.source_path, self.verbose)
-        routes = scanner.scan(self.routes_filter)
-
-        print(f"Found {len(routes)} routes")
-
-        # Create output directories
-        self.output_path.mkdir(parents=True, exist_ok=True)
-        if self.include_pom:
-            (self.output_path / 'pages').mkdir(exist_ok=True)
-
-        # Generate test files
-        test_generator = TestGenerator(self.include_pom, self.verbose)
-        pom_generator = PageObjectGenerator(self.verbose) if self.include_pom else None
-        config_generator = ConfigGenerator()
-
-        # Generate tests for each route
-        for route in routes:
-            # Generate test file
-            test_content = test_generator.generate(route)
-            test_filename = self._get_test_filename(route.path)
-            test_path = self.output_path / test_filename
-
-            test_path.write_text(test_content, encoding='utf-8')
-
-            self.results['generated_files'].append({
-                'type': 'test',
-                'route': route.path,
-                'path': str(test_path)
-            })
-
-            print(f"  {test_filename}")
-
-            # Generate Page Object if enabled
-            if self.include_pom:
-                pom_content = pom_generator.generate(route)
-                pom_filename = self._get_pom_filename(route.path)
-                pom_path = self.output_path / 'pages' / pom_filename
-
-                pom_path.write_text(pom_content, encoding='utf-8')
-
-                self.results['generated_files'].append({
-                    'type': 'page_object',
-                    'route': route.path,
-                    'path': str(pom_path)
-                })
-
-                print(f"  pages/{pom_filename}")
-
-        # Generate config files if not exists
-        config_path = Path('playwright.config.ts')
-        if not config_path.exists():
-            config_content = config_generator.generate_config()
-            config_path.write_text(config_content, encoding='utf-8')
-            self.results['generated_files'].append({
-                'type': 'config',
-                'path': str(config_path)
-            })
-            print(f"  playwright.config.ts")
-
-        # Generate auth fixture
-        fixtures_dir = self.output_path / 'fixtures'
-        fixtures_dir.mkdir(exist_ok=True)
-        auth_fixture_path = fixtures_dir / 'auth.ts'
-        if not auth_fixture_path.exists():
-            auth_content = config_generator.generate_auth_fixture()
-            auth_fixture_path.write_text(auth_content, encoding='utf-8')
-            self.results['generated_files'].append({
-                'type': 'fixture',
-                'path': str(auth_fixture_path)
-            })
-            print(f"  fixtures/auth.ts")
-
-        # Store route info
-        self.results['routes'] = [asdict(r) for r in routes]
-
-        # Summary
-        self.results['summary'] = {
-            'total_routes': len(routes),
-            'total_files': len(self.results['generated_files']),
-            'output_directory': str(self.output_path),
-            'include_pom': self.include_pom
-        }
-
-        print('')
-        print(f"Summary: {len(routes)} routes, {len(self.results['generated_files'])} files generated")
-
-        return self.results
-
-    def _get_test_filename(self, route_path: str) -> str:
-        """Get test filename from route path"""
-        if route_path == '/':
-            return 'home.spec.ts'
-
-        name = route_path.strip('/')
-        name = re.sub(r'\[([^\]]+)\]', r'\1', name)  # [id] -> id
-        name = name.replace('/', '-')
-        return f"{name}.spec.ts"
-
-    def _get_pom_filename(self, route_path: str) -> str:
-        """Get Page Object filename from route path"""
-        if route_path == '/':
-            return 'HomePage.ts'
-
-        name = route_path.strip('/')
-        name = re.sub(r'\[.*?\]', '', name)
-        parts = name.split('/')
-        class_name = ''.join(p.title() for p in parts if p) + 'Page'
-        return f"{class_name}.ts"
-
-
-def main():
-    """Main entry point"""
-    parser = argparse.ArgumentParser(
-        description="Generate Playwright E2E tests from Next.js routes",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  # Scaffold E2E tests for App Router
-  python e2e_test_scaffolder.py src/app/ --output e2e/
-
-  # Include Page Object Models
-  python e2e_test_scaffolder.py src/app/ --include-pom
-
-  # Generate for specific routes only
-  python e2e_test_scaffolder.py src/app/ --routes "/login,/dashboard,/checkout"
-
-  # Verbose output
-  python e2e_test_scaffolder.py pages/ -v
-        """
-    )
-    parser.add_argument(
-        'source',
-        help='Source directory (app/ or pages/)'
-    )
-    parser.add_argument(
-        '--output', '-o',
-        default='e2e',
-        help='Output directory for test files (default: e2e/)'
-    )
-    parser.add_argument(
-        '--include-pom',
-        action='store_true',
-        help='Generate Page Object Model classes'
-    )
-    parser.add_argument(
-        '--routes',
-        help='Comma-separated list of routes to generate tests for'
-    )
-    parser.add_argument(
-        '--verbose', '-v',
-        action='store_true',
-        help='Enable verbose output'
-    )
-    parser.add_argument(
-        '--json',
-        action='store_true',
-        help='Output results as JSON'
-    )
-
-    args = parser.parse_args()
-
-    try:
-        scaffolder = E2ETestScaffolder(
-            source_path=args.source,
-            output_path=args.output,
-            include_pom=args.include_pom,
-            routes=args.routes,
-            verbose=args.verbose
-        )
-
-        results = scaffolder.run()
-
-        if args.json:
-            print(json.dumps(results, indent=2))
-
-    except Exception as e:
-        print(f"Error: {e}")
-        sys.exit(1)
-
-
-if __name__ == '__main__':
-    main()
+#!/usr/bin/env python3
+"""
+E2E Test Scaffolder
+
+Scans Next.js pages/app directory and generates Playwright test files
+with common interactions, Page Object Model classes, and configuration.
+
+Usage:
+    python e2e_test_scaffolder.py src/app/ --output e2e/
+    python e2e_test_scaffolder.py pages/ --include-pom --routes "/login,/dashboard"
+"""
+
+import os
+import sys
+import json
+import argparse
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Set
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+
+
+@dataclass
+class RouteInfo:
+    """Information about a detected route"""
+    path: str  # URL path e.g., /dashboard
+    file_path: str  # File system path
+    route_type: str  # 'page', 'layout', 'api', 'dynamic'
+    has_params: bool
+    params: List[str]
+    has_form: bool
+    has_auth: bool
+    interactions: List[str]
+
+
+@dataclass
+class TestSpec:
+    """A Playwright test specification"""
+    route: RouteInfo
+    test_cases: List[str]
+    imports: Set[str] = field(default_factory=set)
+
+
+@dataclass
+class PageObject:
+    """Page Object Model class definition"""
+    name: str
+    route: str
+    locators: List[Tuple[str, str, str]]  # (name, selector, description)
+    methods: List[Tuple[str, str]]  # (name, code)
+
+
+class RouteScanner:
+    """Scans Next.js directories for routes"""
+
+    # Pattern to detect page files
+    PAGE_PATTERNS = {
+        'page.tsx', 'page.ts', 'page.jsx', 'page.js',  # App Router
+        'index.tsx', 'index.ts', 'index.jsx', 'index.js'  # Pages Router
+    }
+
+    # Patterns indicating specific features
+    FORM_PATTERNS = [
+        r'<form', r'handleSubmit', r'onSubmit', r'useForm',
+        r'<input', r'<textarea', r'<select'
+    ]
+
+    AUTH_PATTERNS = [
+        r'auth', r'login', r'signin', r'signup', r'register',
+        r'useAuth', r'useSession', r'getServerSession', r'withAuth'
+    ]
+
+    INTERACTION_PATTERNS = {
+        'click': r'onClick|button|Button|<a\s|Link',
+        'type': r'<input|<textarea|onChange',
+        'select': r'<select|Dropdown|Select',
+        'navigation': r'useRouter|router\.push|Link',
+        'modal': r'Modal|Dialog|isOpen|onClose',
+        'toggle': r'toggle|Switch|Checkbox',
+        'upload': r'<input.*type=["\']file|upload|dropzone'
+    }
+
+    def __init__(self, source_path: Path, verbose: bool = False):
+        self.source_path = source_path
+        self.verbose = verbose
+        self.routes: List[RouteInfo] = []
+        self.is_app_router = self._detect_router_type()
+
+    def _detect_router_type(self) -> bool:
+        """Detect if using App Router or Pages Router"""
+        # App Router: has 'app' directory with page.tsx files
+        # Pages Router: has 'pages' directory with index.tsx files
+        app_dir = self.source_path / 'app'
+        if app_dir.exists() and list(app_dir.rglob('page.*')):
+            return True
+
+        return 'app' in str(self.source_path).lower()
+
+    def scan(self, filter_routes: Optional[List[str]] = None) -> List[RouteInfo]:
+        """Scan for all routes"""
+        self._scan_directory(self.source_path)
+
+        # Filter if specific routes requested
+        if filter_routes:
+            self.routes = [
+                r for r in self.routes
+                if any(fr in r.path for fr in filter_routes)
+            ]
+
+        return self.routes
+
+    def _scan_directory(self, directory: Path, url_path: str = ''):
+        """Recursively scan directory for routes"""
+        if not directory.exists():
+            return
+
+        for item in directory.iterdir():
+            if item.name.startswith('.') or item.name == 'node_modules':
+                continue
+
+            if item.is_dir():
+                # Handle route groups (parentheses) and dynamic routes
+                dir_name = item.name
+
+                if dir_name.startswith('(') and dir_name.endswith(')'):
+                    # Route group - doesn't add to URL path
+                    self._scan_directory(item, url_path)
+                elif dir_name.startswith('[') and dir_name.endswith(']'):
+                    # Dynamic route
+                    param_name = dir_name[1:-1]
+                    if param_name.startswith('...'):
+                        # Catch-all route
+                        new_path = f"{url_path}/[...{param_name[3:]}]"
+                    else:
+                        new_path = f"{url_path}/[{param_name}]"
+                    self._scan_directory(item, new_path)
+                elif dir_name == 'api':
+                    # API routes - scan but mark differently
+                    self._scan_api_directory(item, '/api')
+                else:
+                    new_path = f"{url_path}/{dir_name}"
+                    self._scan_directory(item, new_path)
+
+            elif item.is_file():
+                self._process_file(item, url_path)
+
+    def _process_file(self, file_path: Path, url_path: str):
+        """Process a potential page file"""
+        if file_path.name not in self.PAGE_PATTERNS:
+            return
+
+        # Skip if it's a layout or other special file
+        if any(x in file_path.name for x in ['layout', 'loading', 'error', 'template']):
+            return
+
+        try:
+            content = file_path.read_text(encoding='utf-8')
+        except Exception:
+            return
+
+        # Determine route path
+        if url_path == '':
+            route_path = '/'
+        else:
+            route_path = url_path
+
+        # Detect dynamic parameters
+        params = re.findall(r'\[([^\]]+)\]', route_path)
+        has_params = len(params) > 0
+
+        # Detect features
+        has_form = any(re.search(p, content) for p in self.FORM_PATTERNS)
+        has_auth = any(re.search(p, content, re.IGNORECASE) for p in self.AUTH_PATTERNS)
+
+        # Detect interactions
+        interactions = []
+        for interaction, pattern in self.INTERACTION_PATTERNS.items():
+            if re.search(pattern, content):
+                interactions.append(interaction)
+
+        route = RouteInfo(
+            path=route_path,
+            file_path=str(file_path),
+            route_type='dynamic' if has_params else 'page',
+            has_params=has_params,
+            params=params,
+            has_form=has_form,
+            has_auth=has_auth,
+            interactions=interactions
+        )
+
+        self.routes.append(route)
+
+        if self.verbose:
+            print(f"  Found route: {route_path}")
+
+    def _scan_api_directory(self, directory: Path, url_path: str):
+        """Scan API routes (mark them differently)"""
+        for item in directory.iterdir():
+            if item.is_dir():
+                new_path = f"{url_path}/{item.name}"
+                self._scan_api_directory(item, new_path)
+            elif item.is_file() and item.suffix in {'.ts', '.tsx', '.js', '.jsx'}:
+                # API routes don't get E2E tests typically
+                pass
+
+
+class TestGenerator:
+    """Generates Playwright test files"""
+
+    def __init__(self, include_pom: bool = False, verbose: bool = False):
+        self.include_pom = include_pom
+        self.verbose = verbose
+
+    def generate(self, route: RouteInfo) -> str:
+        """Generate a test file for a route"""
+        lines = []
+
+        # Imports
+        lines.append("import { test, expect } from '@playwright/test';")
+
+        if self.include_pom:
+            page_class = self._get_page_class_name(route.path)
+            lines.append(f"import {{ {page_class} }} from './pages/{page_class}';")
+
+        lines.append('')
+
+        # Test describe block
+        route_name = route.path if route.path != '/' else 'Home'
+        lines.append(f"test.describe('{route_name}', () => {{")
+
+        # Generate test cases based on route features
+        test_cases = self._generate_test_cases(route)
+
+        for test_case in test_cases:
+            lines.append('')
+            lines.append(test_case)
+
+        lines.append('});')
+        lines.append('')
+
+        return '\n'.join(lines)
+
+    def _generate_test_cases(self, route: RouteInfo) -> List[str]:
+        """Generate test cases based on route features"""
+        cases = []
+        url = self._get_test_url(route)
+
+        # Basic navigation test
+        cases.append(f'''  test('loads successfully', async ({{ page }}) => {{
+    await page.goto('{url}');
+    await expect(page).toHaveURL(/{re.escape(route.path.replace('[', '').replace(']', '.*'))}/);
+    // TODO: Add specific content assertions
+  }});''')
+
+        # Page title test
+        cases.append(f'''  test('has correct title', async ({{ page }}) => {{
+    await page.goto('{url}');
+    // TODO: Update expected title
+    await expect(page).toHaveTitle(/.*/);
+  }});''')
+
+        # Auth-related tests
+        if route.has_auth:
+            cases.append(f'''  test('redirects unauthenticated users', async ({{ page }}) => {{
+    await page.goto('{url}');
+    // TODO: Verify redirect to login
+    // await expect(page).toHaveURL('/login');
+  }});
+
+  test('allows authenticated access', async ({{ page }}) => {{
+    // TODO: Set up authentication
+    // await page.context().addCookies([{{ name: 'session', value: '...' }}]);
+    await page.goto('{url}');
+    await expect(page).toHaveURL(/{re.escape(route.path.replace('[', '').replace(']', '.*'))}/);
+  }});''')
+
+        # Form tests
+        if route.has_form:
+            cases.append(f'''  test('form submission works', async ({{ page }}) => {{
+    await page.goto('{url}');
+
+    // TODO: Fill in form fields
+    // await page.getByLabel('Email').fill('test@example.com');
+    // await page.getByLabel('Password').fill('password123');
+
+    // Submit form
+    // await page.getByRole('button', {{ name: 'Submit' }}).click();
+
+    // TODO: Assert success state
+    // await expect(page.getByText('Success')).toBeVisible();
+  }});
+
+  test('shows validation errors', async ({{ page }}) => {{
+    await page.goto('{url}');
+
+    // Submit without filling required fields
+    await page.getByRole('button', {{ name: /submit/i }}).click();
+
+    // TODO: Assert validation errors shown
+    // await expect(page.getByText('Required')).toBeVisible();
+  }});''')
+
+        # Click interaction tests
+        if 'click' in route.interactions:
+            cases.append(f'''  test('button interactions work', async ({{ page }}) => {{
+    await page.goto('{url}');
+
+    // TODO: Find and click interactive elements
+    // const button = page.getByRole('button', {{ name: '...' }});
+    // await button.click();
+    // await expect(page.getByText('...')).toBeVisible();
+  }});''')
+
+        # Navigation tests
+        if 'navigation' in route.interactions:
+            cases.append(f'''  test('navigation works correctly', async ({{ page }}) => {{
+    await page.goto('{url}');
+
+    // TODO: Click navigation links
+    // await page.getByRole('link', {{ name: '...' }}).click();
+    // await expect(page).toHaveURL('...');
+  }});''')
+
+        # Modal tests
+        if 'modal' in route.interactions:
+            cases.append(f'''  test('modal opens and closes', async ({{ page }}) => {{
+    await page.goto('{url}');
+
+    // TODO: Open modal
+    // await page.getByRole('button', {{ name: 'Open' }}).click();
+    // await expect(page.getByRole('dialog')).toBeVisible();
+
+    // TODO: Close modal
+    // await page.getByRole('button', {{ name: 'Close' }}).click();
+    // await expect(page.getByRole('dialog')).not.toBeVisible();
+  }});''')
+
+        # Dynamic route test
+        if route.has_params:
+            cases.append(f'''  test('handles dynamic parameters', async ({{ page }}) => {{
+    // TODO: Test with different parameter values
+    await page.goto('{url}');
+    await expect(page.locator('body')).toBeVisible();
+  }});''')
+
+        return cases
+
+    def _get_test_url(self, route: RouteInfo) -> str:
+        """Get a testable URL for the route"""
+        url = route.path
+
+        # Replace dynamic segments with example values
+        for param in route.params:
+            if param.startswith('...'):
+                url = url.replace(f'[...{param[3:]}]', 'example/path')
+            else:
+                url = url.replace(f'[{param}]', 'test-id')
+
+        return url
+
+    def _get_page_class_name(self, route_path: str) -> str:
+        """Get Page Object class name from route path"""
+        if route_path == '/':
+            return 'HomePage'
+
+        # Remove leading slash and convert to PascalCase
+        name = route_path.strip('/')
+        name = re.sub(r'\[.*?\]', '', name)  # Remove dynamic segments
+        parts = name.split('/')
+        return ''.join(p.title() for p in parts if p) + 'Page'
+
+
+class PageObjectGenerator:
+    """Generates Page Object Model classes"""
+
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+
+    def generate(self, route: RouteInfo) -> str:
+        """Generate a Page Object class for a route"""
+        class_name = self._get_class_name(route.path)
+        url = route.path
+
+        # Replace dynamic segments
+        for param in route.params:
+            url = url.replace(f'[{param}]', f'${{{param}}}')
+
+        lines = []
+
+        # Imports
+        lines.append("import { Page, Locator, expect } from '@playwright/test';")
+        lines.append('')
+
+        # Class definition
+        lines.append(f"export class {class_name} {{")
+        lines.append("  readonly page: Page;")
+
+        # Common locators
+        locators = self._get_locators(route)
+        for name, selector, _ in locators:
+            lines.append(f"  readonly {name}: Locator;")
+
+        lines.append('')
+
+        # Constructor
+        lines.append("  constructor(page: Page) {")
+        lines.append("    this.page = page;")
+        for name, selector, _ in locators:
+            lines.append(f"    this.{name} = page.{selector};")
+        lines.append("  }")
+        lines.append('')
+
+        # Navigation method
+        if route.has_params:
+            param_args = ', '.join(f'{p}: string' for p in route.params)
+            url_parts = url.split('/')
+            url_template = '/'.join(
+                f'${{{p}}}' if f'${{{p}}}' in part else part
+                for p, part in zip(route.params, url_parts)
+            )
+            lines.append(f"  async goto({param_args}) {{")
+            lines.append(f"    await this.page.goto(`{url_template}`);")
+        else:
+            lines.append("  async goto() {")
+            lines.append(f"    await this.page.goto('{route.path}');")
+        lines.append("  }")
+        lines.append('')
+
+        # Add methods based on features
+        methods = self._get_methods(route, locators)
+        for method_name, method_code in methods:
+            lines.append(method_code)
+            lines.append('')
+
+        lines.append('}')
+        lines.append('')
+
+        return '\n'.join(lines)
+
+    def _get_class_name(self, route_path: str) -> str:
+        """Get class name from route path"""
+        if route_path == '/':
+            return 'HomePage'
+
+        name = route_path.strip('/')
+        name = re.sub(r'\[.*?\]', '', name)
+        parts = name.split('/')
+        return ''.join(p.title() for p in parts if p) + 'Page'
+
+    def _get_locators(self, route: RouteInfo) -> List[Tuple[str, str, str]]:
+        """Get common locators for a page"""
+        locators = []
+
+        # Always add a heading locator
+        locators.append(('heading', "getByRole('heading', { level: 1 })", 'Main heading'))
+
+        if route.has_form:
+            locators.extend([
+                ('submitButton', "getByRole('button', { name: /submit/i })", 'Form submit button'),
+                ('form', "locator('form')", 'Main form element'),
+            ])
+
+        if route.has_auth:
+            locators.extend([
+                ('emailInput', "getByLabel('Email')", 'Email input field'),
+                ('passwordInput', "getByLabel('Password')", 'Password input field'),
+            ])
+
+        if 'navigation' in route.interactions:
+            locators.append(('navLinks', "getByRole('navigation').getByRole('link')", 'Navigation links'))
+
+        if 'modal' in route.interactions:
+            locators.append(('modal', "getByRole('dialog')", 'Modal dialog'))
+
+        return locators
+
+    def _get_methods(
+        self,
+        route: RouteInfo,
+        locators: List[Tuple[str, str, str]]
+    ) -> List[Tuple[str, str]]:
+        """Get methods for the page object"""
+        methods = []
+
+        # Wait for load method
+        methods.append(('waitForLoad', '''  async waitForLoad() {
+    await expect(this.heading).toBeVisible();
+  }'''))
+
+        if route.has_form:
+            methods.append(('submitForm', '''  async submitForm() {
+    await this.submitButton.click();
+  }'''))
+
+        if route.has_auth:
+            methods.append(('login', '''  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }'''))
+
+        if 'modal' in route.interactions:
+            methods.append(('waitForModal', '''  async waitForModal() {
+    await expect(this.modal).toBeVisible();
+  }'''))
+            methods.append(('closeModal', '''  async closeModal() {
+    await this.page.keyboard.press('Escape');
+    await expect(this.modal).not.toBeVisible();
+  }'''))
+
+        return methods
+
+
+class ConfigGenerator:
+    """Generates Playwright configuration"""
+
+    def generate_config(self) -> str:
+        """Generate playwright.config.ts"""
+        return '''import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Playwright Test Configuration
+ * @see https://playwright.dev/docs/test-configuration
+ */
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { open: 'never' }],
+    ['list'],
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'Mobile Chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120 * 1000,
+  },
+});
+'''
+
+    def generate_auth_fixture(self) -> str:
+        """Generate authentication fixture"""
+        return '''import { test as base, Page } from '@playwright/test';
+
+interface AuthFixtures {
+  authenticatedPage: Page;
+}
+
+export const test = base.extend<AuthFixtures>({
+  authenticatedPage: async ({ page }, use) => {
+    // Option 1: Login via UI
+    // await page.goto('/login');
+    // await page.getByLabel('Email').fill(process.env.TEST_EMAIL || 'test@example.com');
+    // await page.getByLabel('Password').fill(process.env.TEST_PASSWORD || 'password');
+    // await page.getByRole('button', { name: 'Sign in' }).click();
+    // await page.waitForURL('/dashboard');
+
+    // Option 2: Login via API
+    // const response = await page.request.post('/api/auth/login', {
+    //   data: {
+    //     email: process.env.TEST_EMAIL,
+    //     password: process.env.TEST_PASSWORD,
+    //   },
+    // });
+    // const { token } = await response.json();
+    // await page.context().addCookies([
+    //   { name: 'auth-token', value: token, domain: 'localhost', path: '/' }
+    // ]);
+
+    await use(page);
+  },
+});
+
+export { expect } from '@playwright/test';
+'''
+
+
+class E2ETestScaffolder:
+    """Main scaffolder class"""
+
+    def __init__(
+        self,
+        source_path: str,
+        output_path: Optional[str] = None,
+        include_pom: bool = False,
+        routes: Optional[str] = None,
+        verbose: bool = False
+    ):
+        self.source_path = Path(source_path)
+        self.output_path = Path(output_path) if output_path else Path('e2e')
+        self.include_pom = include_pom
+        self.routes_filter = routes.split(',') if routes else None
+        self.verbose = verbose
+        self.results = {
+            'status': 'success',
+            'source': str(self.source_path),
+            'routes': [],
+            'generated_files': [],
+            'summary': {}
+        }
+
+    def run(self) -> Dict:
+        """Run the scaffolder"""
+        print(f"Scanning: {self.source_path}")
+
+        # Validate source path
+        if not self.source_path.exists():
+            raise ValueError(f"Source path does not exist: {self.source_path}")
+
+        # Scan for routes
+        scanner = RouteScanner(self.source_path, self.verbose)
+        routes = scanner.scan(self.routes_filter)
+
+        print(f"Found {len(routes)} routes")
+
+        # Create output directories
+        self.output_path.mkdir(parents=True, exist_ok=True)
+        if self.include_pom:
+            (self.output_path / 'pages').mkdir(exist_ok=True)
+
+        # Generate test files
+        test_generator = TestGenerator(self.include_pom, self.verbose)
+        pom_generator = PageObjectGenerator(self.verbose) if self.include_pom else None
+        config_generator = ConfigGenerator()
+
+        # Generate tests for each route
+        for route in routes:
+            # Generate test file
+            test_content = test_generator.generate(route)
+            test_filename = self._get_test_filename(route.path)
+            test_path = self.output_path / test_filename
+
+            test_path.write_text(test_content, encoding='utf-8')
+
+            self.results['generated_files'].append({
+                'type': 'test',
+                'route': route.path,
+                'path': str(test_path)
+            })
+
+            print(f"  {test_filename}")
+
+            # Generate Page Object if enabled
+            if self.include_pom:
+                pom_content = pom_generator.generate(route)
+                pom_filename = self._get_pom_filename(route.path)
+                pom_path = self.output_path / 'pages' / pom_filename
+
+                pom_path.write_text(pom_content, encoding='utf-8')
+
+                self.results['generated_files'].append({
+                    'type': 'page_object',
+                    'route': route.path,
+                    'path': str(pom_path)
+                })
+
+                print(f"  pages/{pom_filename}")
+
+        # Generate config files if not exists
+        config_path = Path('playwright.config.ts')
+        if not config_path.exists():
+            config_content = config_generator.generate_config()
+            config_path.write_text(config_content, encoding='utf-8')
+            self.results['generated_files'].append({
+                'type': 'config',
+                'path': str(config_path)
+            })
+            print(f"  playwright.config.ts")
+
+        # Generate auth fixture
+        fixtures_dir = self.output_path / 'fixtures'
+        fixtures_dir.mkdir(exist_ok=True)
+        auth_fixture_path = fixtures_dir / 'auth.ts'
+        if not auth_fixture_path.exists():
+            auth_content = config_generator.generate_auth_fixture()
+            auth_fixture_path.write_text(auth_content, encoding='utf-8')
+            self.results['generated_files'].append({
+                'type': 'fixture',
+                'path': str(auth_fixture_path)
+            })
+            print(f"  fixtures/auth.ts")
+
+        # Store route info
+        self.results['routes'] = [asdict(r) for r in routes]
+
+        # Summary
+        self.results['summary'] = {
+            'total_routes': len(routes),
+            'total_files': len(self.results['generated_files']),
+            'output_directory': str(self.output_path),
+            'include_pom': self.include_pom
+        }
+
+        print('')
+        print(f"Summary: {len(routes)} routes, {len(self.results['generated_files'])} files generated")
+
+        return self.results
+
+    def _get_test_filename(self, route_path: str) -> str:
+        """Get test filename from route path"""
+        if route_path == '/':
+            return 'home.spec.ts'
+
+        name = route_path.strip('/')
+        name = re.sub(r'\[([^\]]+)\]', r'\1', name)  # [id] -> id
+        name = name.replace('/', '-')
+        return f"{name}.spec.ts"
+
+    def _get_pom_filename(self, route_path: str) -> str:
+        """Get Page Object filename from route path"""
+        if route_path == '/':
+            return 'HomePage.ts'
+
+        name = route_path.strip('/')
+        name = re.sub(r'\[.*?\]', '', name)
+        parts = name.split('/')
+        class_name = ''.join(p.title() for p in parts if p) + 'Page'
+        return f"{class_name}.ts"
+
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Generate Playwright E2E tests from Next.js routes",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Scaffold E2E tests for App Router
+  python e2e_test_scaffolder.py src/app/ --output e2e/
+
+  # Include Page Object Models
+  python e2e_test_scaffolder.py src/app/ --include-pom
+
+  # Generate for specific routes only
+  python e2e_test_scaffolder.py src/app/ --routes "/login,/dashboard,/checkout"
+
+  # Verbose output
+  python e2e_test_scaffolder.py pages/ -v
+        """
+    )
+    parser.add_argument(
+        'source',
+        help='Source directory (app/ or pages/)'
+    )
+    parser.add_argument(
+        '--output', '-o',
+        default='e2e',
+        help='Output directory for test files (default: e2e/)'
+    )
+    parser.add_argument(
+        '--include-pom',
+        action='store_true',
+        help='Generate Page Object Model classes'
+    )
+    parser.add_argument(
+        '--routes',
+        help='Comma-separated list of routes to generate tests for'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Enable verbose output'
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+
+    args = parser.parse_args()
+
+    try:
+        scaffolder = E2ETestScaffolder(
+            source_path=args.source,
+            output_path=args.output,
+            include_pom=args.include_pom,
+            routes=args.routes,
+            verbose=args.verbose
+        )
+
+        results = scaffolder.run()
+
+        if args.json:
+            print(json.dumps(results, indent=2))
+
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()