playwright-route-tester/CLAUDE.md

Intelligent CLI tool that automatically generates Playwright tests with smart framework detection, zero-configuration setup, and advanced route testing

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

- `npm run build` - Build the project (copies src to dist, makes CLI executable, verifies templates)
- `npm run dev` - Run CLI in development mode using source files directly
- `npm run dev:scan` - Test project scanning functionality
- `npm run dev:setup` - Test smart setup functionality
- `npm test` - Run tests using Node.js built-in test runner
- `npm run prepublishOnly` - Automatically runs build before publishing

**Testing New Commands Locally:**
- `node dist/cli.js setup` - Test smart setup command
- `node dist/cli.js scan` - Test project scanning
- `node dist/cli.js jenkins` - Test Jenkins pipeline generation
- `node dist/cli.js info` - Test project information display

**Build Issues Resolution:**
If the build script hangs, manually build with:
```bash
rm -rf dist && mkdir -p dist
cp -r src/* dist/
chmod +x dist/cli.js
```

## Architecture Overview

This is an intelligent CLI tool that automatically generates Playwright test suites for route testing with authentication validation. The tool uses advanced project scanning, framework detection, and unified templating to provide zero-configuration setup.

### Core Architecture (v2.0)

**Smart CLI Interface (`src/cli.js`)**
- Enhanced CLI with multiple commands: `setup`, `scan`, `init`, `add-route`, `jenkins`, `info`
- Zero-configuration smart setup with auto-detection
- Framework-aware testing and configuration
- Jenkins pipeline generation
- Backward compatibility with legacy commands

**Project Scanner (`src/core/scanner.js`)**
- Automatically detects project framework (Next.js, React, Express, Vue, etc.)
- Scans codebase for existing routes (file-based and code-based routing)
- Intelligently categorizes routes as public, protected, or API
- Detects authentication patterns and login URLs
- Provides smart defaults and configuration suggestions

**Framework Detection System (`src/core/frameworks/`)**
- **Next.js Support (`nextjs.js`)**: Detects App Router, Pages Router, API routes
- **React Support (`react.js`)**: React Router, Reach Router, client-side routing
- **Express Support (`express.js`)**: REST APIs, middleware, route definitions
- Extensible architecture for adding new frameworks

**Unified Template Engine (`src/core/templates/engine.js`)**
- Handlebars-based templating with framework-specific conditionals
- Single template files replace 14+ duplicate templates (90% reduction)
- Dynamic feature enablement based on project configuration
- Smart test generation with framework optimizations

**Programmatic API (`src/index.js`)**
- Maintained for backward compatibility
- Enhanced with new smart features

### New Unified Template System

Located in `templates/unified/` directory with Handlebars templating:

**Core Templates:**
- `playwright.config.hbs` - Framework-aware Playwright configuration
- `test-config.hbs` - Smart test configuration with framework detection
- `tests.public.hbs` - Public route testing with framework optimizations
- `tests.protected.hbs` - Authentication redirect testing
- `tests.api.hbs` - API endpoint security testing
- `routes.*.hbs` - Route definition files
- `package.hbs` - Generated project package.json
- `redirect-helper.hbs` - Authentication helper utilities
- `jenkins.pipeline.hbs` - Self-configuring Jenkins pipeline

**Template Features:**
- Handlebars conditionals: `{{#ifFramework "nextjs"}}...{{/ifFramework}}`
- Feature flags: `{{#ifFeature "jenkins"}}...{{/ifFeature}}`
- Smart route iteration: `{{#eachRoute routes.public}}...{{/eachRoute}}`
- JSON helpers: `{{{json routes.api 2}}}` for proper formatting

### New Smart Generation Flow

1. **Project Scanning**: Automatically detect framework and routes
2. **Smart Configuration**: Generate config based on detected patterns
3. **Framework Optimization**: Apply framework-specific enhancements
4. **Unified Template Processing**: Single templates with conditional logic
5. **Intelligent Test Generation**: Context-aware test creation
6. **Jenkins Integration**: Optional self-configuring pipeline

### CLI Commands

**New Smart Commands:**
- `playwright-route-tester setup` - Zero-configuration smart setup
- `playwright-route-tester scan [--json]` - Analyze project for routes
- `playwright-route-tester jenkins` - Generate Jenkins pipeline
- `playwright-route-tester info` - Show project analysis

**Enhanced Legacy Commands:**
- `playwright-route-tester init [--scan]` - Interactive setup with auto-detection
- `playwright-route-tester add-route` - Enhanced route addition with validation

### Smart Generated Project Structure

```
playwright-tests/
├── config/test-config.js          # Framework-aware test configuration
├── helpers/redirect-helper.js     # Smart auth helpers with framework detection
├── routes/                         # Auto-detected route definitions
│   ├── public-routes.js           # Scanned public routes
│   ├── protected-routes.js        # Detected protected routes  
│   └── api-routes.js              # Found API endpoints
├── tests/                          # Framework-optimized tests
│   ├── public-routes.spec.js      # Smart public route validation
│   ├── auth-redirect.spec.js      # Intelligent auth redirect testing
│   └── api-routes.spec.js         # API security validation
├── playwright.config.js           # Framework-specific configuration
└── package.json                   # Optimized dependencies & scripts
```

### Framework-Specific Features

**Next.js Detection:**
- App Router vs Pages Router detection
- Dynamic route handling (`[id]`, `[...slug]`)
- API route auto-discovery
- Build integration and SSR considerations

**React Detection:**
- React Router vs Reach Router detection
- Client-side routing patterns
- SPA navigation testing
- Component-based route discovery

**Express Detection:**
- Route definition parsing (`app.get`, `router.post`)
- Middleware authentication detection
- REST API endpoint discovery
- Server-side route validation

### Smart Setup Modes

**Smart Setup (Recommended):**
- Zero-configuration with auto-detection
- Framework-specific optimizations
- Intelligent route discovery
- Self-configuring Jenkins pipeline

**Interactive Setup:**
- Manual route specification with smart suggestions
- Framework detection with user confirmation  
- Customizable configuration options

**Enhanced Route Configuration:**
```javascript
// Auto-detected routes with rich metadata
{ 
  url: '/', 
  title: 'Home Page', 
  expectedStatus: 200,
  framework: 'nextjs',
  type: 'page',
  file: '/app/page.tsx' 
}

// Smart protected route detection
{ 
  url: '/dashboard', 
  title: 'Dashboard', 
  requiresAuth: true, 
  expectedRedirect: '/login',
  authPattern: 'middleware'
}

// Framework-aware API routes
{ 
  url: '/api/users', 
  method: 'GET', 
  requiresAuth: true, 
  expectedStatus: 401,
  framework: 'nextjs',
  type: 'api',
  file: '/app/api/users/route.ts'
}
```

## Advanced Jenkins Integration

The new self-configuring Jenkins pipeline provides:

**Zero-Configuration Setup:**
- Automatic project detection and test generation
- Framework-specific build and test commands
- Smart health checks and server management
- No manual parameter configuration required

**Intelligent Pipeline Features:**
- Auto-detects framework and generates appropriate pipeline stages
- Dynamic test execution based on discovered routes
- Framework-specific optimizations (Next.js build, Express server start)
- Comprehensive HTML reporting with route details
- Automatic cleanup and artifact management

**Generated Pipeline Includes:**
- Environment setup with Node.js installation
- Smart dependency installation
- Auto-generated test suite creation
- Application health monitoring
- Parallel test execution (public, protected, API)
- Beautiful HTML reports with framework details
- Automatic server lifecycle management

## Dependencies

**Enhanced Runtime:**
- `commander` - CLI framework
- `inquirer` - Interactive prompts  
- `chalk` - Terminal colors
- `fs-extra` - Enhanced file system operations
- `handlebars` - Advanced templating engine
- `glob` - File pattern matching for route discovery

**Generated Test Projects:**
- `@playwright/test` - Testing framework (peer dependency)
- Framework-specific optimizations and dependencies

## Package Configuration

- ES modules (`"type": "module"`)
- Bin entry: `playwright-route-tester` → `dist/cli.js`
- Main entry: `dist/index.js`  
- Files included: `dist`, `templates`, `README.md`, `LICENSE`, `CLAUDE.md`
- Enhanced scripts: `dev:scan`, `dev:setup` for development
- Node.js test runner integration

## Usage Examples

**Zero-Configuration Setup:**
```bash
# Smart setup - detects everything automatically
npx playwright-route-tester setup

# With Jenkins pipeline
npx playwright-route-tester setup --jenkins
```

**Project Analysis:**
```bash
# Scan and display detected routes
npx playwright-route-tester scan

# JSON output for programmatic use
npx playwright-route-tester scan --json
```

**Jenkins Pipeline:**
```bash
# Generate smart Jenkins pipeline
npx playwright-route-tester jenkins
```

## No NPM Deployment of node_modules

The package correctly excludes `node_modules` from deployment:
- Uses `files` array in package.json to explicitly include only necessary files
- Dependencies are installed by end users (`npm install`)
- Keeps package size minimal and secure
- Templates and source code only in published package

## Current Status (v2.0.0)

### ✅ Completed Implementation
- **Smart Project Scanner**: Automatically detects frameworks and routes
- **Unified Template System**: 90% reduction in template files using Handlebars
- **Framework Detection**: Next.js, React Router, Express support
- **Enhanced CLI**: New commands (setup, scan, jenkins, info)
- **Self-Configuring Jenkins Pipeline**: Zero-configuration CI/CD
- **Version Checking & Upgrade System**: Smart upgrade prompts and compatibility handling
- **Legacy Support**: Backward compatibility with helpful upgrade prompts
- **Enhanced Documentation**: Updated README and architecture docs

### 🆕 New User Experience Features
- **Automatic Update Checking**: Prompts users when newer versions are available
- **Existing Setup Detection**: Recognizes old installations and offers upgrades
- **Smart Upgrade Prompts**: Guides users through v1 → v2 migration
- **Legacy Command Enhancement**: Old `init` command shows smart setup recommendations
- **Force Override**: `--force` flag to overwrite existing setups
- **Version Check Disable**: `--no-version-check` flag for CI environments

### 🚧 Current Build Status
- **Source Code**: All smart features + upgrade system implemented in `src/`
- **Dist Build**: Manually built with new version checking features
- **Testing**: All commands tested including upgrade prompts
- **Version**: Bumped to 2.0.0 to reflect major architectural changes
- **NPX Ready**: After publishing, will provide seamless upgrade experience

### 🔄 For Publishing v2.0.0
1. Ensure `dist/` contains latest built files with version checking
2. All templates in `templates/unified/` are included
3. Version set to 2.0.0 in package.json (major version for breaking changes)
4. Enhanced dependencies (handlebars, glob) included
5. New VersionChecker module included in build

### 🧪 Testing the New Architecture
```bash
# Test smart setup with upgrade detection
node dist/cli.js setup --directory ./test-output

# Test version checking and upgrade prompts
node dist/cli.js setup  # Will detect existing setups

# Test legacy command with smart recommendations
node dist/cli.js init   # Shows smart setup recommendations

# Test project scanning
node dist/cli.js scan --json

# Test Jenkins pipeline generation  
node dist/cli.js jenkins

# Test framework detection
node dist/cli.js info

# Test with version check disabled (for CI)
node dist/cli.js setup --no-version-check
```

### 📱 User Experience Improvements
The new version provides:
1. **Seamless Upgrades**: Existing v1 users get prompted to upgrade with clear benefits
2. **Backward Compatibility**: All old commands still work with helpful guidance
3. **Smart Detection**: Recognizes existing setups and offers appropriate actions
4. **Clear Guidance**: Users know exactly what commands to run and why

### 🚀 Key Improvements Delivered
1. **Zero-Configuration Setup**: `npx playwright-route-tester setup`
2. **Smart Framework Detection**: Automatic Next.js, React, Express support
3. **90% Code Reduction**: Unified templates replace duplicate files
4. **Jenkins Integration**: Self-configuring CI/CD pipelines
5. **Enhanced Security Testing**: Framework-aware vulnerability detection
6. **Better Developer Experience**: Intuitive CLI with helpful guidance

The tool has been transformed from a simple template generator into an intelligent, framework-aware testing solution that works out of the box with zero configuration!