socialseed-e2e 0.1.4

Framework E2E para testing de APIs REST con Playwright

🌱 SocialSeed E2E

The Problem: Your E2E Tests Are Brittle and Slow

If you're a QA engineer or developer, you know the pain:

• Fragile tests that break with every minor UI or API change
• Complex setup requiring multiple tools and configurations
• Slow feedback loops waiting hours for test suites to run
• Unreliable CI/CD with flaky tests causing false positives
• Repetitive boilerplate writing the same test patterns over and over

The Solution: Reliable E2E Testing That Scales

SocialSeed E2E is a testing platform designed for production reliability with optional AI acceleration.

Who is this for?

• QA Engineers who need stable, maintainable API tests without writing boilerplate
• Developers who want fast feedback on API changes without the overhead
• Teams transitioning from experimental AI testing to a production-ready solution

Why we built this?

Most AI-driven testing frameworks promise the world but deliver unreliable, flaky tests. We wanted something different:

1. Reliability First - Tests that pass when they should, fail when they must
2. Optional AI Acceleration - Use AI to generate tests faster when you want it, but never required
3. Developer Experience - CLI that gets out of your way and lets you focus on testing
4. Production Ready - Built for CI/CD pipelines from day one

"Write tests that survive your API changing, not tests that break on every update."

📚 Full Documentation

---

🚀 Quick Start

Get up and running in under 5 minutes with this minimal setup:

1. Install

pip install socialseed-e2e

2. Initialize Project

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.4
══════════════════════════════════════════════════

📋 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!

Note: If tests fail with "Connection refused", ensure your API server is running before executing e2e run.

---

📋 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:

# 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

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 setup-ci <platform>     # Generate CI/CD pipelines
e2e manifest                # Generate API knowledge
e2e search "auth"           # Semantic search (RAG)
e2e build-index             # Build vector index
e2e watch                   # Auto-update on changes

---

🔄 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}