hop3-testing 0.4.0b1

Testing utilities for Hop3

hop3-testing

Testing framework for Hop3 deployment validation.

Overview

hop3-testing provides utilities and fixtures for testing Hop3 deployments. It supports running tests against Docker containers or remote servers, with a catalog of test applications covering various languages and frameworks.

Features

• Multiple targets - Test against Docker containers or remote SSH servers
• App catalog - Pre-built test applications for various languages
• Deployment sessions - Automated deploy/verify/cleanup workflow
• pytest fixtures - Integration with pytest for E2E testing
• Category filtering - Run tests by language or framework

Installation

For development

# From workspace root
cd packages/hop3-testing
uv pip install -e ".[dev]"

Quick Start

# Test all apps on Docker
hop3-test --target docker

# Test specific app
hop3-test --target docker 010-flask-pip-wsgi

# Test against remote server
hop3-test --target remote --host server.example.com

# Test specific category
hop3-test --target docker --category python-simple

# List available apps
hop3-test --list-apps

Architecture

hop3-testing/
├── src/hop3_testing/
│   ├── main.py              # CLI entry point
│   ├── base.py              # Base test fixtures
│   ├── common.py            # Shared utilities
│   ├── apps/
│   │   ├── catalog.py       # App catalog management
│   │   └── deployment.py    # Deployment session handling
│   ├── targets/
│   │   ├── base.py          # Abstract target interface
│   │   ├── docker.py        # Docker container target
│   │   └── remote.py        # Remote SSH target
│   └── util/
│       ├── console.py       # Output formatting
│       └── backports.py     # Python compatibility
└── tests/

Test Targets

Docker Target

Runs tests in isolated Docker containers:

hop3-test --target docker --image ubuntu:24.04

Remote Target

Runs tests against a remote Hop3 server:

hop3-test --target remote --host server.example.com --ssh-key ~/.ssh/id_rsa

App Categories

Test applications are organized by category:

Category	Languages/Frameworks
python-simple	Flask, FastAPI, Django
python-complex	Multi-process, workers
nodejs	Express, Fastify
ruby	Sinatra, Rails
go	Fiber, Gin
rust	Actix-web, Axum
static	HTML, Hugo, Jekyll

Using with pytest

# conftest.py
from hop3_testing import DeploymentTarget, AppCatalog

@pytest.fixture(scope="session")
def deployment_target():
    """Provide a deployment target for tests."""
    return DockerTarget()

@pytest.fixture
def app_catalog():
    """Provide the test app catalog."""
    return AppCatalog()

# test_deployment.py
def test_flask_app(deployment_target, app_catalog):
    """Test Flask application deployment."""
    app = app_catalog.get("010-flask-pip-wsgi")

    with DeploymentSession(deployment_target, app) as session:
        session.deploy()
        assert session.verify_running()
        assert session.verify_http_response()

Development

Running tests

# From package directory
uv run pytest tests/ -v

# With coverage
uv run pytest tests/ --cov=hop3_testing

Code quality

uv run ruff check src/
uv run ruff format src/

Documentation

• Testing Strategy: Testing guide
• System Architecture: Architecture overview
• Package Internals: Deep-dive documentation

Related Packages

• hop3-server - The server being tested
• hop3-cli - CLI used for deployments in tests

License

Apache-2.0 - Copyright (c) 2024-2025, Abilian SAS