Quick Start Guide

Get started with socialseed-e2e in 15 minutes! This guide will walk you through creating your first API testing project from scratch.

⏱️ Time Required: 15 minutes 📋 Prerequisites: socialseed-e2e installed (see Installation Guide)

Table of Contents

Overview
What You’ll Build
Step 1: Project Initialization
Step 2: Understanding the Project Structure
Step 3: Configure Your API
Step 4: Create Your First Service
Step 5: Create Your First Test
Step 6: Run Your Tests
Step 7: Add More Tests
Next Steps
Troubleshooting

Overview

In this quick start guide, you’ll:

✅ Initialize a new testing project
✅ Configure API endpoints
✅ Create a service test suite
✅ Write your first API test
✅ Run tests and see results
✅ Chain multiple tests together

What You’ll Build

You’ll create a simple test suite for a Users API with these endpoints:

POST /auth/login - User authentication
GET /users/me - Get current user profile

Final Result: A working test suite that logs in a user and retrieves their profile.

Step 1: Project Initialization

Let’s create your first testing project!

Command

# Create a new directory for your project
mkdir my-api-tests
cd my-api-tests

# Initialize the project
e2e init

What Happens

🚀 Initializing socialseed-e2e project...

📁 Creating directory structure...
   ✓ services/
   ✓ tests/
   ✓ .github/workflows/

📄 Creating configuration files...
   ✓ e2e.conf
   ✓ .gitignore
   ✓ README.md

🎉 Project initialized successfully!

Next steps:
   1. Edit e2e.conf to configure your API
   2. Run 'e2e new-service <name>' to create a service
   3. Run 'e2e new-test <name> --service <service>' to create tests
   4. Run 'e2e run' to execute your tests

Files Created

my-api-tests/
├── e2e.conf              # Main configuration file
├── .gitignore            # Git ignore rules
├── README.md             # Project readme
├── services/             # Your service test implementations
│   └── __init__.py
└── .github/
    └── workflows/        # CI/CD templates
        └── e2e-tests.yml

⏱️ Time elapsed: ~30 seconds

Step 2: Understanding the Project Structure

Before continuing, let’s understand what each component does:

Configuration File (`e2e.conf`)

This is the heart of your testing project. It defines:

General settings (environment, timeouts)
Service endpoints to test
Test execution parameters

Services Directory (`services/`)

Each subdirectory here represents an API service you want to test:

services/
├── users-api/           # Tests for Users API
│   ├── __init__.py
│   ├── users_api_page.py    # Service page class
│   ├── data_schema.py       # DTOs and constants
│   └── modules/             # Test modules
│       ├── 01_login.py
│       └── 02_get_profile.py
└── __init__.py

The Service Page Pattern

Service Page: Python class that extends BasePage
Encapsulates: HTTP methods, authentication, base URL
Benefit: Reusable across all tests for that service

Step 3: Configure Your API

Now let’s configure your API endpoints in e2e.conf.

Open e2e.conf

# Using your favorite editor
code e2e.conf    # VS Code
# or
vim e2e.conf     # Vim
# or
nano e2e.conf    # Nano

Edit the Configuration

Replace the default configuration with this:

general:
  environment: dev
  timeout: 30000
  verbose: true

services:
  users-api:
    name: users-api
    base_url: http://localhost:8080
    health_endpoint: /health
    timeout: 5000
    required: true

logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Configuration Explained

Setting	Description	Value
`environment`	Current environment	`dev`
`timeout`	Default request timeout (ms)	`30000` (30s)
`verbose`	Show detailed output	`true`
`base_url`	API base URL	`http://localhost:8080`
`health_endpoint`	Health check endpoint	`/health`
`required`	Fail if service is unavailable	`true`

Verify Configuration

e2e config

Expected Output:

📋 Configuration Summary
═══════════════════════════════════════════════════

Environment: dev
Timeout: 30000ms
Verbose: true

Services:
───────────────────────────────────────────────────
users-api (required)
  Base URL: http://localhost:8080
  Health: /health
  Timeout: 5000ms

✓ Configuration is valid

⏱️ Time elapsed: ~2 minutes

Step 4: Create Your First Service

A “service” in socialseed-e2e represents an API you want to test.

Command

e2e new-service users-api

What Happens

🆕 Creating new service: users-api

📁 Creating directory structure...
   ✓ services/users-api/
   ✓ services/users-api/modules/

📄 Creating service files...
   ✓ services/users-api/__init__.py
   ✓ services/users-api/users_api_page.py
   ✓ services/users-api/data_schema.py
   ✓ services/users-api/modules/__init__.py

🎨 Generating from templates...
   ✓ Service page class
   ✓ Data schema definitions
   ✓ Module structure

✅ Service 'users-api' created successfully!

Next steps:
   1. Review and customize users_api_page.py
   2. Add constants to data_schema.py
   3. Run 'e2e new-test <name> --service users-api' to create tests

Files Created

services/users-api/
├── __init__.py              # Makes it a Python package
├── users_api_page.py        # Service page class (main file)
├── data_schema.py           # Constants and DTOs
└── modules/                 # Test modules go here
    └── __init__.py

Review the Service Page

Open services/users-api/users_api_page.py:

"""Users API Service Page.

This module provides a service page for testing the Users API.
"""

from typing import TYPE_CHECKING

from socialseed_e2e import BasePage

if TYPE_CHECKING:
    from playwright.sync_api import APIResponse


class UsersApiPage(BasePage):
    """Service page for Users API testing.

    This class provides methods for interacting with the Users API,
    including authentication, user management, and profile operations.

    Usage:
        page = UsersApiPage(config)
        response = page.post("/auth/login", json=credentials)
    """

    def __init__(self, config: dict):
        """Initialize the Users API page.

        Args:
            config: Service configuration from e2e.conf
        """
        super().__init__(config)
        self.auth_token: str = None
        self.current_user: dict = None

Key Points:

Extends BasePage (provides HTTP methods, retry logic, etc.)
Has access to service configuration from e2e.conf
Can store state (like auth_token) between tests

⏱️ Time elapsed: ~4 minutes

Step 5: Create Your First Test

Now let’s create a test that checks if the API is healthy.

Command

e2e new-test health_check --service users-api

What Happens

🆕 Creating new test: health_check

📄 Generating test module...
   ✓ services/users-api/modules/01_health_check.py

🎨 Applying template...
   ✓ Test structure
   ✓ Docstrings
   ✓ Type hints

✅ Test 'health_check' created successfully!

The test has been added to the execution queue.
Run 'e2e run --service users-api' to execute it.

File Created

services/users-api/modules/01_health_check.py:

"""Health Check Test for Users API.

This test verifies that the Users API is running and accessible.
"""

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from playwright.sync_api import APIResponse
    from ..users_api_page import UsersApiPage


def run(users_api: 'UsersApiPage') -> 'APIResponse':
    """Test that the Users API health endpoint returns 200.

    This test checks if the API is running and responding correctly.

    Args:
        users_api: Instance of UsersApiPage with service configuration

    Returns:
        APIResponse: The HTTP response from the health endpoint
    """
    print("🔍 Checking API health...")

    # Make the HTTP request
    response = users_api.get("/health")

    # Assert the response is successful
    if response.status == 200:
        print("✅ API is healthy!")
    else:
        print(f"❌ API health check failed: {response.status}")
        raise AssertionError(f"Expected 200, got {response.status}")

    return response

Understanding the Test Structure

def run(users_api: 'UsersApiPage') -> 'APIResponse':

Function name: Must be run
Parameter: Service page instance (injected by framework)
Return type: APIResponse from Playwright
State: Can store data in users_api for next test

Customize the Test

Let’s make it more interesting. Edit the file:

"""Health Check Test for Users API.

This test verifies that the Users API is running and accessible.
"""

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from playwright.sync_api import APIResponse
    from ..users_api_page import UsersApiPage


def run(users_api: 'UsersApiPage') -> 'APIResponse':
    """Test that the Users API health endpoint returns 200.

    Args:
        users_api: Instance of UsersApiPage

    Returns:
        APIResponse: The HTTP response
    """
    print("🏥 Checking Users API health...")

    # Test the health endpoint
    response = users_api.get("/health")

    # Verify response
    if response.status == 200:
        data = response.json()
        print(f"✅ API Status: {data.get('status', 'OK')}")
        print(f"✅ Service: {data.get('service', 'unknown')}")
        print(f"✅ Version: {data.get('version', 'unknown')}")
    else:
        print(f"❌ Health check failed with status: {response.status}")
        print(f"Response: {response.text()}")
        raise AssertionError(f"Health check failed: {response.status}")

    return response

⏱️ Time elapsed: ~8 minutes

Step 6: Run Your Tests

Time to see your test in action!

Command

e2e run

Expected Output (Success)

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

📋 Configuration: e2e.conf
🌍 Environment: dev
⏱️  Timeout: 30000ms

🔍 Discovering services...
   ✓ Found 1 service: users-api

📦 Service: users-api
───────────────────────────────────────────────────
🔗 Base URL: http://localhost:8080
🏥 Health Check: /health

🧪 Running 1 test module(s)

[1/1] 01_health_check.py
🏥 Checking Users API health...
✅ API Status: healthy
✅ Service: users-api
✅ Version: 1.0.0
✅ PASSED (0.42s)

───────────────────────────────────────────────────
✅ All tests passed! (1/1)
⏱️  Total Duration: 0.45s

═══════════════════════════════════════════════════
🎉 Test run completed successfully!

Expected Output (API Not Running)

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

📋 Configuration: e2e.conf
🌍 Environment: dev

🔍 Discovering services...
   ✓ Found 1 service: users-api

📦 Service: users-api
───────────────────────────────────────────────────
⚠️  Service health check failed
   URL: http://localhost:8080/health
   Error: Connection refused

❌ Required service 'users-api' is not available
   Set 'required: false' in e2e.conf to skip this check

═══════════════════════════════════════════════════
💥 Test run failed: Service unavailable

Using the Mock API

If you don’t have a real API running, use the built-in Mock API:

Terminal 1:

python tests/fixtures/mock_api.py

Terminal 2:

cd my-api-tests
e2e run

Update e2e.conf to use mock API:

services:
  users-api:
    name: users-api
    base_url: http://localhost:8765  # Mock API port
    health_endpoint: /health
    timeout: 5000
    required: true

⏱️ Time elapsed: ~10 minutes

Step 7: Add More Tests

Let’s create a more complex test that chains with the first one.

Create Login Test

e2e new-test login --service users-api

This creates services/users-api/modules/02_login.py:

Edit it to:

"""Login Test for Users API.

This test authenticates a user and stores the token for subsequent tests.
"""

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from playwright.sync_api import APIResponse
    from ..users_api_page import UsersApiPage


def run(users_api: 'UsersApiPage') -> 'APIResponse':
    """Test user login and store authentication token.

    This test:
    1. Sends login credentials to /auth/login
    2. Extracts the auth token from response
    3. Stores token in users_api for other tests to use

    Args:
        users_api: Instance of UsersApiPage

    Returns:
        APIResponse: The login response
    """
    print("🔐 Attempting user login...")

    # Prepare credentials
    credentials = {
        "email": "test@example.com",
        "password": "secret123"
    }

    # Make login request
    response = users_api.post("/auth/login", json=credentials)

    # Verify and extract token
    if response.status == 200:
        data = response.json()
        users_api.auth_token = data["token"]
        users_api.current_user = data["user"]

        print(f"✅ Login successful!")
        print(f"   Token: {users_api.auth_token[:20]}...")
        print(f"   User: {users_api.current_user['email']}")
    else:
        print(f"❌ Login failed: {response.status}")
        print(f"   Response: {response.text()}")
        raise AssertionError(f"Login failed: {response.status}")

    return response

Create Profile Test

e2e new-test get_profile --service users-api

Edit services/users-api/modules/03_get_profile.py:

"""Get Profile Test for Users API.

This test retrieves the current user's profile using the auth token
from the previous login test.
"""

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from playwright.sync_api import APIResponse
    from ..users_api_page import UsersApiPage


def run(users_api: 'UsersApiPage') -> 'APIResponse':
    """Test retrieving user profile with authentication.

    This test uses the auth_token stored by the login test to
    make an authenticated request to /users/me.

    Args:
        users_api: Instance of UsersApiPage (with auth_token from login)

    Returns:
        APIResponse: The profile response
    """
    print("👤 Retrieving user profile...")

    # Check if we have auth token from previous test
    if not users_api.auth_token:
        raise AssertionError("No auth token found. Run login test first.")

    # Set authorization header
    headers = {
        "Authorization": f"Bearer {users_api.auth_token}"
    }

    # Make authenticated request
    response = users_api.get("/users/me", headers=headers)

    # Verify response
    if response.status == 200:
        profile = response.json()
        print(f"✅ Profile retrieved!")
        print(f"   Name: {profile.get('name', 'N/A')}")
        print(f"   Email: {profile.get('email', 'N/A')}")
        print(f"   Role: {profile.get('role', 'N/A')}")
    else:
        print(f"❌ Failed to get profile: {response.status}")
        raise AssertionError(f"Profile retrieval failed: {response.status}")

    return response

Run All Tests

e2e run --service users-api

Expected Output:

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

📦 Service: users-api
───────────────────────────────────────────────────
🧪 Running 3 test module(s)

[1/3] 01_health_check.py
🏥 Checking Users API health...
✅ API Status: healthy
✅ PASSED (0.42s)

[2/3] 02_login.py
🔐 Attempting user login...
✅ Login successful!
   Token: eyJhbGciOiJIUzI1Ni...
   User: test@example.com
✅ PASSED (0.38s)

[3/3] 03_get_profile.py
👤 Retrieving user profile...
✅ Profile retrieved!
   Name: Test User
   Email: test@example.com
   Role: user
✅ PASSED (0.35s)

───────────────────────────────────────────────────
✅ All tests passed! (3/3)
⏱️  Total Duration: 1.15s

Key Concept: Tests run in alphabetical order (01_, 02_, 03_) and share state through the users_api object!

⏱️ Time elapsed: ~15 minutes ✅

Next Steps

Congratulations! You’ve successfully:

✅ Created a testing project
✅ Configured an API service
✅ Written 3 different tests
✅ Ran tests and saw results
✅ Learned about test chaining

Continue Learning

Writing Tests - Learn advanced test patterns
Configuration - Deep dive into e2e.conf options
CLI Reference - All available commands
Mock API - Test without a real API

Practice Exercises

Try these challenges to reinforce your learning:

Exercise 1: Add Error Handling Test Create a test that checks what happens with invalid credentials.

Exercise 2: Add Data Validation Test Create a test that verifies the response JSON structure.

Exercise 3: Test Multiple Services Add another service to your e2e.conf and create tests for it.

Example Solutions

Click to see Exercise 1 solution

e2e new-test login_error --service users-api

def run(users_api: 'UsersApiPage') -> 'APIResponse':
    """Test login with invalid credentials."""
    print("🔐 Testing login with invalid credentials...")

    credentials = {
        "email": "invalid@example.com",
        "password": "wrongpassword"
    }

    response = users_api.post("/auth/login", json=credentials)

    if response.status == 401:
        print("✅ Correctly rejected invalid credentials")
    else:
        raise AssertionError(f"Expected 401, got {response.status}")

    return response

Troubleshooting

“e2e command not found”

Problem: After installation, the e2e command is not recognized.

Solution:

# Make sure you're in a virtual environment
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Or use the full path
/path/to/venv/bin/e2e

“Connection refused” Error

Problem: Tests fail with “Connection refused” to localhost:8080.

Solution:

Check if your API is running on port 8080
Update e2e.conf with the correct base_url
Or use the Mock API: python tests/fixtures/mock_api.py

Tests Not Found

Problem: e2e run says “No tests found”.

Solution:

# Check test file naming (must start with numbers: 01_, 02_, etc.)
ls services/users-api/modules/

# Check for syntax errors in test files
python -m py_compile services/users-api/modules/*.py

Import Errors

Problem: ModuleNotFoundError when running tests.

Solution:

# Reinstall in editable mode
pip install -e ".[dev]"

# Check that you're in the right directory
pwd  # Should be in project root or my-api-tests/

Summary

What You Learned:

Project Structure: e2e.conf + services/ + tests/
Service Pages: Classes that extend BasePage
Test Modules: Files in services/<name>/modules/
Test Chaining: Tests share state through service page
Running Tests: e2e run with beautiful output

Commands Reference:

e2e init                    # Initialize project
e2e new-service <name>      # Create service
e2e new-test <name> --service <svc>  # Create test
e2e run                     # Run all tests
e2e run --service <name>    # Run specific service
e2e config                  # Show configuration
e2e doctor                  # Verify installation

🎉 You're now ready to test APIs like a pro!

Next: Writing Tests → Configuration → CLI Reference

Quick Start Guide

Table of Contents

Overview

What You’ll Build

Step 1: Project Initialization

Command

What Happens

Files Created

Step 2: Understanding the Project Structure

Configuration File (e2e.conf)

Services Directory (services/)

The Service Page Pattern

Step 3: Configure Your API

Open e2e.conf

Edit the Configuration

Configuration Explained

Verify Configuration

Step 4: Create Your First Service

Command

What Happens

Files Created

Review the Service Page

Step 5: Create Your First Test

Command

What Happens

File Created

Understanding the Test Structure

Customize the Test

Step 6: Run Your Tests

Command

Expected Output (Success)

Expected Output (API Not Running)

Using the Mock API

Step 7: Add More Tests

Create Login Test

Create Profile Test

Run All Tests

Next Steps

Continue Learning

Practice Exercises

Example Solutions

Troubleshooting

“e2e command not found”

“Connection refused” Error

Tests Not Found

Import Errors

Summary

Configuration File (`e2e.conf`)

Services Directory (`services/`)