tox.ini

[tox]

# --------------------------------------------------------------------
#
# NOTE(kgriffs,vytas): CPython 3.10-3.15 is required when checking
# combined coverage. To check coverage:
#
#   $ tox
#
# You can then drill down into coverage details by opening the HTML
# report at ".coverage_html/index.html".
#
# --------------------------------------------------------------------

envlist = cleanup,
          ruff,
          pep8,
          pep8-docstrings,
          mypy,
          mypy_tests,
          mintest,
          pytest,
          coverage,
          docs

[testenv]
# NOTE(vytas): Other Falcon-specific environment variables for automatic
#   wrapping of coroutines are set in tests/conftest.py.
setenv =
    PIP_CONFIG_FILE=pip.conf
    PYTHONASYNCIODEBUG=1
    FALCON_DISABLE_CYTHON=Y
deps = -r requirements/tests
commands = python tools/clean.py falcon
           pytest tests []

# --------------------------------------------------------------------
# Miscellaneous tasks
# --------------------------------------------------------------------

[testenv:cleanup]
deps = {[testenv]deps}
commands = python tools/clean.py falcon
           coverage erase

[testenv:coverage]
deps = {[testenv]deps}
commands = coverage combine
           coverage html -d .coverage_html
           coverage report --fail-under 100

# --------------------------------------------------------------------
# Coverage
# --------------------------------------------------------------------

[with-coverage]
commands = python tools/clean.py falcon
           coverage run -m pytest tests []

[testenv:mintest]
setenv =
    PIP_CONFIG_FILE=pip.conf
    PYTHONASYNCIODEBUG=0
    FALCON_DISABLE_CYTHON=Y
deps = -r requirements/mintest
commands = coverage run -m pytest tests -k 'not slow' []

[testenv:pytest]
deps = {[testenv]deps}
       pytest-randomly
       jsonschema
       testtools
commands = coverage run -m pytest tests []

[testenv:py314]
basepython = python3.14
deps = {[testenv]deps}
       pytest-randomly
       jsonschema
       testtools
commands = {[with-coverage]commands}

[testenv:py314_nocover]
basepython = python3.14
deps = {[testenv]deps}
       pytest-randomly
       jsonschema
commands = pytest tests []

# --------------------------------------------------------------------
# Additional test suite environments
# --------------------------------------------------------------------

[testenv:pypy3]
basepython = pypy3

# --------------------------------------------------------------------
# Debugging
# --------------------------------------------------------------------

[with-debug-tools]
deps = -r requirements/tests
       pdbpp

[testenv:py3_debug]
basepython = python3.14
deps = {[with-debug-tools]deps}
       uvicorn
       jsonschema

# --------------------------------------------------------------------
# Typing
# --------------------------------------------------------------------

[testenv:mypy]
skipsdist = True
skip_install = True
deps = mypy
       types-jsonschema
commands = python tools/clean.py falcon
           mypy --strict falcon

[testenv:mypy_tests]
deps = {[testenv]deps}
       mypy
       cheroot
       types-requests
       types-PyYAML
       types-ujson
       types-waitress
       types-aiofiles
       types-jsonschema
commands = python tools/clean.py falcon
           mypy --strict e2e-tests/server
           mypy --strict tests/test_typing.py
           mypy tests --allow-untyped-calls --allow-untyped-defs --no-check-untyped-defs

[testenv:pyright_tests]
deps = pyright
commands = python tools/clean.py falcon
           pyright e2e-tests/server
           pyright tests/test_typing.py

# --------------------------------------------------------------------
# Cython
# --------------------------------------------------------------------

[with-cython]
# NOTE(vytas): Specify Cython dep for tests/test_cython.py as PEP 517 build
#   does not require it (although Tox seems to inject it in the current impl).
deps = -r requirements/tests
       Cython
setenv =
    PIP_CONFIG_FILE=pip.conf
    FALCON_DISABLE_CYTHON=
    FALCON_ASGI_WRAP_NON_COROUTINES=Y
    FALCON_TESTING_SESSION=Y
    PYTHONASYNCIODEBUG=1
commands = pytest tests []

[testenv:py39_cython]
basepython = python3.9
deps = {[with-cython]deps}
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py310_cython]
basepython = python3.10
deps = {[with-cython]deps}
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py311_cython]
basepython = python3.11
deps = {[with-cython]deps}
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py312_cython]
basepython = python3.12
# NOTE(vytas): pyximport relies on distutils.extension
deps = {[with-cython]deps}
       setuptools
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py313_cython]
basepython = python3.13
# NOTE(vytas): pyximport relies on distutils.extension
deps = {[with-cython]deps}
       setuptools
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py314_cython]
basepython = python3.14
# NOTE(vytas): pyximport relies on distutils.extension
deps = {[with-cython]deps}
       setuptools
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

[testenv:py315_cython]
basepython = python3.15
# NOTE(vytas): pyximport relies on distutils.extension
deps = {[with-cython]deps}
       setuptools
setenv = {[with-cython]setenv}
commands = {[with-cython]commands}

# --------------------------------------------------------------------
# WSGI servers (Cythonized Falcon)
# --------------------------------------------------------------------

[testenv:wsgi_servers]
setenv = {[with-cython]setenv}
# NOTE(vytas): Uvicorn is also included (via default deps) and tested.
deps = {[with-cython]deps}
       cheroot
       granian
       gunicorn
       pyuwsgi
       waitress
commands = pytest -v tests/test_wsgi_servers.py

[testenv:wsgi_meinheld]
# NOTE(caselit): meinheld requires greenlet<0.5 that's not compatible with py3.10
basepython = python3.9
setenv = {[with-cython]setenv}
deps = {[with-cython]deps}
       gunicorn
       meinheld
commands = pytest -v tests/test_wsgi_servers.py

# --------------------------------------------------------------------
# ASGI servers
# --------------------------------------------------------------------

[testenv:daphne]
deps = -r requirements/asgiservers
       daphne
commands = pytest -v tests/asgi/test_asgi_servers.py

[testenv:granian]
deps = -r requirements/asgiservers
       granian
commands = pytest -v tests/asgi/test_asgi_servers.py

[testenv:hypercorn]
deps = -r requirements/asgiservers
       hypercorn
commands = pytest -v tests/asgi/test_asgi_servers.py

# --------------------------------------------------------------------
# Smoke testing with a sample app
# --------------------------------------------------------------------

[smoke-test]
commands = python -c "import falcon.asgi; falcon.asgi.App()"
           falcon-bench -t 1 -b falcon-ext

[testenv:py310_smoke]
# NOTE(vytas): vmprof supports only up to Python 3.11 at the time of writing.
#   (https://github.com/vmprof/vmprof-python/issues/261)
basepython = python3.10
deps = -r requirements/bench
commands = {[smoke-test]commands}

[testenv:py310_smoke_cython]
# NOTE(vytas): vmprof supports only up to Python 3.11 at the time of writing.
#   (https://github.com/vmprof/vmprof-python/issues/261)
basepython = python3.10
deps = -r requirements/bench
       cython
setenv = {[with-cython]setenv}
commands = {[smoke-test]commands}

# --------------------------------------------------------------------
# Lint
# --------------------------------------------------------------------

[testenv:pep8]
deps = ruff>=0.16.7
skip_install = True
commands = ruff check []

[testenv:pep8-docstrings]
deps = ruff>=0.16.7
skip_install = True
commands = ruff check \
             --exclude=.ecosystem,.eggs,.git,.tox,.venv,build,dist,docs,examples,tests,falcon/bench/nuts \
             --select=D205,D212,D400,D401,D403,D404 \
             []

[testenv:ruff]
deps = ruff>=0.16.7
skip_install = True
commands = ruff format --check . []

[testenv:reformat]
deps = ruff>=0.16.7
skip_install = True
commands =
    ruff format . []
    ruff check --fix

# --------------------------------------------------------------------
# For viewing environ dicts generated by various WSGI servers
# --------------------------------------------------------------------

[testenv:dump_gunicorn]
deps = gunicorn
commands = gunicorn -b localhost:8000 tests.dump_wsgi

[testenv:dump_waitress]
deps = waitress
commands = waitress-serve --listen=localhost:8000 tests.dump_wsgi:application

[testenv:dump_wsgiref]
commands = python tests/dump_wsgi.py

# --------------------------------------------------------------------
# Benchmarking
# --------------------------------------------------------------------

[testenv:py310_bench]
basepython = python3.10
deps = -r requirements/bench
commands = falcon-bench []

[testenv:py310_bench_cython]
basepython = python3.10
deps = -r requirements/bench
       cython
commands = falcon-bench []

[testenv:pypy_bench]
basepython = pypy
deps = -r requirements/bench
commands = falcon-bench []

[testenv:pypy3_bench]
basepython = pypy3
deps = -r requirements/bench
commands = falcon-bench []

# --------------------------------------------------------------------
# Package sanity check with twine
# --------------------------------------------------------------------

[testenv:twine_check]
skipsdist = True
deps = build
       twine
commands =
    python -m build
    twine check dist/*

# --------------------------------------------------------------------
# Security auditing
# --------------------------------------------------------------------

[testenv:zizmor]
skipsdist = True
deps = zizmor
commands =
    zizmor .github/workflows/

[testenv:zizmor_github]
skipsdist = True
deps = zizmor
commands =
    zizmor --format github .github/workflows/

# --------------------------------------------------------------------
# Documentation
# --------------------------------------------------------------------

[testenv:docs]
# NOTE(vytas): For easy testing of reproducible documentation builds.
#   (See also: https://reproducible-builds.org/docs/source-date-epoch/)
passenv = SOURCE_DATE_EPOCH
deps = -r requirements/docs
commands =
    sphinx-build -j auto -W -E -b html docs docs/_build/html []

[testenv:changelog_release]
deps = -r requirements/docs
        toml
commands =
    python tools/add_contributors.py
    python tools/towncrier_draft.py

# NOTE(kgriffs): Renders the changelog to HTML so that the final result
#   can be previewed, but then restores the changelog RST document.
[testenv:changelog_draft]
deps = -r requirements/docs
        toml
commands =
    python tools/add_contributors.py --dry-run
    python tools/towncrier_draft.py --dry-run

[testenv:dash]
basepython = python3.10
setenv =
    DASHBUILD = True
deps = -r requirements/docs
commands =
    sphinx-build -j 4 -W -E -b html docs docs/_build/html []
    tools/generate_dash.sh

# --------------------------------------------------------------------
# Tutorial tests
#
#   - Tutorial ("look") tests
#   - ASGI tutorial ("asgilook") tests
#   - WebSockets tutorial ("ws_tutorial") tests
# --------------------------------------------------------------------

[testenv:look]
deps =
    -r examples/look/requirements/test
commands =
    pytest examples/look/tests

[testenv:asgilook]
basepython = python3.14
deps =
    -r examples/asgilook/requirements/asgilook
    -r examples/asgilook/requirements/test
commands =
    pytest \
        --cov asgilook \
        --cov-config examples/asgilook/.coveragerc \
        --cov-fail-under 100 \
        --cov-report term-missing \
        examples/asgilook/tests/

[testenv:ws_tutorial]
basepython = python3.14
deps =
    -r examples/ws_tutorial/requirements/app
    -r examples/ws_tutorial/requirements/test
commands =
    pytest \
        --cov ws_tutorial \
        --cov-config examples/ws_tutorial/.coveragerc \
        --cov-fail-under 100 \
        --cov-report term-missing \
        examples/ws_tutorial/tests/

# --------------------------------------------------------------------
# E2E tests
# --------------------------------------------------------------------

[testenv:e2e_chrome]
basepython = python3.14
deps =
    -r requirements/e2e
commands =
    pytest e2e-tests/ --browser=chrome

[testenv:e2e_firefox]
basepython = python3.14
deps =
    -r requirements/e2e
commands =
    pytest e2e-tests/ --browser=firefox