Skill: Run Tests

Purpose

Execute the test suite for anyformat-backend services in a Dockerized environment, ensuring code changes are validated against the full test infrastructure including database, message broker, and object storage dependencies.

When to use this skill

• After implementing or modifying backend logic, models, or API endpoints.
• When debugging a failing test or investigating test behavior.
• Before committing code to verify no regressions were introduced.
• When validating that a bug fix resolves the reported issue.

Primary command

docker-compose run --rm --remove-orphans anyformat-core pytest tests/ -vvv -n auto --maxfail=1

Flag breakdown

Service-specific test commands

anyformat-core (Dramatiq workers)

# Full test suite
docker-compose run --rm --remove-orphans anyformat-core pytest tests/ -vvv -n auto --maxfail=1

# Exclude LLM and minio-dependent tests
docker-compose run --rm --remove-orphans anyformat-core pytest tests/ -vvv -n auto -m "not llm and not minio"

Backend (Django)

docker-compose run --rm backend pytest -n auto

External API

# Unit tests only
docker-compose run --rm external-api pytest -k unit -n auto

# All tests
docker-compose run --rm external-api pytest

Test markers

Filter tests using pytest markers:

Example usage

# Run only unit tests
docker-compose run --rm --remove-orphans anyformat-core pytest tests/ -m unit -vvv

# Skip tests requiring external services
docker-compose run --rm --remove-orphans anyformat-core pytest tests/ -m "not llm and not minio" -vvv -n auto

Running specific tests

# Single test file
docker-compose run --rm --remove-orphans anyformat-core pytest tests/test_specific.py -vvv

# Single test function
docker-compose run --rm --remove-orphans anyformat-core pytest tests/test_specific.py::test_function_name -vvv

# Tests matching a pattern
docker-compose run --rm --remove-orphans anyformat-core pytest tests/ -k "keyword" -vvv

Prerequisites

Ensure Docker services are running:

# Start infrastructure services
docker-compose up -d postgres redis rabbitmq minio

# Or start all services
docker-compose up -d

Infrastructure dependencies

The test environment requires:

• postgres: PostgreSQL 16.4 database
• redis: Caching and session storage
• rabbitmq: Message broker for async tasks
• minio: S3-compatible object storage (for tests marked minio)
• litellm: LLM API proxy (for tests marked llm)

Interpreting results

Success output

==================== X passed in Y.YYs ====================

Failure output

Look for:

1. FAILED lines indicating which tests failed
2. AssertionError or exception details
3. Short test summary at the end listing all failures

Common failure patterns

Debugging failing tests

# Run with print statements visible
docker-compose run --rm --remove-orphans anyformat-core pytest tests/test_file.py -vvv -s

# Run with debugger (drops into pdb on failure)
docker-compose run --rm --remove-orphans anyformat-core pytest tests/test_file.py --pdb

# Run without parallelization for clearer output
docker-compose run --rm --remove-orphans anyformat-core pytest tests/test_file.py -vvv --maxfail=1

Verification checklist

The skill is complete when:

• All targeted tests pass (or expected failures are documented)
• No infrastructure errors (connection refused, timeouts)
• Test output is reviewed for warnings that may indicate issues
• Any new test failures are investigated before proceeding

Safety notes

• Tests run in isolated containers and do not affect production data.
• The --rm flag ensures containers are cleaned up after runs.
• Use --remove-orphans to prevent container accumulation from interrupted runs.
• If tests modify shared state, run them without -n auto to avoid race conditions.