Quick Start#

This guide will help you get started with core-tests in just a few minutes.

Setting Up Your Project#

1. Install core-tests#

pip install core-tests
uv pip install core-tests  # Or using UV...

2. Create Project Structure#

Organize your tests in a tests directory:

your-project/
├── manager.py
├── tests/
│   ├── unit/
│   │   ├── tests_example.py
│   │   └── tests_another.py
│   ├── integration/
│   │   └── tests_integration.py
│   └── functional/
│       └── check_functional.py
└── your_package/
    └── __init__.py

3. Create Entry Point#

Create a manager.py file in your project root:

# manager.py
from click.core import CommandCollection
from core_tests.tests.runner import cli_tests

if __name__ == "__main__":
    cli = CommandCollection(sources=[cli_tests()])
    cli()

Running Your Tests#

python manager.py run-tests  # Default: unit tests
python manager.py run-tests --test-type unit
python manager.py run-tests --test-type integration
python manager.py run-tests --test-type functional
python manager.py run-tests --test-type functional --pattern "*.py"

Test File Patterns#

By default (--pattern tests_*.py), discovery runs across all three built-in patterns: test_*.py, *_test.py, and tests_*.py.

To target a specific naming convention, supply a different pattern:

python manager.py run-tests --test-type unit --pattern "test_*.py"
python manager.py run-tests --test-type unit --pattern "*.py"

Tests that connect to real external services should use a name outside these patterns (e.g. check_aws_*.py) so they are not discovered automatically.

Test Coverage#

python manager.py run-coverage                      # Run all tests and report coverage
python manager.py run-coverage --save-report false  # Skip saving HTML report

Using pytest directly#

unittest cannot discover standalone test_* functions or use pytest fixtures. If your project needs those features, install and invoke pytest directly — it is a better fit than routing it through this abstraction layer:

pip install pytest pytest-xdist
pytest .
pytest -n auto  # Run with all available processors

Next Steps#