CLI Reference

Complete reference for the socialseed-e2e command-line interface.

Overview

The socialseed-e2e CLI provides a complete interface for managing E2E testing projects. It follows a workflow-based approach:

init → new-service → new-test → run

Global Options

All commands support these global options:

e2e [command] [options]

Available Global Options

Option	Short	Description
`--version`	`-V`	Show version number and exit
`--help`	`-h`	Show help message and exit

Usage Examples

# Show version
e2e --version

# Get help for specific command
e2e init --help
e2e run --help

Commands Reference

`init` - Initialize Project

Creates a new E2E testing project with the necessary structure.

Syntax

e2e init [directory] [options]

Arguments

Argument	Required	Default	Description
`directory`	No	`.`	Directory where to create the project

Options

Option	Short	Type	Default	Description
`--force`	-	flag	false	Overwrite existing files

Created Files and Directories

<directory>/
├── e2e.conf              # Main configuration file
├── .gitignore           # Git ignore rules
├── services/            # Service modules directory
├── tests/               # Test directory
└── .github/
    └── workflows/       # GitHub Actions workflows

Examples

# Initialize in current directory
e2e init

# Initialize in specific directory
e2e init ./my-api-tests

# Force overwrite existing files
e2e init --force

Output Example

🌱 Inicializando proyecto E2E en: /home/user/my-project

  ✓ Creado: services
  ✓ Creado: tests
  ✓ Creado: .github/workflows
  ✓ Creado: e2e.conf
  ✓ Creado: .gitignore

✅ Proyecto inicializado correctamente!

╭──────── 🚀 Empezar ─────────╮
│ 1. Edita e2e.conf para      │
│    configurar tu API        │
│ 2. Ejecuta: e2e new-service │
│    <nombre>                 │
│ 3. Ejecuta: e2e new-test    │
│    <nombre> --service <svc> │
│ 4. Ejecuta: e2e run para    │
│    correr tests             │
╰─────────────────────────────╯

`new-service` - Create Service

Creates a new service with complete scaffolding including page class, configuration, and data schema.

Syntax

e2e new-service <name> [options]

Arguments

Argument	Required	Description
`name`	Yes	Service name (e.g., `users-api`, `auth-service`)

Options

Option	Short	Type	Default	Description
`--base-url`	-	string	`http://localhost:8080`	Base URL for the service
`--health-endpoint`	-	string	`/health`	Health check endpoint

Created Files

services/<name>/
├── __init__.py              # Package initialization
├── <name>_page.py          # ServicePage class
├── config.py                # Service configuration
└── data_schema.py           # Data models and DTOs

Generated Classes

ServicePage: Extends BasePage with service-specific HTTP methods
ServiceConfig: Configuration class with base URL, timeouts, etc.
Data Models: Pydantic models for request/response validation

Examples

# Create basic service
e2e new-service users-api

# Create with custom base URL
e2e new-service payment-api --base-url https://api.payments.com/v1

# Create with custom health endpoint
e2e new-service auth-api --health-endpoint /api/health

# Full example
e2e new-service inventory --base-url http://localhost:3000 --health-endpoint /status

Output Example

🔧 Creando servicio: users-api

  ✓ Creado: services/users-api/
  ✓ Creado: services/users-api/modules/
  ✓ Creado: services/users-api/__init__.py
  ✓ Creado: services/users-api/modules/__init__.py
  ✓ Creado: services/users-api/users_api_page.py
  ✓ Creado: services/users-api/config.py
  ✓ Creado: services/users-api/data_schema.py
  ✓ Actualizado: e2e.conf

✅ Servicio 'users-api' creado correctamente!

╭─────── 🚀 Continuar ───────╮
│ 1. Edita                    │
│    services/users-api/data_ │
│    schema.py para definir   │
│    tus DTOs                 │
│ 2. Ejecuta: e2e new-test    │
│    <nombre> --service       │
│    users-api                │
│ 3. Ejecuta: e2e run         │
│    --service users-api      │
╰─────────────────────────────╯

`new-test` - Create Test Module

Creates a new test module within a service.

Syntax

e2e new-test <name> --service <service> [options]

Arguments

Argument	Required	Description
`name`	Yes	Test name (e.g., `login`, `create-user`)

Options

Option	Short	Type	Required	Description
`--service`	`-s`	string	Yes	Service name where to create the test
`--description`	`-d`	string	No	Test description

Test Naming Convention

Tests are automatically numbered with a two-digit prefix to control execution order:

modules/
├── 01_setup.py
├── 02_authentication.py
├── 03_create_user.py
└── 04_update_profile.py

Created File Structure

# services/<service>/modules/XX_<name>_flow.py

"""Test flow for <name>.

<description>
"""

from playwright.sync_api import APIResponse
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ..<service>_page import <Service>Page


def run(page: '<Service>Page') -> APIResponse:
    """Execute <name> test flow.

    Args:
        page: Service page instance

    Returns:
        APIResponse: Response from the test
    """
    # Implement test logic here
    pass

Examples

# Create test for users service
e2e new-test login --service users-api

# Create with description
e2e new-test create-order --service payment-api --description "Test order creation flow"

# Short option form
e2e new-test register -s auth-api -d "User registration test"

Output Example

📝 Creando test: login

  ✓ Creado: services/users-api/modules/01_login_flow.py

✅ Test 'login' creado correctamente!

╭────── 🚀 Implementar ──────╮
│ 1. Edita                    │
│    services/users-api/modul │
│    es/01_login_flow.py      │
│ 2. Implementa la lógica del │
│    test                     │
│ 3. Ejecuta: e2e run         │
│    --service users-api      │
╰─────────────────────────────╯

`run` - Execute Tests

Discovers and executes E2E tests.

Syntax

e2e run [options]

Options

Option	Short	Type	Default	Description
`--service`	`-s`	string	-	Filter by specific service
`--module`	`-m`	string	-	Filter by specific module
`--verbose`	`-v`	flag	false	Enable verbose output
`--output`	`-o`	choice	`text`	Output format: `text` or `json`

Examples

# Run all tests
e2e run

# Run tests for specific service
e2e run --service users-api
e2e run -s auth-api

# Run specific module
e2e run --module 01_login
e2e run -m 02_register

# Verbose mode
e2e run -v
e2e run --verbose --service payment-api

# JSON output
e2e run -o json
e2e run --output json --service inventory

# Combined options
e2e run -s users-api -m 01_login -v

Output Formats

Text Format (default):

🚀 socialseed-e2e v0.1.0
═══════════════════════════════════

📋 Configuración: /home/user/project/e2e.conf
🌍 Environment: dev

╭──────── Servicios Encontrados ────────╮
│  Servicio      │ Tests │ Estado      │
├────────────────┼───────┼─────────────┤
│  users-api     │   3   │ Ready       │
│  auth-api      │   2   │ Ready       │
│  payment-api   │   0   │ Empty       │
╰────────────────┴───────┴─────────────╯

JSON Format:

{
  "version": "0.1.0",
  "config": "/home/user/project/e2e.conf",
  "environment": "dev",
  "services": [
    {
      "name": "users-api",
      "tests": 3,
      "status": "ready"
    }
  ]
}

`doctor` - Verify Installation

Checks that the installation and dependencies are correctly configured.

Syntax

e2e doctor

Checks Performed

Check	Description
Python	Version 3.9+ required
Playwright	Library installation
Playwright CLI	Browser management tools
Pydantic	Data validation library
Configuration	`e2e.conf` existence
Directory Structure	`services/` and `tests/` existence

Examples

# Run diagnostic
e2e doctor

Output Example

Successful Check:

🏥 socialseed-e2e Doctor

╭────────── Verificación del Sistema ──────────╮
│  Componente       │ Versión/Estado │ Estado  │
├───────────────────┼────────────────┼─────────┤
│  Python           │ 3.11.4         │ ✓       │
│  Playwright       │ 1.40.0         │ ✓       │
│  Playwright CLI   │ Disponible     │ ✓       │
│  Pydantic         │ 2.5.0          │ ✓       │
│  Configuración    │ e2e.conf       │ ✓       │
│  Directorio       │ OK             │ ✓       │
│  services/        │                │         │
│  Directorio       │ OK             │ ✓       │
│  tests/           │                │         │
╰───────────────────┴────────────────┴─────────╯

✅ Todo está configurado correctamente!

Failed Checks:

🏥 socialseed-e2e Doctor

╭────────── Verificación del Sistema ──────────╮
│  Componente       │ Versión/Estado │ Estado  │
├───────────────────┼────────────────┼─────────┤
│  Python           │ 3.11.4         │ ✓       │
│  Playwright       │ No instalado   │ ✗       │
│  Playwright CLI   │ No disponible  │ ✗       │
│  Pydantic         │ 2.5.0          │ ✓       │
│  Configuración    │ e2e.conf no    │ ✗       │
│                   │ encontrado     │         │
╰───────────────────┴────────────────┴─────────╯

⚠ Se encontraron algunos problemas

Soluciones sugeridas:
  • Instala Playwright: pip install playwright
  • Instala browsers: playwright install chromium
  • Inicializa proyecto: e2e init

`config` - Show Configuration

Displays and validates the current configuration from e2e.conf.

Syntax

e2e config

Displayed Information

Configuration file path
Current environment
Timeout settings
Verbose mode status
Configured services table

Examples

# Show configuration
e2e config

Output Example

⚙️  Configuración E2E

📋 Configuración: /home/user/project/e2e.conf
🌍 Environment: dev
Timeout: 30000ms
Verbose: true

╭────────── Servicios Configurados ──────────╮
│  Nombre      │ Base URL              │ ... │
├──────────────┼───────────────────────┼─────┤
│  users-api   │ http://localhost:8080 │ ... │
│  auth-api    │ http://localhost:3000 │ ... │
╰──────────────┴───────────────────────┴─────╯

✅ Configuración válida

Error Output:

❌ Error de configuración: Missing required field: services

Ejecuta: e2e init para crear un proyecto

Error Messages and Solutions

Common Errors

E001: Not in E2E Project

❌ Error: No se encontró e2e.conf. ¿Estás en un proyecto E2E?
   Ejecuta: e2e init primero

Cause: Running new-service, new-test, or run outside an E2E project.

Solution:

e2e init

E002: Service Does Not Exist

❌ Error: El servicio 'users-api' no existe.
   Crea el servicio primero: e2e new-service users-api

Cause: Trying to create a test for a non-existent service.

Solution:

e2e new-service users-api
e2e new-test login --service users-api

E003: Service Already Exists

⚠ El servicio 'users-api' ya existe
¿Deseas continuar y sobrescribir archivos? [y/N]:

Cause: Attempting to create a service that already exists.

Solution:

Press y to overwrite
Or choose a different service name

E004: Configuration Error

❌ Error de configuración: <error details>

Common causes:

Invalid YAML syntax in e2e.conf
Missing required fields
Invalid values (e.g., non-integer timeout)

Solution:

Check e2e.conf syntax
Run e2e doctor for diagnostics
Regenerate with e2e init --force

E005: Missing Dependencies

❌ Error: playwright module not found

Solution:

pip install socialseed-e2e
playwright install chromium

Environment Variables

Framework Variables

Variable	Description	Default
`E2E_CONFIG_PATH`	Path to configuration file	`e2e.conf`
`E2E_ENVIRONMENT`	Override environment	From config
`E2E_VERBOSE`	Enable verbose logging	`false`

Playwright Variables

Variable	Description
`PLAYWRIGHT_BROWSERS_PATH`	Path to browser binaries
`DEBUG`	Enable Playwright debug mode

Usage Examples

# Use custom config file
export E2E_CONFIG_PATH=/path/to/custom.conf
e2e run

# Force verbose mode
export E2E_VERBOSE=true
e2e run

# Set environment
export E2E_ENVIRONMENT=staging
e2e run

Command Cheat Sheet

Quick Reference

# Project Setup
e2e init                                    # Initialize in current dir
e2e init ./my-project                       # Initialize in specific dir
e2e init --force                           # Overwrite existing

# Service Management
e2e new-service users-api                   # Create service
e2e new-service api --base-url http://...   # With custom URL
e2e new-service svc --health /status        # With custom health endpoint

# Test Creation
e2e new-test login --service users          # Create test
e2e new-test auth -s users -d "Login flow"  # With description

# Test Execution
e2e run                                     # Run all tests
e2e run -s users-api                        # Run specific service
e2e run -m 01_login                        # Run specific module
e2e run -v                                 # Verbose mode
e2e run -o json                            # JSON output

# Diagnostics
e2e doctor                                  # Check installation
e2e config                                  # Show configuration

# Help
e2e --help                                  # Global help
e2e <command> --help                       # Command help

Workflow Examples

New Project Workflow

# 1. Initialize
e2e init my-api-tests
cd my-api-tests

# 2. Configure
echo "Configure e2e.conf with your API details"

# 3. Create services
e2e new-service users-api --base-url https://api.example.com/v1
e2e new-service auth-api --base-url https://auth.example.com

# 4. Create tests
e2e new-test login --service auth-api
e2e new-test get-profile --service users-api

# 5. Run tests
e2e run

Daily Development Workflow

# Check setup
e2e doctor

# Run all tests
e2e run

# Run only modified service
e2e run -s users-api

# Debug specific test
e2e run -s users-api -m 03_update -v

CI/CD Workflow

# Install
e2e doctor || exit 1

# Run with JSON output for parsing
e2e run -o json > results.json

# Check results
jq '.success' results.json

Advanced Usage

Combining Options

# Multiple filters
e2e run --service users-api --module 01_login --verbose

# Short form
e2e run -s users-api -m 01_login -v

# JSON output with verbose
e2e run -s payment-api -o json -v

Scripting with CLI

#!/bin/bash

# Create services in batch
for service in users-api auth-api payment-api; do
    e2e new-service "$service"
done

# Run tests and capture output
if e2e run -o json > /tmp/results.json; then
    echo "Tests passed!"
else
    echo "Tests failed!"
    exit 1
fi

Tips and Best Practices

Always run e2e doctor after installation to verify setup
Use --force carefully - it will overwrite existing files
Name services descriptively - they become class names
Use verbose mode (-v) when debugging test issues
Check e2e config to verify your configuration is loaded correctly
Use JSON output for CI/CD integration and automation

CLI Reference

Overview

Global Options

Available Global Options

Usage Examples

Commands Reference

init - Initialize Project

Syntax

Arguments

Options

Created Files and Directories

Examples

Output Example

new-service - Create Service

Syntax

Arguments

Options

Created Files

Generated Classes

Examples

Output Example

new-test - Create Test Module

Syntax

Arguments

Options

Test Naming Convention

Created File Structure

Examples

Output Example

run - Execute Tests

Syntax

Options

Examples

Output Formats

doctor - Verify Installation

Syntax

Checks Performed

Examples

Output Example

config - Show Configuration

Syntax

Displayed Information

Examples

Output Example

Error Messages and Solutions

Common Errors

E001: Not in E2E Project

E002: Service Does Not Exist

E003: Service Already Exists

E004: Configuration Error

E005: Missing Dependencies

Environment Variables

Framework Variables

Playwright Variables

Usage Examples

Command Cheat Sheet

Quick Reference

Workflow Examples

New Project Workflow

Daily Development Workflow

CI/CD Workflow

Advanced Usage

Combining Options

Scripting with CLI

Tips and Best Practices

See Also

`init` - Initialize Project

`new-service` - Create Service

`new-test` - Create Test Module

`run` - Execute Tests

`doctor` - Verify Installation

`config` - Show Configuration