core-tests 2.1.0

It contains common elements for testing purposes...

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.

• 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-tests

Execute unittest-based test suites with flexible options:

Options:

• --test-type: Folder name under ./tests directory (e.g., unit, integration, functional). Default: unit

• --pattern: File pattern to match test files (e.g., *.py, test_*.py). Defaults to multi-pattern discovery.

Examples:

# 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"

run-coverage

Generate code coverage reports across all test directories:

Options:

• --save-report: Save HTML and data coverage reports to disk. Default: True

Examples:

python manager.py run-coverage
python manager.py run-coverage --save-report false

Quick Start

Setting Up Environment

1. Install required libraries:

pip install --upgrade pip
pip install virtualenv

2. Create Python virtual environment:

virtualenv --python=python3.12 .venv

3. Activate the virtual environment:

source .venv/bin/activate

4. Install the package:

pip install -e ".[dev]"

Tests and Coverage

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

Using pytest directly

unittest cannot discover standalone test_* functions or use pytest fixtures. If your project relies on those features, invoke pytest directly:

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

Install pytest via pip or through core-dev-tools:

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 - [e-mail]