socialseed-e2e 0.1.6

Framework E2E para testing de APIs REST con Playwright

🌱 SocialSeed E2E

---

🤖 AI Agent First - Start Here!

This section is for AI agents. If you're using OpenCode, Claude, or any AI to create tests, START HERE:

1. Install Framework

pip install socialseed-e2e

2. Initialize Project with Your API

# Create test directory
mkdir api-tests && cd api-tests

# Auto-detect your API and generate AI documentation
e2e init . --api

That's it! Now run your AI agent:

opencode .

3. Tell the AI What to Do

Example prompts for AI agents:

"Create tests for the auth service login endpoint"
"Test the user registration flow"
"Generate tests for all CRUD operations"
"Test error handling for invalid inputs"

What AI Agents Need to Know

When AI agent starts, it will find in .agent/:

File	Description
ENDPOINTS.md	All API endpoints with methods, paths
DATA_SCHEMAS.md	DTOs, models, request/response formats
AUTH_FLOWS.md	Login, register, password reset flows
TEST_PATTERNS.md	Test templates ready to use
ERROR_CODES.md	Error codes and messages

Multi-Service Projects

For projects with multiple microservices:

# Each service gets its own documentation
e2e init tests/auth --scan ../services/auth-service/src
e2e init tests/user --scan ../services/user-service/src
e2e init tests/payment --scan ../services/payment-service/src

Example: Full AI Workflow

# 1. Install
pip install socialseed-e2e

# 2. Setup
mkdir tests && cd tests
e2e init . --api

# 3. Run AI
opencode .

# 4. AI will:
#    - Read .agent/ to understand your API
#    - Read e2e.conf for service URLs
#    - Create tests in services/<name>/modules/
#    - Run tests with e2e run --service <name>

Troubleshooting AI Agents

Problem: AI generates wrong endpoints Solution: Update documentation:

e2e init . --scan ../path/to/your-api

Problem: AI can't connect to services Solution: Check e2e.conf has correct URLs:

services:
  auth-service:
    base_url: http://localhost:8085

Problem: AI doesn't understand the API Solution: Ensure .agent/ docs are generated:

e2e init . --api

---

📚 For Developers - Manual Setup

If you prefer manual configuration instead of AI:

Quick Start

# Install
pip install socialseed-e2e

# Initialize
e2e init my-project
cd my-project

# Create service
e2e new-service my-api --base-url http://localhost:8080

# Run tests
e2e run

Configuration (e2e.conf)

services:
  my-api:
    base_url: http://localhost:8080
    health_endpoint: /health

---

The Problem

pip install socialseed-e2e

### 2. Initialize Project

```bash
e2e init demo
cd demo

Output:

🌱 Initializing E2E project at: /path/to/demo

  ✓ Created: services
  ✓ Created: tests
  ✓ Created: .github/workflows
  ✓ Created: e2e.conf
  ✓ Created: .gitignore
  ✓ Created: requirements.txt
  ✓ Created: .agent/ (AI Documentation)

✅ Project initialized successfully!

3. Create Your First Service

e2e new-service demo-api --base-url http://localhost:8080

Generated Folder Structure:

demo/
├── e2e.conf                    # Configuration file
├── services/
│   └── demo-api/
│       ├── __init__.py
│       ├── demo_api_page.py    # Service Page class
│       ├── data_schema.py      # Data models
│       └── modules/            # Test modules
├── tests/                      # Additional tests
└── .github/workflows/          # CI/CD templates

4. Create Your First Test

e2e new-test health --service demo-api

This creates services/demo-api/modules/01_health_flow.py with a test template.

5. Start Your API (3 Options)

Before running tests, you need an API server running. You have three options:

Option A: Use the Included Demo API (Recommended for beginners)

The e2e init command automatically creates a demo REST API with CRUD operations:

# Install dependencies (includes Flask for the demo API)
pip install -r requirements.txt

# Start the demo API (in a separate terminal)
cd demo
python api-rest-demo.py

# The API will start on http://localhost:5000
# It includes 10 sample users and full CRUD endpoints

Note: If you get a ModuleNotFoundError: No module named 'flask' error, install Flask manually:

pip install flask>=2.0.0

Update your service to use the demo API:

# Edit e2e.conf and change the base_url to http://localhost:5000
e2e set url demo-api http://localhost:5000

Option B: Use Your Own API

Ensure your API is running at the configured base URL (e.g., http://localhost:8080):

# Start your API (example)
python your_api.py
# or
npm start
# or
docker-compose up

Option C: Use the Built-in Mock Server

# Install Flask (required for mock server)
pip install flask>=2.0.0

# Start the mock server in a separate terminal
python -m socialseed_e2e.mock_server

6. Run Tests

e2e run

Expected Output:

🚀 socialseed-e2e v0.1.6
══════════════════════════════════════════════════

📋 Configuration: e2e.conf
🌍 Environment: dev

Services Summary:
   Detected:    [demo-api]
   Configured:  [demo-api]

Running tests for service: demo-api
══════════════════════════════════════════════════

✓ demo-api tests completed

════════════════════════════════════════════════════════════
Test Execution Summary
════════════════════════════════════════════════════════════

demo-api: 1/1 passed (100.0%)

✅ All tests passed!

---

## 📋 System Requirements

Before installing socialseed-e2e, ensure your environment meets the following requirements:

### Python Versions

- **Python >= 3.10** (required)
- Tested on Python 3.10, 3.11, and 3.12

### Operating Systems

- ✅ **Linux** - Fully supported (primary development platform)
- ✅ **macOS** - Fully supported (Intel and Apple Silicon)
- ⚠️ **Windows** - Supported via WSL2 (Windows Subsystem for Linux)

### Browser Dependencies

socialseed-e2e uses **Playwright** for HTTP testing. You need to install browser binaries:

```bash
# After installing socialseed-e2e
playwright install chromium

# Or install with dependencies (recommended for CI/CD)
playwright install --with-deps chromium

Supported Browsers:

• Chromium (recommended for API testing)
• Firefox (optional)
• WebKit (optional)

System Dependencies

Linux (Ubuntu/Debian)

# Playwright system dependencies
sudo apt-get update
sudo apt-get install -y libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
  libxrandr2 libgbm1 libasound2

macOS

# No additional system dependencies required
# Playwright will prompt if anything is needed

Docker (Optional)

You can also run socialseed-e2e using Docker:

# Build the Docker image
docker build -t socialseed-e2e .

# Run tests in container
docker run --rm -v $(pwd):/app socialseed-e2e e2e run

Docker Benefits:

• Consistent testing environment
• No local Python/Playwright installation needed
• Perfect for CI/CD pipelines

---

🐳 Docker Usage

SocialSeed E2E provides an official Docker image for containerized test execution. This is ideal for CI/CD pipelines and environments where you want to avoid installing Python dependencies locally.

Building the Docker Image

# Clone or navigate to the project directory
cd socialseed-e2e

# Build the Docker image
docker build -t socialseed-e2e .

Running Tests with Docker

Basic Usage

# Show help
docker run --rm socialseed-e2e --help

# Run all tests (mount your project directory)
docker run --rm -v $(pwd):/app socialseed-e2e run

# Run tests for a specific service
docker run --rm -v $(pwd):/app socialseed-e2e run --service users-api

# Run with verbose output
docker run --rm -v $(pwd):/app socialseed-e2e run --verbose

Advanced Usage

# Run with debug mode
docker run --rm -v $(pwd):/app socialseed-e2e run --debug

# Run in boring mode (disable AI features)
docker run --rm -v $(pwd):/app socialseed-e2e run --no-agent

# Generate JUnit report
docker run --rm -v $(pwd):/app -v $(pwd)/reports:/app/reports socialseed-e2e run --report junit

# Run specific test module
docker run --rm -v $(pwd):/app socialseed-e2e run --service auth --module 01_login

Docker in CI/CD

Example GitHub Actions workflow using Docker:

name: E2E Tests with Docker

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Docker image
        run: docker build -t socialseed-e2e .
      
      - name: Run E2E tests
        run: docker run --rm -v $(pwd):/app socialseed-e2e run --report junit
      
      - name: Upload test results
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: ./reports/junit.xml

Benefits of Docker Usage

• No local installation: No need to install Python, Playwright, or dependencies
• Consistent environment: Same environment across dev, CI, and production
• Isolated execution: Tests run in a clean, isolated container
• Easy CI/CD integration: Simple to integrate with any CI/CD platform
• Version pinning: Use specific versions of the framework via Docker tags

---

🤖 Built for AI Agents (Recommended)

This framework was designed from the ground up for AI agents.

While you can write tests manually, the true power comes from letting AI do the work:

# 1. Initialize
e2e init

# 2. Tell your AI agent:
# "Read the .agent/ folder and generate tests for my API"

# 3. The AI automatically:
# - Scans your API code
# - Generates complete test suites
# - Uses semantic search to understand your endpoints
# - Creates stateful test chains

AI Features:

• Auto-generates project_knowledge.json from your codebase
• Vector embeddings for semantic search over your API
• RAG-ready retrieval for context-aware test generation
• Structured protocols that AI agents understand

Don't have an AI agent? You can write tests manually too—it's still 10x faster than traditional frameworks.

---

✨ What You Get

• CLI scaffolding - e2e new-service and e2e new-test commands
• Auto-discovery - Tests run in order automatically
• Stateful chaining - Share data between tests
• Built-in mocking - Test without external dependencies
• AI Manifest - Auto-generate API knowledge from code
• Vector search - Semantic search over your API (RAG-ready)

---

📚 Advanced Usage Examples

Learn how to handle common testing scenarios with these examples:

Authorization Headers

• Basic Authentication
• Bearer Token (JWT)
• API Key authentication
• Custom headers
• OAuth 2.0 flow

Environment Variables

• Loading .env files
• Environment-specific configuration
• Secrets management
• Test data from environment

Test Fixtures

• Setup/teardown logic
• Sharing state between tests
• Page attributes as fixtures
• Test isolation patterns
• Cleanup strategies

Parameterized Tests

• Multiple test files
• External test data (JSON, CSV)
• Test data providers
• Dynamic test generation
• pytest parametrize integration

# Run an example
python3 examples/advanced_usage/auth_headers_example.py

---

📝 Example Test

# services/users-api/modules/01_login.py

async def run(page):
    response = await page.do_login(
        email="[e-mail]",
        password="secret"
    )
    assert response.status == 200
    assert "token" in response.json()
    return response

---

✅ Checklist for Creating Tests

Before creating tests, ensure your service setup follows these conventions:

Directory Structure

services/{service_name}/
├── __init__.py
├── {service_name}_page.py      # Must be named EXACTLY like this
├── data_schema.py               # Optional: Data models and constants
└── modules/                     # Test modules directory
    ├── 01_login.py
    └── __init__.py

Requirements

• Directory: services/{service_name}/ - Use underscores (e.g., auth_service)
• Page File: {service_name}_page.py - Must be named exactly like the directory + _page.py
• Inheritance: Class must inherit from BasePage
• Constructor: Must accept base_url: str and call super().__init__(base_url=base_url)
• Configuration: The services block in e2e.conf must match the directory name (hyphens/underscores are normalized)

Boilerplate: {service_name}_page.py

"""Page class for {service_name} API."""

from socialseed_e2e.core.base_page import BasePage
from typing import Optional


class AuthServicePage(BasePage):  # Replace AuthService with your service name
    """Page object for auth-service API interactions."""
    
    def __init__(self, base_url: str, **kwargs):
        """Initialize the page with base URL.
        
        Args:
            base_url: Base URL for the API (e.g., http://localhost:8080)
            **kwargs: Additional arguments passed to BasePage
        """
        super().__init__(base_url=base_url, **kwargs)
    
    def do_login(self, email: str, password: str):
        """Execute login request."""
        return self.post("/auth/login", json={
            "email": email,
            "password": password
        })

Configuration Example (e2e.conf)

services:
  auth_service:  # Matches services/auth_service/ directory
    base_url: http://localhost:8080
    health_endpoint: /health

Note: Service names with hyphens (e.g., auth-service) are automatically normalized to underscores (auth_service) for matching.

---

🎯 CLI Commands

Core Commands

e2e init [dir]              # Initialize project
e2e new-service <name>      # Create service structure
e2e new-test <name>         # Create test module
e2e run                     # Run all tests
e2e lint                    # Validate test files
e2e config                  # Show configuration

AI Features

e2e manifest                # Generate API knowledge manifest
e2e manifest-query          # Query manifest
e2e build-index            # Build vector index for semantic search
e2e search "query"         # Semantic search (RAG)
e2e retrieve "task"        # Retrieve context for task
e2e watch                  # Auto-update manifest on file changes
e2e discover               # Generate AI Discovery Report
e2e generate-tests         # Autonomous test generation
e2e plan-strategy          # Generate test strategy
e2e autonomous-run         # Run tests with AI orchestration

Testing & Debugging

e2e doctor                 # Verify installation
e2e deep-scan              # Zero-config project mapping
e2e observe                # Auto-detect services and ports
e2e debug-execution        # Debug failed tests with AI
e2e analyze-flaky         # Analyze flaky test patterns
e2e healing-stats          # View self-healing statistics
e2e regression             # AI regression analysis
e2e semantic-analyze       # Semantic drift detection

Performance & Security

e2e perf-profile           # Performance profiling
e2e perf-report           # Generate performance report
e2e security-test          # AI-driven security fuzzing
e2e red-team assess        # Adversarial security testing

Mocking & Recording

e2e mock-analyze          # Analyze external API dependencies
e2e mock-generate <svc>   # Generate mock server
e2e mock-run              # Run mock servers
e2e mock-validate         # Validate API contracts
e2e recorder record        # Record API session
e2e recorder replay       # Replay session
e2e shadow capture        # Capture production traffic

Import & Export

e2e import postman <file> # Import Postman collection
e2e import openapi <file> # Import OpenAPI spec
e2e import curl <cmd>      # Import curl command
e2e gherkin-translate     # Convert Gherkin to tests
e2e translate             # Natural language to test code

CI/CD & Community

e2e setup-ci <platform>   # Generate CI/CD templates
e2e community templates   # List community templates
e2e community plugins     # List plugins

Additional Commands

e2e install-demo          # Install demo APIs (D01-D16)
e2e install-extras       # Install optional dependencies (tui, rag, dashboard, etc.)
e2e telemetry             # Token usage monitoring
e2e ai-learning feedback  # View AI feedback
e2e dashboard             # Launch web dashboard (Vue.js + FastAPI)
e2e tui                  # Launch terminal interface
e2e set url <svc> <url>  # Configure service URL
e2e --version            # Show version

Full Command Reference

See docs/cli-reference.md for complete documentation.

---

🔄 CI/CD Integration

SocialSeed E2E provides ready-to-use CI/CD templates for seamless integration into your pipelines.

GitHub Actions

The framework includes a pre-configured GitHub Actions workflow at .github/workflows/e2e.yml:

name: E2E Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '>=3.10'
    - name: Install socialseed-e2e
      run: pip install socialseed-e2e
    - name: Install Playwright Browsers
      run: playwright install --with-deps chromium
    - name: Run E2E Tests
      run: e2e run --report junit
    - name: Upload Test Results
      uses: actions/upload-artifact@v4
      with:
        name: junit-test-results
        path: ./reports/junit.xml

Features:

• ✅ Triggers on push/PR to main branch
• ✅ Python 3.10+ support
• ✅ Automatic JUnit XML report generation
• ✅ Test artifacts uploaded for 30 days
• ✅ Workflow summary in GitHub Actions UI

Setup Instructions

1. Use the built-in template:

   e2e setup-ci github
   

2. Or manually copy the .github/workflows/e2e.yml file to your repository

3. The workflow will automatically:

   • Run on every push/PR to main
   • Install socialseed-e2e
   • Execute all E2E tests
   • Generate JUnit reports
   • Upload artifacts for analysis

Other Platforms

Generate templates for other CI/CD platforms:

e2e setup-ci gitlab      # GitLab CI
e2e setup-ci jenkins     # Jenkins
e2e setup-ci azure       # Azure DevOps
e2e setup-ci circleci    # CircleCI
e2e setup-ci travis      # Travis CI

---

🎯 CLI Reference

Complete reference for all CLI commands and flags.

Global Options

e2e --help          # Show help message and exit
e2e --version       # Show version information

Core Commands

e2e init - Initialize Project

Initialize a new E2E testing project with directory structure and configuration files.

e2e init [DIRECTORY] [OPTIONS]

Options:
  --force    Overwrite existing files

Examples:

e2e init                      # Initialize in current directory
e2e init my-project           # Initialize in specific directory
e2e init --force              # Overwrite existing files

e2e new-service - Create Service

Create a new service with complete scaffolding (page class, data schema, and modules directory).

e2e new-service NAME [OPTIONS]

Arguments:
  NAME    Service name (e.g., users-api, auth_service)

Options:
  --base-url TEXT          Service base URL (default: http://localhost:8080)
  --health-endpoint TEXT   Health check endpoint path (default: /health)

Examples:

e2e new-service users-api
e2e new-service payment-service --base-url http://localhost:8081
e2e new-service auth-service --base-url http://localhost:8080 --health-endpoint /actuator/health

e2e new-test - Create Test

Create a new test module for an existing service.

e2e new-test NAME --service SERVICE

Required:
  --service TEXT    Service name to create test for

Examples:

e2e new-test login --service auth-api
e2e new-test create-user --service users-api

e2e run - Execute Tests

Run E2E tests with various filtering and output options.

e2e run [OPTIONS]

Filtering Options:
  -s, --service TEXT              Run tests for specific service only
  -m, --module TEXT               Run specific test module
  -t, --tag TEXT                  Only run tests with these tags (can be used multiple times)
  -x, --exclude-tag TEXT          Exclude tests with these tags (can be used multiple times)

Configuration Options:
  -c, --config TEXT               Path to configuration file (default: e2e.conf)
  -v, --verbose                   Enable verbose output with detailed information

Output Options:
  -o, --output [text|json|html]   Output format (default: text)
  --report-dir PATH               Directory for HTML reports (default: .e2e/reports)

Report Generation:
  --report [junit|json]           Generate machine-readable test report
  --report-output PATH            Directory for reports (default: ./reports)

Debugging:
  -d, --debug                     Enable debug mode with verbose HTTP request/response logging for failed tests

Parallel Execution:
  -j, --parallel INTEGER          Enable parallel execution with N workers (0=disabled)
  --parallel-mode [service|test]  Parallel execution mode

Traceability:
  -T, --trace                     Enable visual traceability and generate sequence diagrams
  --trace-output PATH             Directory for traceability reports
  --trace-format [mermaid|plantuml|both]  Format for sequence diagrams

Examples:

e2e run                                              # Run all tests
e2e run --service auth_service                       # Run tests for specific service
e2e run --service auth_service --module 01_login     # Run specific test module
e2e run --verbose                                    # Run with detailed output
e2e run --output html --report-dir ./reports         # Generate HTML report
e2e run --parallel 4                                 # Run with 4 parallel workers
e2e run --trace                                      # Enable traceability
e2e run -c /path/to/e2e.conf                         # Use custom config file
e2e run --report junit                               # Generate JUnit XML report
e2e run --report json                                # Generate JSON report
e2e run --report junit --report-output ./reports     # Custom report directory
e2e run --debug                                      # Enable debug mode with HTTP logging

AI-Powered Commands

e2e manifest - Generate AI Project Manifest

Generate structured API knowledge from your codebase for AI agents.

e2e manifest [DIRECTORY]

e2e search - Semantic Search

Search your API endpoints and DTOs using natural language (RAG-ready).

e2e search QUERY

e2e search "authentication endpoints"
e2e search "user DTO" --type dto

e2e build-index - Build Vector Index

Build vector embeddings index for semantic search.

e2e build-index

e2e deep-scan - Auto-Discover Project

Zero-config deep scan for automatic project mapping and configuration.

e2e deep-scan [DIRECTORY]

Options:
  --auto-config    Automatically configure e2e.conf based on scan results

e2e generate-tests - AI Test Generation

Autonomous test suite generation based on code intent.

e2e generate-tests [OPTIONS]

Options:
  --service TEXT    Target service for test generation
  --module TEXT     Specific module to generate tests for

e2e translate - Natural Language to Test Code

Translate natural language descriptions to test code.

e2e translate "Create a test that logs in and verifies the token"

CI/CD Commands

e2e setup-ci - Generate CI/CD Templates

Generate CI/CD pipeline templates for various platforms.

e2e setup-ci PLATFORM

Platforms:
  github       GitHub Actions
  gitlab       GitLab CI
  jenkins      Jenkins
  azure        Azure DevOps
  circleci     CircleCI
  travis       Travis CI
  bitbucket    Bitbucket Pipelines

Examples:

e2e setup-ci github      # Generate GitHub Actions workflow
e2e setup-ci gitlab      # Generate GitLab CI configuration
e2e setup-ci jenkins     # Generate Jenkinsfile

Utility Commands

e2e config - Show Configuration

Show and validate current configuration.

e2e config

e2e doctor - Verify Installation

Verify installation and check dependencies.

e2e doctor

e2e watch - File Watcher

Watch project files and auto-update manifest on changes.

e2e watch [DIRECTORY]

e2e observe - Service Discovery

Auto-detect running services and ports.

e2e observe [DIRECTORY]

Options:
  -h, --host TEXT         Hosts to scan
  -p, --ports TEXT        Port range (e.g., 8000-9000)
  -t, --timeout FLOAT     Timeout for port scanning in seconds
  --docker / --no-docker  Scan Docker containers
  --auto-setup            Auto-setup environment using Docker
  --dry-run               Show what would be done without executing

Getting Help

Use --help with any command for detailed information:

e2e --help
e2e run --help
e2e new-service --help
e2e generate-tests --help

---

📚 Documentation

All guides at daironpf.github.io/socialseed-e2e

• How it Works - Understanding the core concepts (Service, Endpoint, Scenario, Test)
• Quick Start
• Writing Tests
• CI/CD Integration
• CLI Reference
• AI Manifest

---

📜 License

MIT - See LICENSE

_{Built with ❤️ by Dairon Pérez Frías and AI co-authors}