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

This guide will help you get started with ``core-tests`` in just a few minutes.


Setting Up Your Project
-------------------------------------------------------------------------------


1. Install core-tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

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


2. Create Project Structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Organize your tests in a ``tests`` directory:

.. code-block:: text

    your-project/
    ├── manager.py
    ├── tests/
    │   ├── unit/
    │   │   ├── tests_example.py
    │   │   └── tests_another.py
    │   ├── integration/
    │   │   └── tests_integration.py
    │   └── functional/
    │       └── check_functional.py
    └── your_package/
        └── __init__.py


3. Create Entry Point
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a ``manager.py`` file in your project root:

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


Running Your Tests
-------------------------------------------------------------------------------

.. code-block:: bash

    python manager.py run-tests  # Default: unit tests
    python manager.py run-tests --test-type unit
    python manager.py run-tests --test-type integration
    python manager.py run-tests --test-type functional
    python manager.py run-tests --test-type functional --pattern "*.py"


Test File Patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default (``--pattern tests_*.py``), discovery runs across all three
built-in patterns: ``test_*.py``, ``*_test.py``, and ``tests_*.py``.

To target a specific naming convention, supply a different pattern:

.. code-block:: bash

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

Tests that connect to real external services should use a name outside these
patterns (e.g. ``check_aws_*.py``) so they are not discovered automatically.


Test Coverage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    python manager.py run-coverage                      # Run all tests and report coverage
    python manager.py run-coverage --save-report false  # Skip saving HTML report


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

``unittest`` cannot discover standalone ``test_*`` functions or use pytest
fixtures. If your project needs those features, install and invoke ``pytest``
directly — it is a better fit than routing it through this abstraction layer:

.. code-block:: bash

    pip install pytest pytest-xdist
    pytest .
    pytest -n auto  # Run with all available processors


Next Steps
-------------------------------------------------------------------------------

* Learn about all :doc:`commands` available
* Check out :doc:`best_practices` for optimization tips