============
Unit Testing
============
It is important to have unit-tests to verify that your CLI is behaving correctly.
For unit-testing, we will be using the defacto-standard python unit-testing library, pytest_.
This section demonstrates some common scenarios you may encounter when unit-testing your CLI app.

Lets make a small application that checks PyPI_ if a library name is available:

.. code-block:: python

   # pypi_checker.py
   import sys
   import urllib.error
   import urllib.request
   import cyclopts

   def _check_pypi_name_available(name):
       try:
           urllib.request.urlopen(f"https://pypi.org/pypi/{name}/json")
       except urllib.error.HTTPError as e:
           if e.code == 404:
               return True  # Package does not exist (name is available)
       return False  # Package exists (name is not available)

   app = cyclopts.App(
         config=[
            cyclopts.config.Env("PYPI_CHECKER_"),
            cyclopts.config.Json("config.json"),
         ],
   )

   @app.default
   def pypi_checker(name: str, *, silent: bool = False) -> bool:
       """Check if a package name is available on PyPI.

       Returns True if available; False otherwise.

       Parameters
       ----------
       name: str
           Name of the package to check.
       silent: bool
           Do not print anything to stdout.
       """
       is_available = _check_pypi_name_available(name)
       if not silent:
           if is_available:
               print(f"{name} is available.")
           else:
               print(f"{name} is not available.")
       return is_available

   if __name__ == "__main__":
       app()

Running the app from the console:

.. code-block:: console

   $ python pypi_checker.py --help
   Usage: pypi_checker COMMAND [ARGS] [OPTIONS]

   Check if a package name is available on PyPI.

   Returns True if available; False otherwise.

   ╭─ Commands ────────────────────────────────────────────────────────────────────────────────────────╮
   │ --help -h  Display this message and exit.                                                         │
   │ --version  Display application version.                                                           │
   ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
   ╭─ Parameters ──────────────────────────────────────────────────────────────────────────────────────╮
   │ *  NAME --name           Name of the package to check. [env var: PYPI_CHECKER_NAME] [required]    │
   │    --silent --no-silent  Do not print anything to stdout. [env var: PYPI_CHECKER_SILENT]          │
   │                          [default: False]                                                         │
   ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯

   $ python pypi_checker.py cyclopts
   cyclopts is not available.

   $ python pypi_checker.py cyclopts --silent
   $ echo $?  # Check the exit code of the previous command.
   1

   $ python pypi_checker.py the-next-big-project
   the-next-big-project is available.
   $ echo $?  # Check the exit code of the previous command.
   0

We will slowly introduce unit-testing concepts and build up a fairly comprehensive set of unit-tests for this application.

-------
Mocking
-------
First off, it's good code-hygiene to separate "business logic" from "user interface."
In this example, that means putting all the actual logic of determining whether or not a package name is available into the ``_check_pypi_name_available`` function, and putting all of the CLI logic (like printing to ``stdout`` and exit-codes) in the Cyclopts-decorated function ``pypi_checker``.
This makes it easier to unit-test the app because it allows us to `mock <https://docs.python.org/3/library/unittest.mock.html>`_ out portions of our app, allowing us to isolate our CLI unit-tests to just the CLI components.

We can use `pytest-mock`_ to simplify mocking ``_check_pypi_name_available``. Let's define a `fixture`_ that declares this mock.

.. code-block:: python

   # test.py
   import pytest
   from pypi_checker import app

   @pytest.fixture
   def mock_check_pypi_name_available(mocker):
       return mocker.patch("pypi_checker._check_pypi_name_available")

Unit tests that use this fixture can define it's return value, as well as check the arguments it was called with.
This will be demonstrated in the next section.

----------
Exit Codes
----------
Our command function returns a boolean. By default, Cyclopts uses :attr:`~cyclopts.App.result_action` of ``"print_non_int_sys_exit"``, which calls :func:`sys.exit` with the appropriate code: :obj:`True` → ``0`` (success), :obj:`False` → ``1`` (failure).

.. code-block:: python

   import pytest

   def test_unavailable_name_cli_behavior(mock_check_pypi_name_available):
       # Set the mock return_value to False (i.e. the name is NOT available).
       mock_check_pypi_name_available.return_value = False
       with pytest.raises(SystemExit) as exc_info:
           app("foo")  # Default result_action calls sys.exit
       mock_check_pypi_name_available.assert_called_once_with("foo")
       assert exc_info.value.code == 1  # Package unavailable exits with code 1

We can then run pytest on this file:

.. code-block:: console

   $ pytest test.py
   ============================== test session starts ==============================
   platform darwin -- Python 3.13.0, pytest-8.3.4, pluggy-1.5.0
   rootdir: /cyclopts-demo
   configfile: pyproject.toml
   plugins: cov-6.0.0, anyio-4.8.0, mock-3.14.0
   collected 1 item

   test.py .                                                                 [100%]

   =============================== 1 passed in 0.05s ===============================


---------------
Checking stdout
---------------
We also want to make sure that our message is displayed to the user.
The built-in `capsys`_ fixture gives us access to our application's ``stdout``.
We can use this to confirm our app prints the correct statement.

By passing ``result_action="return_value"`` to the app call, we can get the return value directly without :func:`sys.exit` being called:

.. code-block:: python

   # test.py - continued from "Exit Codes"
   def test_unavailable_name_with_output(capsys, mock_check_pypi_name_available):
       mock_check_pypi_name_available.return_value = False
       is_available = app("foo", result_action="return_value")
       mock_check_pypi_name_available.assert_called_once_with("foo")
       assert is_available is False
       assert capsys.readouterr().out == "foo is not available.\n"

.. note::
   Normal output goes to :attr:`~cyclopts.App.console` (stdout), while errors go to :attr:`~cyclopts.App.error_console` (stderr). Use ``capsys.readouterr().err`` to check error messages, or provide a custom ``error_console`` to capture both streams together.


---------------------
Environment Variables
---------------------
Because we configured our :class:`.App` with :class:`cyclopts.config.Env`, we can pass arguments into our application via environment variables.
The `pytest monkeypatch fixture`_ allows us to modify environment variables within the context of a unit-test.

In this test, we only want to test if our environment variable is being passed in correctly.
We will use :meth:`.App.parse_args`, which performs all the parsing, but doesn't actually invoke the command.

.. code-block:: python

   # test.py
   def test_name_env_var(monkeypatch):
       from pypi_checker import pypi_checker
       monkeypatch.setenv("PYPI_CHECKER_NAME", "foo")
       command, bound, _ = app.parse_args([])  # An empty list - no CLI arguments passed in.
       assert command == pypi_checker
       assert bound.arguments['name'] == "foo"

.. warning::

   A common mistake is accidentally calling ``app()`` or ``app.parse_args()`` with the **intent of providing no arguments**.
   Calling these methods with no arguments will read from :obj:`sys.argv`, the same as in a typical application.
   This is rarely the intention in a unit-test, and Cyclopts **will produce a warning.**
   For example, this code in a unit test:

   .. code-block:: python

      app()  # Wrong: will produce a warning

   Will generate this warning:

   .. code-block:: text

      =============================== warnings summary ================================
      test.py::test_no_args
        /my_project/test.py:64: UserWarning: Cyclopts application invoked without tokens
        under unit-test framework "pytest". Did you mean "app([])"?
          app()

   The proper way to specify no CLI arguments is to provide an empty string or list:

   .. code-block:: python

      app([])

-----------
File Config
-----------
To explicitly test that configurations from the :ref:`Cyclopts configuration system <Config Files>` are loading properly, we can create a configuration file in a temporary directory and change our current-working-directory (cwd) to that temporary directory. The pytest built-in ``tmp_path`` fixture gives us a temporary directory, and the ``monkeypatch`` fixture allows us to change the cwd. We have to change the cwd because typically configuration files are discovered relative to the directory where the CLI was invoked. If your CLI searches other locations (such as the home directory), you will need to modify this example appropriately.

.. code-block:: python

   # test.py
   import json
   from pypi_checker import pypi_checker

   @pytest.fixture(autouse=True)
   def chdir_to_tmp_path(tmp_path, monkeypatch):
       "Automatically change current directory to tmp_path"
       monkeypatch.chdir(tmp_path)

   @pytest.fixture
   def config_path(tmp_path):
       "Path to JSON configuration file in tmp_path"
       return tmp_path / "config.json"  # same name that was provided to cyclopts.config.Json

   def test_config(config_path):
       with config_path.open("w") as f:
          json.dump({"name": "bar"}, f)
       command, bound, _ = app.parse_args([])  # An empty list - no CLI arguments passed in.
       assert command == pypi_checker
       assert bound.arguments['name'] == "bar"

---------
Help Page
---------
Cyclopts uses Rich_ to pretty-print messages to the console.
Rich interprets the console environment, and can change how it displays text depending on the terminal's capabilities.
For unit testing, we will explicitly set a lot of these parameters in a pytest fixture to make it easier to compare against known good values:

.. code-block:: python

   @pytest.fixture
   def console():
       from rich.console import Console
       return Console(width=70, force_terminal=True, highlight=False, color_system=None, legacy_windows=False)

Since the help-page is just printed to ``stdout``, we will be using the `capsys`_ fixture again.

.. code-block:: python

   import pytest
   from textwrap import dedent

   def test_help_page(capsys, console):
       with pytest.raises(SystemExit):
           app("--help", console=console)
       actual = capsys.readouterr().out
       assert actual == dedent(
           """\
           Usage: pypi_checker COMMAND [ARGS] [OPTIONS]

           Check if a package name is available on PyPI.

           Returns True if available; False otherwise.

           ╭─ Commands ─────────────────────────────────────────────────────────╮
           │ --help -h  Display this message and exit.                          │
           │ --version  Display application version.                            │
           ╰────────────────────────────────────────────────────────────────────╯
           ╭─ Parameters ───────────────────────────────────────────────────────╮
           │ *  NAME --name           Name of the package to check. [required]  │
           │    --silent --no-silent  Do not print anything to stdout.          │
           │                          [default: False]                          │
           ╰────────────────────────────────────────────────────────────────────╯
           """
       )

The :func:`textwrap.dedent` function allows us to have our expected-help-string nicely indented within our code.
Alternatively, we could have used the :meth:`rich.console.Console.capture` context manager to directly capture the :class:`rich.console.Console` output.

.. note::
   Unit-testing the help-page is probably overkill for most projects (and may get in the way more often than it helps!).

.. _PyPI: https://pypi.org
.. _pytest: https://docs.pytest.org/en/stable/
.. _pytest-mock: https://pytest-mock.readthedocs.io/en/latest/
.. _fixture: https://docs.pytest.org/en/stable/explanation/fixtures.html
.. _capsys: https://docs.pytest.org/en/stable/how-to/capture-stdout-stderr.html#accessing-captured-output-from-a-test-function
.. _pytest monkeypatch fixture: https://docs.pytest.org/en/stable/how-to/monkeypatch.html
.. _Rich: https://rich.readthedocs.io/en/stable/
