1Basic usage 2============================================= 3 4a simple tox.ini / default environments 5----------------------------------------------- 6 7Put basic information about your project and the test environments you 8want your project to run in into a ``tox.ini`` file that should 9reside next to your ``setup.py`` file: 10 11.. code-block:: ini 12 13 # content of: tox.ini , put in same dir as setup.py 14 [tox] 15 envlist = py27,py36 16 [testenv] 17 # install testing framework 18 # ... or install anything else you might need here 19 deps = pytest 20 # run the tests 21 # ... or run any other command line tool you need to run here 22 commands = pytest 23 24To sdist-package, install and test your project, you can 25now type at the command prompt: 26 27.. code-block:: shell 28 29 tox 30 31This will sdist-package your current project, create two virtualenv_ 32Environments, install the sdist-package into the environments and run 33the specified command in each of them. With: 34 35.. code-block:: shell 36 37 tox -e py36 38 39you can run restrict the test run to the python3.6 environment. 40 41Available "default" test environments names are: 42 43.. code-block:: shell 44 45 py 46 py2 47 py27 48 py3 49 py34 50 py35 51 py36 52 py37 53 py38 54 jython 55 pypy 56 pypy2 57 pypy27 58 pypy3 59 pypy35 60 61The environment ``py`` uses the version of Python used to invoke tox. 62 63However, you can also create your own test environment names, 64see some of the examples in :doc:`examples <../examples>`. 65 66pyproject.toml tox legacy ini 67----------------------------- 68 69The tox configuration can also be in ``pyproject.toml`` (if you want to avoid an extra file). 70 71Currently only the old format is supported via ``legacy_tox_ini``, a native implementation is planned though. 72 73.. code-block:: toml 74 75 [build-system] 76 requires = [ "setuptools >= 35.0.2", "wheel >= 0.29.0"] 77 build-backend = "setuptools.build_meta" 78 79 [tool.tox] 80 legacy_tox_ini = """ 81 [tox] 82 envlist = py27,py36 83 84 [testenv] 85 deps = pytest >= 3.0.0, <4 86 commands = pytest 87 """ 88 89Note that when you define a ``pyproject.toml`` you must define the ``build-requires`` section per PEP-518. 90 91specifying a platform 92----------------------------------------------- 93 94.. versionadded:: 2.0 95 96If you want to specify which platform(s) your test environment 97runs on you can set a platform regular expression like this: 98 99.. code-block:: ini 100 101 [testenv] 102 platform = linux2|darwin 103 104If the expression does not match against ``sys.platform`` 105the test environment will be skipped. 106 107whitelisting non-virtualenv commands 108----------------------------------------------- 109 110.. versionadded:: 1.5 111 112Sometimes you may want to use tools not contained in your 113virtualenv such as ``make``, ``bash`` or others. To avoid 114warnings you can use the ``whitelist_externals`` testenv 115configuration: 116 117.. code-block:: ini 118 119 # content of tox.ini 120 [testenv] 121 whitelist_externals = make 122 /bin/bash 123 124 125.. _virtualenv: https://pypi.org/project/virtualenv 126 127.. _multiindex: 128 129depending on requirements.txt or defining constraints 130----------------------------------------------------- 131 132.. versionadded:: 1.6.1 133 134(experimental) If you have a ``requirements.txt`` file or a ``constraints.txt`` file you can add it to your ``deps`` variable like this: 135 136.. code-block:: ini 137 138 [testenv] 139 deps = -rrequirements.txt 140 141or 142 143.. code-block:: ini 144 145 [testenv] 146 deps = -cconstraints.txt 147 148or 149 150.. code-block:: ini 151 152 [testenv] 153 deps = 154 -rrequirements.txt 155 -cconstraints.txt 156 157All installation commands are executed using ``{toxinidir}`` (the directory where ``tox.ini`` resides) as the current working directory. 158Therefore, the underlying ``pip`` installation will assume ``requirements.txt`` or ``constraints.txt`` to exist at ``{toxinidir}/requirements.txt`` or ``{toxinidir}/constraints.txt``. 159 160This is actually a side effect that all elements of the dependency list is directly passed to ``pip``. 161 162For more details on ``requirements.txt`` files or ``constraints.txt`` files please see: 163 164* https://pip.pypa.io/en/stable/user_guide/#requirements-files 165* https://pip.pypa.io/en/stable/user_guide/#constraints-files 166 167using a different default PyPI url 168----------------------------------------------- 169 170.. versionadded:: 0.9 171 172To install dependencies and packages from a different 173default PyPI server you can type interactively: 174 175.. code-block:: shell 176 177 tox -i https://pypi.my-alternative-index.org 178 179This causes tox to install dependencies and the sdist install step 180to use the specified url as the index server. 181 182You can cause the same effect by this ``tox.ini`` content: 183 184.. code-block:: ini 185 186 [tox] 187 indexserver = 188 default = https://pypi.my-alternative-index.org 189 190installing dependencies from multiple PyPI servers 191--------------------------------------------------- 192 193.. versionadded:: 0.9 194 195You can instrument tox to install dependencies from 196different PyPI servers, example: 197 198.. code-block:: ini 199 200 [tox] 201 indexserver = 202 DEV = https://mypypiserver.org 203 204 [testenv] 205 deps = 206 # docutils will be installed directly from PyPI 207 docutils 208 # mypackage will be installed from custom "DEV" PyPI url 209 :DEV:mypackage 210 211This configuration will install ``docutils`` from the default 212Python PYPI server and will install the ``mypackage`` from 213our ``DEV`` indexserver, and the respective ``https://mypypiserver.org`` 214url. You can override config file settings from the command line 215like this: 216 217.. code-block:: shell 218 219 tox -i DEV=https://pypi.org/simple # changes :DEV: package URLs 220 tox -i https://pypi.org/simple # changes default 221 222further customizing installation 223--------------------------------- 224 225.. versionadded:: 1.6 226 227By default tox uses `pip`_ to install packages, both the 228package-under-test and any dependencies you specify in ``tox.ini``. 229You can fully customize tox's install-command through the 230testenv-specific :conf:`install_command=ARGV` setting. 231For instance, to use pip's ``--find-links`` and ``--no-index`` options to specify 232an alternative source for your dependencies: 233 234.. code-block:: ini 235 236 [testenv] 237 install_command = pip install --pre --find-links https://packages.example.com --no-index {opts} {packages} 238 239.. _pip: https://pip.pypa.io/en/stable/ 240 241forcing re-creation of virtual environments 242----------------------------------------------- 243 244.. versionadded:: 0.9 245 246To force tox to recreate a (particular) virtual environment: 247 248.. code-block:: shell 249 250 tox --recreate -e py27 251 252would trigger a complete reinstallation of the existing py27 environment 253(or create it afresh if it doesn't exist). 254 255passing down environment variables 256------------------------------------------- 257 258.. versionadded:: 2.0 259 260By default tox will only pass the ``PATH`` environment variable (and on 261windows ``SYSTEMROOT`` and ``PATHEXT``) from the tox invocation to the 262test environments. If you want to pass down additional environment 263variables you can use the ``passenv`` option: 264 265.. code-block:: ini 266 267 [testenv] 268 passenv = LANG 269 270When your test commands execute they will execute with 271the same LANG setting as the one with which tox was invoked. 272 273setting environment variables 274------------------------------------------- 275 276.. versionadded:: 1.0 277 278If you need to set an environment variable like ``PYTHONPATH`` you 279can use the ``setenv`` directive: 280 281.. code-block:: ini 282 283 [testenv] 284 setenv = PYTHONPATH = {toxinidir}/subdir 285 286When your test commands execute they will execute with 287a PYTHONPATH setting that will lead Python to also import 288from the ``subdir`` below the directory where your ``tox.ini`` 289file resides. 290 291special handling of PYTHONHASHSEED 292------------------------------------------- 293 294.. versionadded:: 1.6.2 295 296By default, tox sets PYTHONHASHSEED_ for test commands to a random integer 297generated when ``tox`` is invoked. This mimics Python's hash randomization 298enabled by default starting `in Python 3.3`_. To aid in reproducing test 299failures, tox displays the value of ``PYTHONHASHSEED`` in the test output. 300 301You can tell tox to use an explicit hash seed value via the ``--hashseed`` 302command-line option to ``tox``. You can also override the hash seed value 303per test environment in ``tox.ini`` as follows: 304 305.. code-block:: ini 306 307 [testenv] 308 setenv = PYTHONHASHSEED = 100 309 310If you wish to disable this feature, you can pass the command line option 311``--hashseed=noset`` when ``tox`` is invoked. You can also disable it from the 312``tox.ini`` by setting ``PYTHONHASHSEED = 0`` as described above. 313 314.. _`in Python 3.3`: https://docs.python.org/3/whatsnew/3.3.html#builtin-functions-and-types 315.. _PYTHONHASHSEED: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONHASHSEED 316 317Integration with "setup.py test" command 318---------------------------------------------------- 319 320.. warning:: 321 322 Integrating tox with ``setup.py test`` is as of October 2016 discouraged as 323 it breaks packaging/testing approaches used by downstream distributions 324 which expect ``setup.py test`` to run tests with the invocation interpreter 325 rather than setting up many virtualenvs and installing packages. If you need to 326 define ``setup.py test``, you can see how to integrate your eventual 327 test runner with it, here is an `example of setup.py test integration with pytest 328 <https://docs.pytest.org/en/latest/goodpractices.html#integrating-with-setuptools-python-setup-py-test-pytest-runner>`_. 329 As the python eco-system rather moves away from using ``setup.py`` as a tool entry 330 point it's maybe best to not go for any ``setup.py test`` integration. 331 332 333.. _`ignoring exit code`: 334 335Ignoring a command exit code 336---------------------------- 337 338In some cases, you may want to ignore a command exit code. For example: 339 340.. code-block:: ini 341 342 [testenv:py27] 343 commands = coverage erase 344 {envbindir}/python setup.py develop 345 coverage run -p setup.py test 346 coverage combine 347 - coverage html 348 {envbindir}/flake8 loads 349 350By using the ``-`` prefix, similar to a ``make`` recipe line, you can ignore 351the exit code for that command. 352 353Compressing dependency matrix 354----------------------------- 355 356If you have a large matrix of dependencies, python versions and/or environments you can 357use :ref:`generative-envlist` and :ref:`conditional settings <factors>` to express that in a concise form: 358 359.. code-block:: ini 360 361 [tox] 362 envlist = py{27,34,36}-django{15,16}-{sqlite,mysql} 363 364 [testenv] 365 deps = 366 django15: Django>=1.5,<1.6 367 django16: Django>=1.6,<1.7 368 # use PyMySQL if factors "py34" and "mysql" are present in env name 369 py34-mysql: PyMySQL 370 # use urllib3 if any of "py36" or "py27" are present in env name 371 py27,py36: urllib3 372 # mocking sqlite on 2.7 and 3.6 if factor "sqlite" is present 373 py{27,36}-sqlite: mock 374 375Prevent symbolic links in virtualenv 376------------------------------------ 377By default virtualenv will use symlinks to point to the system's python files, modules, etc. 378If you want the files to be copied instead, possibly because your filesystem is not capable 379of handling symbolic links, you can instruct virtualenv to use the "--always-copy" argument 380meant exactly for that purpose, by setting the ``alwayscopy`` directive in your environment: 381 382.. code-block:: ini 383 384 [testenv] 385 alwayscopy = True 386 387.. _`parallel_mode`: 388 389Parallel mode 390------------- 391``tox`` allows running environments in parallel: 392 393- Invoke by using the ``--parallel`` or ``-p`` flag. After the packaging phase completes tox will run in parallel 394 processes tox environments (spins a new instance of the tox interpreter, but passes through all host flags and 395 environment variables). 396- ``-p`` takes an argument specifying the degree of parallelization: 397 398 - ``all`` to run all invoked environments in parallel, 399 - ``auto`` to limit it to CPU count, 400 - or pass an integer to set that limit. 401- Parallel mode displays a progress spinner while running tox environments in parallel, and reports outcome of 402 these as soon as completed with a human readable duration timing attached. 403- Parallel mode by default shows output only of failed environments and ones marked as :conf:`parallel_show_output` 404 ``=True``. 405- There's now a concept of dependency between environments (specified via :conf:`depends`), tox will re-order the 406 environment list to be run to satisfy these dependencies (in sequential run too). Furthermore, in parallel mode, 407 will only schedule a tox environment to run once all of its dependencies finished (independent of their outcome). 408 409 .. warning:: 410 411 ``depends`` does not pull in dependencies into the run target, for example if you select ``py27,py36,coverage`` 412 via the ``-e`` tox will only run those three (even if ``coverage`` may specify as ``depends`` other targets too - 413 such as ``py27, py35, py36, py37``). 414 415- ``--parallel-live``/``-o`` allows showing the live output of the standard output and error, also turns off reporting 416 described above. 417- Note: parallel evaluation disables standard input. Use non parallel invocation if you need standard input. 418 419Example final output: 420 421.. code-block:: bash 422 423 $ tox -e py27,py36,coverage -p all 424 ✔ OK py36 in 9.533 seconds 425 ✔ OK py27 in 9.96 seconds 426 ✔ OK coverage in 2.0 seconds 427 ___________________________ summary ______________________________________________________ 428 py27: commands succeeded 429 py36: commands succeeded 430 coverage: commands succeeded 431 congratulations :) 432 433 434Example progress bar, showing a rotating spinner, the number of environments running and their list (limited up to \ 435120 characters): 436 437.. code-block:: bash 438 439 ⠹ [2] py27 | py36 440 441.. _`auto-provision`: 442 443tox auto-provisioning 444--------------------- 445In case the host tox does not satisfy either the :conf:`minversion` or the :conf:`requires`, tox will now automatically 446create a virtual environment under :conf:`provision_tox_env` that satisfies those constraints and delegate all calls 447to this meta environment. This should allow automatically satisfying constraints on your tox environment, 448given you have at least version ``3.8.0`` of tox. 449 450For example given: 451 452.. code-block:: ini 453 454 [tox] 455 minversion = 3.10.0 456 requires = tox_venv >= 1.0.0 457 458if the user runs it with tox ``3.8.0`` or later installed tox will automatically ensured that both the minimum version 459and requires constraints are satisfied, by creating a virtual environment under ``.tox`` folder, and then installing 460into it ``tox >= 3.10.0`` and ``tox_venv >= 1.0.0``. Afterwards all tox invocations are forwarded to the tox installed 461inside ``.tox\.tox`` folder (referred to as meta-tox or auto-provisioned tox). 462 463This allows tox to automatically setup itself with all its plugins for the current project. If the host tox satisfies 464the constraints expressed with the :conf:`requires` and :conf:`minversion` no such provisioning is done (to avoid 465setup cost when it's not explicitly needed). 466