run-tests
Run the test suite for anyformat-backend services using Docker Compose. Use when you need to validate code changes, debug failing tests, or verify that implementations work correctly before committing.
When & Why to Use This Skill
This Claude skill automates the execution of comprehensive test suites for backend services using Docker Compose and pytest. It streamlines the validation of code changes by managing complex infrastructure dependencies like databases and message brokers, ensuring high-quality deployments and rapid debugging through containerized isolation.
Use Cases
- Pre-commit validation: Automatically run the full test suite to ensure new code changes don't introduce regressions before committing to the repository.
- Targeted debugging: Execute specific test files or functions with increased verbosity and debugger support to quickly identify and fix backend logic errors.
- Integration testing: Validate interactions between backend services and infrastructure components like PostgreSQL, Redis, and RabbitMQ in an isolated Docker environment.
- Environment-specific testing: Use pytest markers to run or skip tests requiring external dependencies like MinIO or LLM APIs based on the current development context.
- Parallel test execution: Speed up the feedback loop by running tests in parallel across multiple CPU cores using pytest-xdist integration.
| name | run-tests |
|---|---|
| description | Run the test suite for anyformat-backend services using Docker Compose. Use when you need to validate code changes, debug failing tests, or verify that implementations work correctly before committing. |
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
| Flag | Purpose |
|---|---|
--rm |
Remove the container after the test run completes |
--remove-orphans |
Clean up any orphaned containers from previous runs |
-vvv |
Maximum verbosity for detailed test output |
-n auto |
Parallel execution using all available CPU cores (pytest-xdist) |
--maxfail=1 |
Stop after the first failure for faster feedback |
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:
| Marker | Description |
|---|---|
unit |
Fast tests with no external dependencies |
smoke |
Integration tests requiring running services |
integration |
Full integration tests |
minio |
Requires AWS/MinIO credentials |
llm |
Requires LLM API access |
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:
- FAILED lines indicating which tests failed
- AssertionError or exception details
- Short test summary at the end listing all failures
Common failure patterns
| Pattern | Likely cause |
|---|---|
Connection refused |
Infrastructure services not running |
relation does not exist |
Database migrations not applied |
timeout |
Service startup delay or deadlock |
ModuleNotFoundError |
Missing dependency or import path issue |
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
--rmflag ensures containers are cleaned up after runs. - Use
--remove-orphansto prevent container accumulation from interrupted runs. - If tests modify shared state, run them without
-n autoto avoid race conditions.