.. core-tests documentation master file, created by
   sphinx-quickstart on Wed Mar 26 13:53:47 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

core-tests
===============================================================================

A reusable library that provides CLI commands for running ``unittest``-based
tests and generating code coverage reports. Consuming projects wire ``cli_tests``
into their own ``CommandCollection`` to expose ``run-tests`` and ``run-coverage``
without duplicating that logic, keeping the ecosystem **DRY**.

This library is intentionally scoped to ``unittest`` and ``coverage``.
If your project requires pytest-specific features, install ``pytest`` directly
or via ``core-dev-tools`` and invoke it standalone.

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

.. 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


Documentation Contents
-------------------------------------------------------------------------------

.. toctree::
   :maxdepth: 1
   :caption: Index:

   quickstart
   commands
   best_practices


Features
-------------------------------------------------------------------------------

* **Unittest abstraction**: Expose ``run-tests`` and ``run-coverage`` in any
  project without duplicating boilerplate.
* **Flexible Test Discovery**: Default pattern ``tests_*.py`` triggers discovery
  across all three built-in patterns: ``test_*.py``, ``*_test.py``, ``tests_*.py``.
* **Custom Pattern Support**: Override discovery with ``--pattern`` to target a
  specific file naming convention.
* **Test Organization**: Target specific directories (unit, integration,
  functional, etc.) via ``--test-type``.
* **Branch Coverage Reports**: Generate branch-level coverage reports and
  optional HTML output.
* **CLI Integration**: Easy integration via Click command collections.


Installation
-------------------------------------------------------------------------------

Install the package:

.. code-block:: bash

    pip install core-tests
    uv pip install core-tests  # Or using UV...
    pip install -e ".[dev]"    # For development...


How to Use
-------------------------------------------------------------------------------

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

.. code-block:: python

    from click.core import CommandCollection
    from core_tests.tests.runner import cli_tests

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

Run your tests:

.. code-block:: bash

    python manager.py run-tests
    python manager.py run-coverage


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``.
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


Indices and tables
-------------------------------------------------------------------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`