Metadata-Version: 2.4
Name: core-tests
Version: 2.1.0
Summary: It contains common elements for testing purposes...
Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
Maintainer: Alejandro Cora González
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/bytecode-solutions/core/core-tests
Project-URL: Repository, https://gitlab.com/bytecode-solutions/core/core-tests
Project-URL: Documentation, https://core-tests.readthedocs.io/en/latest/
Project-URL: Issues, https://gitlab.com/bytecode-solutions/core/core-tests/-/issues
Project-URL: Changelog, https://gitlab.com/bytecode-solutions/core/core-tests/-/blob/master/CHANGELOG.md
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: click>=8.1.8
Requires-Dist: coverage>=7.7.1
Requires-Dist: environs>=14.1.1
Provides-Extra: dev
Requires-Dist: core-dev-tools>=2.0.0; extra == "dev"
Dynamic: license-file

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.

===============================================================================

.. image:: https://img.shields.io/pypi/pyversions/core-tests.svg
    :target: https://pypi.org/project/core-tests/
    :alt: Python Versions

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-tests/-/blob/main/LICENSE
    :alt: License

.. image:: https://gitlab.com/bytecode-solutions/core/core-tests/badges/release/pipeline.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-tests/-/pipelines
    :alt: Pipeline Status

.. image:: https://readthedocs.org/projects/core-tests/badge/?version=latest
    :target: https://readthedocs.org/projects/core-tests/
    :alt: Docs Status

.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security

|


Installation
===============================================================================

Install from PyPI using pip:

.. code-block:: bash

    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:

.. code-block:: python

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

.. code-block:: bash

    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:**

.. code-block:: bash

    # 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:**

.. code-block:: bash

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


Quick Start
===============================================================================

Setting Up Environment
-------------------------------------------------------------------------------

1. Install required libraries:

.. code-block:: bash

    pip install --upgrade pip
    pip install virtualenv

2. Create Python virtual environment:

.. code-block:: bash

    virtualenv --python=python3.12 .venv

3. Activate the virtual environment:

.. code-block:: bash

    source .venv/bin/activate

4. Install the package:

.. code-block:: bash

    pip install -e ".[dev]"


Tests and Coverage
-------------------------------------------------------------------------------

.. code-block:: bash

    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:

.. code-block:: bash

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

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

.. code-block:: bash

    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
