Metadata-Version: 2.3
Name: hop3-testing
Version: 0.4.0b1
Summary: Testing utilities for Hop3
Author: Stefane Fermigier
Author-email: Stefane Fermigier <sf@abilian.com>
Requires-Dist: hop3-cli
Requires-Dist: pytest>=8.0.0
Requires-Dist: docker>=7.0.0
Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
Requires-Dist: devtools>=0.12.2
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: httpcore>=1.0.6
Requires-Dist: httpx>=0.27.2
Requires-Dist: paramiko>=2.11.0,<3.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Python: >=3.10, <4
Description-Content-Type: text/markdown

# 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

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

## Quick Start

```bash
# 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:

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

### Remote Target

Runs tests against a remote Hop3 server:

```bash
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

```python
# 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

```bash
# From package directory
uv run pytest tests/ -v

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

### Code quality

```bash
uv run ruff check src/
uv run ruff format src/
```

## Documentation

- **Testing Strategy**: [Testing guide](../../docs/src/dev/testing-strategy.md)
- **System Architecture**: [Architecture overview](../../docs/src/dev/architecture.md)
- **Package Internals**: [Deep-dive documentation](./docs/internals.md)

## Related Packages

- [hop3-server](../hop3-server/) - The server being tested
- [hop3-cli](../hop3-cli/) - CLI used for deployments in tests

## License

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