tox.ini

[tox]

# --------------------------------------------------------------------
#
# NOTE(kgriffs,vytas): Python 3.10, 3.11, 3.12, or 3.13 are 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,
          towncrier

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

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

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

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

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

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

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

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

[testenv:py312]
basepython = python3.12
deps = {[testenv]deps}
       pytest-randomly
       jsonschema
commands = {[with-coverage]commands}

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

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

[testenv:pypy3]
basepython = pypy3

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

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

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

# --------------------------------------------------------------------
# Mypy
# --------------------------------------------------------------------

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

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

# --------------------------------------------------------------------
# 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{toxinidir}/requirements/tests
       Cython
setenv =
    PIP_CONFIG_FILE={toxinidir}/pip.conf
    FALCON_DISABLE_CYTHON=
    FALCON_ASGI_WRAP_NON_COROUTINES=Y
    FALCON_TESTING_SESSION=Y
    PYTHONASYNCIODEBUG=1
commands = pytest tests []

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

[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}

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

[testenv:wsgi_servers]
setenv = {[with-cython]setenv}
deps = {[with-cython]deps}
       gunicorn
       uwsgi
       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.8
setenv = {[with-cython]setenv}
deps = {[with-cython]deps}
       gunicorn
       meinheld
commands = pytest -v tests/test_wsgi_servers.py

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

[testenv:daphne]
deps = {[testenv]deps}
       daphne
commands = pytest -v tests/asgi/test_asgi_servers.py

[testenv:hypercorn]
deps = {[testenv]deps}
       hypercorn
commands = pytest -v tests/asgi/test_asgi_servers.py

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

[smoke-test]
# NOTE(vytas): Work around pprofile's reliance on the removed use_2to3 option:
#   https://github.com/vpelletier/pprofile/issues/41
commands = pip install "setuptools < 58.0"
           pip install -r {toxinidir}/requirements/bench
           python -c "import falcon.asgi; falcon.asgi.App()"
           falcon-bench -t 1 -b falcon-ext

[testenv:py38_smoke]
# NOTE(caselit): vmprof requires python 3.8 https://github.com/vmprof/vmprof-python/issues/240
basepython = python3.8
deps =
commands = {[smoke-test]commands}

[testenv:py38_smoke_cython]
# NOTE(caselit): vmprof requires python 3.8 https://github.com/vmprof/vmprof-python/issues/240
basepython = python3.8
deps = cython
setenv = {[with-cython]setenv}
commands = {[smoke-test]commands}

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

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

[testenv:pep8-docstrings]
deps = ruff
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.3.7
skip_install = True
commands = ruff format --check . []

[testenv:reformat]
deps = ruff>=0.3.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{toxinidir}/requirements/bench
commands = falcon-bench []

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

[testenv:py38_bench]
basepython = python3.8
deps = -r{toxinidir}/requirements/bench
commands = falcon-bench []

[testenv:py38_bench_cython]
basepython = python3.8
deps = -r{toxinidir}/requirements/bench
       cython
commands = falcon-bench []

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

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

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

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

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

[testenv:docs]
deps = -r{toxinidir}/requirements/docs
commands =
    sphinx-build -j auto -W -E -b html docs docs/_build/html []

[testenv:towncrier]
deps = -r{toxinidir}/requirements/docs
        toml
        towncrier
commands =
    python "{toxinidir}/tools/towncrier_draft.py" --dry-run

[testenv:changelog_release]
deps = -r{toxinidir}/requirements/docs
        toml
        towncrier
commands =
    python "{toxinidir}/tools/add_contributors.py"
    python "{toxinidir}/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{toxinidir}/requirements/docs
        toml
        towncrier
commands =
    python "{toxinidir}/tools/add_contributors.py" --dry-run
    python "{toxinidir}/tools/towncrier_draft.py" --dry-run

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

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

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

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

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

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

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

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