Available Commands
===============================================================================

The ``core-tests`` library provides two CLI commands for running tests
and generating coverage reports.


run-tests
-------------------------------------------------------------------------------

Runs ``unittest``-based tests in a specific directory.

.. code-block:: bash

    python manager.py run-tests [OPTIONS]


Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``--test-type``
    Folder name under the ``./tests`` directory containing test files.

    * **Type**: string
    * **Default**: ``unit``
    * **Examples**: ``unit``, ``integration``, ``functional``

``--pattern``
    File glob pattern passed to ``TestLoader.discover``.

    * **Type**: string
    * **Default**: ``tests_*.py`` — triggers discovery across all three
      built-in patterns: ``test_*.py``, ``*_test.py``, and ``tests_*.py``.
    * **Override**: any other ``*.py`` glob runs a single discovery pass
      with that pattern (e.g. ``--pattern "test_*.py"``).


Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run unit tests (default):

.. code-block:: bash

    python manager.py run-tests

Run integration tests:

.. code-block:: bash

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

Run tests with a custom pattern:

.. code-block:: bash

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

Run tests in a custom folder:

.. code-block:: bash

    python manager.py run-tests --test-type "my_custom_tests"


run-coverage
-------------------------------------------------------------------------------

Runs all tests across all test directories and generates a coverage report.

.. code-block:: bash

    python manager.py run-coverage [OPTIONS]


Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``--save-report``
    Save HTML and data coverage reports to disk.

    * **Type**: boolean
    * **Default**: ``True``
    * **Example**: ``--save-report false``


Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Generate coverage report:

.. code-block:: bash

    python manager.py run-coverage

Generate coverage without saving the HTML report:

.. code-block:: bash

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

The HTML report is written to the ``htmlcov/`` directory. Open
``htmlcov/index.html`` in your browser to view the detailed report.


Test Discovery
-------------------------------------------------------------------------------

By default, ``run-tests`` and ``run-coverage`` discover test files using the
``tests_*.py`` sentinel, which expands to all three built-in patterns:

* ``test_*.py``
* ``*_test.py``
* ``tests_*.py``

Supply ``--pattern`` with any other glob to target a specific naming convention
instead. Tests that connect to real external services should use a name outside
these patterns (e.g. ``check_*.py``) so they are not picked up automatically.


Advanced Usage
-------------------------------------------------------------------------------

Combining with CI/CD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use these commands in your CI/CD pipeline:

.. code-block:: yaml

    # .gitlab-ci.yml example
    test:
      script:
        - pip install core-tests
        - python manager.py run-tests
        - python manager.py run-coverage
      coverage: '/TOTAL.*\s+(\d+%)$/'


Using pytest directly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For pytest-specific features (fixtures, parametrize, parallel execution),
run ``pytest`` directly after installing it:

.. code-block:: bash

    # Install pytest separately
    pip install pytest pytest-xdist pytest-cov

    # Run with parallel execution and coverage
    pytest -n auto --cov=your_package --cov-report=html


Exit Codes
-------------------------------------------------------------------------------

The commands use standard exit codes:

* ``0`` — All tests passed
* ``1`` — One or more tests failed or an error occurred

You can use these exit codes in scripts:

.. code-block:: bash

    if python manager.py run-tests --test-type unit; then
        echo "Tests passed!"
    else
        echo "Tests failed!"
        exit 1
    fi