core-tests

A reusable library that provides CLI commands for running unittest-based tests and generating code coverage reports. It wraps Python’s built-in unittest framework and coverage into a Click command group so consuming projects can use python manager.py run-tests and python manager.py run-coverage without duplicating that logic across every project in the ecosystem.

This library is intentionally scoped to unittest and coverage. If your project requires pytest-specific features (fixtures, parametrize, plugins, parallel execution), install pytest directly or via core-dev-tools and invoke it standalone — it is a better fit for that use case than routing it through this abstraction layer.

Installation

Install from PyPI using pip:

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

Features

• Unified CLI abstraction: Expose run-tests and run-coverage in any project without duplicating boilerplate — just wire cli_tests into your CommandCollection.

• Flexible Test Discovery: Supports multiple file patterns out of the box:

  • test_*.py (standard pattern)

  • *_test.py (alternative pattern)

  • tests_*.py (custom pattern)

• Custom Pattern Support: Override discovery with --pattern for non-standard file layouts.

• Enforced Coverage: run-coverage applies the fail_under setting of your coverage configuration, or --fail-under for a single run, and exits non-zero when the total is below it.

• CI-ready Reports: Writes coverage.xml (Cobertura, relative paths) beside the HTML report, so a CI platform can annotate a merge request diff, and the JUnit XML of the results to reports/, so it can show a test report instead of console output.

• Test Organization: Target specific test directories (unit, integration, functional, etc.) via --test-type.

• Branch Coverage Reports: Generate branch-level coverage reports and optional HTML output.

• DRY principle: One implementation shared across all projects in the ecosystem.

How to Use

Create a manager.py file in your project root to integrate the test commands:

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

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

This setup provides two commands:

• run-tests: Execute unittest-based test suites

• run-coverage: Generate code coverage reports

Example usage:

python manager.py run-tests --test-type unit
python manager.py run-coverage

Available Commands

# Run unit tests (default)
python manager.py run-tests --test-type unit

# Run integration tests
python manager.py run-tests --test-type integration

# Run tests with a custom file pattern
python manager.py run-tests --test-type functional --pattern "*.py"

# Run tests in a custom folder
python manager.py run-tests --test-type "custom_folder"

python manager.py run-coverage
python manager.py run-coverage --save-report false
python manager.py run-coverage --fail-under 90

Quick Start

pip install --upgrade pip
pip install virtualenv

virtualenv --python=python3.12 .venv

source .venv/bin/activate

pip install -e ".[dev]"

python manager.py run-tests --test-type unit
python manager.py run-tests --test-type integration
python manager.py run-tests --test-type functional --pattern "*.py"
python manager.py run-coverage

pytest tests/unit/
pytest -n auto --cov=your_package --cov-report=html

pip install pytest pytest-xdist pytest-cov
# or
pip install ".[dev]"  # if core-dev-tools includes pytest

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Write tests for new functionality

4. Ensure all tests pass: python manager.py run-tests --test-type unit

5. Run linting: pylint core_tests

6. Run security checks: bandit -r core_tests

7. Submit a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links

• Documentation: https://core-tests.readthedocs.io/en/latest/

• Repository: https://gitlab.com/bytecode-solutions/core/core-tests

• Issues: https://gitlab.com/bytecode-solutions/core/core-tests/-/issues

• Changelog: https://gitlab.com/bytecode-solutions/core/core-tests/-/blob/master/CHANGELOG.md

• PyPI: https://pypi.org/project/core-tests/

Support

For questions or support, please open an issue on GitLab or contact the maintainers.

Authors

• Alejandro Cora González - Initial work - alek.cora.glez@gmail.com