Cypress Test Generator

AI-powered generator that crawls a site and produces production-quality Cypress tests, a Page Object, and fixtures. Built with Flask + Playwright, with AI-powered test enhancement for enterprise-grade output.

✨ Key Features

• 🔐 Login Bypass: Automatically handles protected pages with login prompts. Enter credentials once and scrape authenticated content.
• 🤖 AI-Powered Enhancement: Uses GPT-4 to transform generated tests into production-quality code following Cypress best practices.
• 📋 Comprehensive Scraping: Extracts ALL form fields, buttons, and interactive elements - not just a few.
• ⚡ Livewire Support: Full support for Laravel Livewire applications with wire:model and wire:click attributes.
• 🎯 Smart Form Detection: Intelligently distinguishes login forms from data entry forms.
• 📦 Source-Aware Generation: Point the generator at a Git repository to scaffold a complete Cypress project (fixtures, support files, specs, config) ready for regression testing.
• 🧱 Static/PHP Support: Repository mode now falls back to scanning HTML/PHP templates when no SPA framework is detected, so traditional apps still get Cypress coverage.
• 📊 Production-Ready Output: Generates tests with validation scenarios, proper wait strategies, and realistic test data.
• 🔍 Enhanced Element Extraction: Captures dynamically revealed forms by interacting with reveal buttons.

Requirements

• Python 3.13 (or 3.8+)
• Node.js 16+ and npm
• An OpenAI API key (optional; features still work without it)

Quick start

# 1) Install globally (recommended for quickest start)
npm install -g cypress-generator

# 2) Create a Python virtual env (recommended)
python3 -m venv .venv && source .venv/bin/activate

# 3) Install Python deps and Playwright browsers
pip install -r requirements.txt || pip install flask flask-cors requests beautifulsoup4 playwright openai python-dotenv
python -m playwright install

# 4) (Optional) Enable AI features
export OPENAI_API_KEY=your_openai_api_key

# 5) Run the server
cypress-generator
# Open http://localhost:5001

Local project usage

If you cloned this repo or installed the package locally in a project, the CLI now prefers your local project’s app.py when you run cypress-generator from that folder.

# Install locally
npm install cypress-generator

# Python env
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python -m playwright install

# Run (prefers local project when inside its folder)
npx cypress-generator
# or
python app.py  # default port 5000

Environment variables

Create a .env in the project root if you want to persist settings.

# Optional, enables AI suggestions in generated tests
OPENAI_API_KEY=your_openai_api_key

# Flask
FLASK_ENV=development
PORT=5000
HOST=0.0.0.0

What you get

Generated Files

• Main Cypress test file: generated_scripts/cypress_test_<domain>.js
  • Production-quality test code with AI enhancement
  • Comprehensive validation tests (required, min, max, format, unique)
  • Realistic user workflows and test scenarios
  • Proper wait strategies and error handling
• Page Object: <TitleNoSpaces>Page.js
  • Encapsulates selectors and actions for maintainability
• Fixtures: test_data.json
  • Realistic test data based on detected form fields
  • Includes member/profile data if applicable

Repository Mode Output

• Cypress project archive: generated_scripts/repo_<name>_<id>.zip
  • Structured with cypress/e2e, cypress/fixtures, and cypress/support
  • Includes preconfigured cypress.config.js and package.json
  • Specs are generated per detected route with TODOs for project-specific assertions

Test Quality Features

• ✅ Comprehensive Field Extraction: All form fields captured, not just a few
• ✅ Livewire Support: Proper handling of wire:model and wire:click attributes
• ✅ Validation Testing: Required, minimum, maximum, format, and unique validations
• ✅ Production Patterns: Follows Cypress best practices from industry examples
• ✅ Smart Selectors: Prioritizes stable selectors (IDs, wire:model, data-testid)
• ✅ Dynamic Content: Handles dynamically revealed forms and content

The web UI includes a built-in IDE-like viewer with tabs (Test, Page Object, Fixture) and Copy/Download buttons.

Web UI

Basic Usage

1. Start the server (see Quick start or Local project usage).
2. Visit http://localhost:5001 when using the CLI or npm run dev (Flask runs on 5001).
   If you run python app.py directly, it defaults to http://localhost:5000 (or pass --port for 5001).
3. Choose between Website Crawl (default) or Git Repository mode in the generator.
   • Website mode crawls the live site and produces test/page object/fixture files.
   • Git Repository mode clones source code, detects routes, and bundles a Cypress project as a downloadable zip (configure branch, subdirectory, and default baseUrl as needed).
4. Click Generate and review the output cards. The IDE panel will show code output with copy/download tabs (Test, Page Object, Fixture), and repository runs expose a “Download Cypress Bundle” button.

Using with Protected Pages (Login Bypass)

1. Enter a URL that requires authentication (e.g., a staging-only members page).
2. Click Generate.
3. A login modal will automatically appear if the page requires authentication.
4. Enter your credentials:
   • Email or Username
   • Password
5. Click "Login & Continue".
6. The generator will:
   • Authenticate using your credentials
   • Navigate to the protected page
   • Extract all form fields and interactive elements
   • Generate comprehensive test code
7. Your session is stored and can be reused for subsequent requests.

Authentication Flow

When you enter a URL that requires login:

• ✅ The generator detects login pages automatically (by analyzing forms, titles, URLs)
• ✅ A login modal appears in the UI
• ✅ Enter your credentials (email/username and password)
• ✅ The generator authenticates and navigates to the protected content
• ✅ All form fields, buttons, and interactive elements are extracted
• ✅ Your session is stored for reuse (no need to login again for related requests)

API

Generate Tests

• POST /api/generate — Generate Cypress tests for a URL

Request Body:

{
  "url": "https://example.com",
  "email": "[email protected]",        // Optional: for protected pages
  "username": "username",              // Optional: alternative to email
  "password": "password",              // Optional: for protected pages
  "session_id": "existing_session_id", // Optional: reuse existing session
  "repo_url": "https://github.com/org/webapp.git",      // Optional: generate from repository
  "repo_branch": "develop",                              // Optional: branch/tag to clone
  "repo_subdirectory": "apps/frontend",                  // Optional: limit analysis to a path
  "base_url": "http://localhost:3000"                    // Optional: default baseUrl for repo suite
}

Example:

# Public page
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# Protected page with login
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://protected-site.com/members/create",
    "email": "[email protected]",
    "password": "password123"
  }'

# Repository (source-aware) mode only
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/org/webapp.git",
    "repo_branch": "main",
    "base_url": "http://localhost:5173"
  }'

Response shape:

• URL-only requests maintain the existing top-level fields (script, page_object, fixture, ...).
• Repository requests return { "repository_suite": { ... } }.
• When both url and repo_url are supplied the response combines both outputs and adds a repository_suite section alongside the scraped artefacts.

Login Endpoint

• POST /api/login — Verify and store login credentials for session reuse

Request Body:

{
  "url": "https://example.com",
  "email": "[email protected]",
  "password": "password123"
}

Response:

{
  "success": true,
  "session_id": "abc123...",
  "authenticated": true
}

Other Endpoints

• GET /api/test_types — Get available test types
• POST /api/ask-ai — Ask AI questions about test generation
• GET /api/download?file=<name> — Download generated artifacts (e.g., repository Cypress bundle zips)

Features & Capabilities

🔐 Authentication Handling

• Automatic Login Detection: Detects login pages by analyzing forms, titles, and URLs
• Interactive Login Modal: User-friendly modal for entering credentials
• Session Management: Stores authenticated sessions for reuse
• Protected Content Access: Scrapes content behind login walls
• Smart Form Detection: Distinguishes login forms from data entry forms

🤖 AI-Powered Enhancement

• Production-Quality Output: GPT-4 enhances generated tests to match enterprise standards
• Best Practices: Follows Cypress documentation and industry patterns
• Comprehensive Validation: Generates validation tests for all scenarios
• Realistic Test Data: Creates appropriate fixtures based on form fields
• Custom Commands: Suggests custom Cypress commands for common operations

📋 Enhanced Scraping

• Complete Field Extraction: Captures ALL form fields, not just a subset
• Dynamic Content: Interacts with reveal buttons to show hidden forms
• Livewire Support: Special handling for Laravel Livewire components
• Smart Filtering: Excludes logout/login forms from test generation
• Priority-Based: Prioritizes Livewire fields and required fields

Notes and best practices

• Always use a Python virtual environment to avoid system Python restrictions (PEP 668).
• After installing Playwright, run playwright install once to download browsers.
• For best results: Set OPENAI_API_KEY to enable AI-powered test enhancement for production-quality output.
• The generator attempts to lint JS if eslint is available. If ESLint isn't configured, generation still succeeds; the warning is safe to ignore.
• For protected pages: Enter credentials when prompted. The session is stored and reused for subsequent requests.
• Livewire applications: The generator automatically detects and properly handles Livewire components.

Troubleshooting

• pip not found:

python3 -m ensurepip --upgrade
python3 -m pip install --upgrade pip

• Missing python-dotenv or other packages:

pip install python-dotenv flask flask-cors requests beautifulsoup4 playwright openai

• Playwright browsers missing:

python -m playwright install

• OpenAI errors: ensure OPENAI_API_KEY is set and valid.

Project scripts

npm run server   # python run_server.py
npm run dev      # python run_server.py
npm run setup    # install Python deps via postinstall helper

Changelog

Version 1.1.1 (Latest)

• ✨ NEW: Login bypass feature - automatically handles protected pages with interactive login modal
• ✨ NEW: AI-powered test enhancement using GPT-4 for production-quality output
• 🚀 IMPROVED: Enhanced scraping captures ALL form fields, not just a few
• 🚀 IMPROVED: Better form detection - distinguishes login forms from data entry forms
• 🚀 IMPROVED: Dynamic content interaction - clicks reveal buttons to show hidden forms
• 🚀 IMPROVED: Livewire support - prioritizes wire:model and wire:click attributes
• 🚀 IMPROVED: Comprehensive validation testing generation
• 🚀 IMPROVED: Better fixture generation with realistic test data
• 🐛 FIXED: Removed circular dependency in package.json

Version 1.0.18

• Basic scraping and test generation
• Page Object Model support
• Fixture generation

See CHANGELOG.md for older versions.