CLI tasks and pytest options
============================

pybFoam uses `poethepoet`_ (``poe``) as a task runner. Tasks are defined in
``pyproject.toml`` under ``[tool.poe.tasks]``.

.. _poethepoet: https://poethepoet.natn.io/

poe tasks
---------

.. list-table::
   :header-rows: 1
   :widths: 20 35 45

   * - Task
     - Command
     - Purpose
   * - ``poe test``
     - ``pytest``
     - Run the full test suite. Requires a sourced OpenFOAM environment and
       a built package.
   * - ``poe lint``
     - ``ruff check src tests``
     - Lint with ruff (rules: E, F, I — pycodestyle, pyflakes, isort).
   * - ``poe format``
     - ``ruff format``
     - Auto-format with ruff.
   * - ``poe type_check``
     - ``mypy``
     - Run mypy in strict mode with the pydantic plugin. Checks ``src`` and
       ``tests``.
   * - ``poe build_docs``
     - ``sphinx-build -b html docs docs/_build``
     - Build HTML docs into ``docs/_build/``.
   * - ``poe view_docs``
     - ``python -m webbrowser -t docs/_build/index.html``
     - Open the locally-built docs in a browser.

Invoke any task with ``poe <name>``. Add flags after the name; they are
forwarded to the underlying command (e.g. ``poe test -k sampling``).

Custom pytest options
---------------------

Defined in the top-level ``conftest.py``:

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Option
     - Default
     - Effect
   * - ``--writeNSteps N``
     - ``0``
     - Cap how many timesteps a test solver writes. Useful when iterating on
       a test to avoid generating many result directories. ``0`` means no
       cap.
   * - ``--no-clean-up``
     - *(cleanup on)*
     - Skip the case teardown after a test finishes so you can inspect the
       run directory. Tests set up their cases from ``0.orig`` / ``Allclean``
       hooks; without cleanup, the run directory is left as-is.

Standard pytest options (``-k``, ``-x``, ``-v``, ``--lf``, etc.) all work too.
``[tool.pytest.ini_options]`` sets the default ``addopts = "-ra -v -s"``.

Stub generation
---------------

Type stubs for the compiled extension modules are generated by a separate
script (not a poe task):

.. code-block:: bash

   ./scripts/generate_stubs.sh

This runs ``pybind11-stubgen``, cleans and formats the output, copies the
``.pyi`` files into ``src/pybFoam/``, and verifies with mypy.