diff options
Diffstat (limited to 'doc/example')
| -rw-r--r-- | doc/example/basic.txt | 313 | ||||
| -rw-r--r-- | doc/example/devenv.txt | 78 | ||||
| -rw-r--r-- | doc/example/general.txt | 182 | ||||
| -rw-r--r-- | doc/example/jenkins.txt | 174 | ||||
| -rw-r--r-- | doc/example/nose.txt | 41 | ||||
| -rwxr-xr-x | doc/example/pytest.txt | 111 | ||||
| -rw-r--r-- | doc/example/result.txt | 44 | ||||
| -rw-r--r-- | doc/example/unittest.txt | 89 |
8 files changed, 0 insertions, 1032 deletions
diff --git a/doc/example/basic.txt b/doc/example/basic.txt deleted file mode 100644 index 84fed34..0000000 --- a/doc/example/basic.txt +++ /dev/null @@ -1,313 +0,0 @@ -Basic usage -============================================= - -a simple tox.ini / default environments ------------------------------------------------ - -Put basic information about your project and the test environments you -want your project to run in into a ``tox.ini`` file that should -reside next to your ``setup.py`` file:: - - # content of: tox.ini , put in same dir as setup.py - [tox] - envlist = py26,py27 - [testenv] - deps=pytest # or 'nose' or ... - commands=py.test # or 'nosetests' or ... - -To sdist-package, install and test your project, you can -now type at the command prompt:: - - tox - -This will sdist-package your current project, create two virtualenv_ -Environments, install the sdist-package into the environments and run -the specified command in each of them. With:: - - tox -e py26 - -you can run restrict the test run to the python2.6 environment. - -Available "default" test environments names are:: - - py - py24 - py25 - py26 - py27 - py30 - py31 - py32 - py33 - py34 - jython - pypy - pypy3 - -The environment ``py`` uses the version of Python used to invoke tox. - -However, you can also create your own test environment names, -see some of the examples in :doc:`examples <../examples>`. - -specifying a platform ------------------------------------------------ - -.. versionadded:: 2.0 - -If you want to specify which platform(s) your test environment -runs on you can set a platform regular expression like this:: - - platform = linux2|darwin - -If the expression does not match against ``sys.platform`` -the test environment will be skipped. - -whitelisting non-virtualenv commands ------------------------------------------------ - -.. versionadded:: 1.5 - -Sometimes you may want to use tools not contained in your -virtualenv such as ``make``, ``bash`` or others. To avoid -warnings you can use the ``whitelist_externals`` testenv -configuration:: - - # content of tox.ini - [testenv] - whitelist_externals = make - /bin/bash - - -.. _virtualenv: http://pypi.python.org/pypi/virtualenv - -.. _multiindex: - -depending on requirements.txt ------------------------------------------------ - -.. versionadded:: 1.6.1 - -(experimental) If you have a ``requirements.txt`` file -you can add it to your ``deps`` variable like this:: - - deps = -rrequirements.txt - -All installation commands are executed using ``{toxinidir}`` -(the directory where ``tox.ini`` resides) as the current -working directory. Therefore, the underlying ``pip`` installation -will assume ``requirements.txt`` to exist at ``{toxinidir}/requirements.txt``. - -using a different default PyPI url ------------------------------------------------ - -.. versionadded:: 0.9 - -To install dependencies and packages from a different -default PyPI server you can type interactively:: - - tox -i http://pypi.testrun.org - -This causes tox to install dependencies and the sdist install step -to use the specificied url as the index server. - -You can cause the same effect by this ``tox.ini`` content:: - - [tox] - indexserver = - default = http://pypi.testrun.org - -installing dependencies from multiple PyPI servers ---------------------------------------------------- - -.. versionadded:: 0.9 - -You can instrument tox to install dependencies from -different PyPI servers, example:: - - [tox] - indexserver = - DEV = http://mypypiserver.org - - [testenv] - deps = - docutils # comes from standard PyPI - :DEV:mypackage # will be installed from custom "DEV" pypi url - -This configuration will install ``docutils`` from the default -Python PYPI server and will install the ``mypackage`` from -our ``DEV`` indexserver, and the respective ``http://mypypiserver.org`` -url. You can override config file settings from the command line -like this:: - - tox -i DEV=http://pypi.python.org/simple # changes :DEV: package URLs - tox -i http://pypi.python.org/simple # changes default - -further customizing installation ---------------------------------- - -.. versionadded:: 1.6 - -By default tox uses `pip`_ to install packages, both the -package-under-test and any dependencies you specify in ``tox.ini``. -You can fully customize tox's install-command through the -testenv-specific :confval:`install_command=ARGV` setting. -For instance, to use ``easy_install`` instead of `pip`_:: - - [testenv] - install_command = easy_install {opts} {packages} - -Or to use pip's ``--find-links`` and ``--no-index`` options to specify -an alternative source for your dependencies:: - - [testenv] - install_command = pip install --pre --find-links http://packages.example.com --no-index {opts} {packages} - -.. _pip: http://pip-installer.org - -forcing re-creation of virtual environments ------------------------------------------------ - -.. versionadded:: 0.9 - -To force tox to recreate a (particular) virtual environment:: - - tox --recreate -e py27 - -would trigger a complete reinstallation of the existing py27 environment -(or create it afresh if it doesn't exist). - -passing down environment variables -------------------------------------------- - -.. versionadded:: 2.0 - -By default tox will only pass the ``PATH`` environment variable (and on -windows ``SYSTEMROOT`` and ``PATHEXT``) from the tox invocation to the -test environments. If you want to pass down additional environment -variables you can use the ``passenv`` option:: - - [testenv] - passenv = LANG - -When your test commands execute they will execute with -the same LANG setting as the one with which tox was invoked. - -setting environment variables -------------------------------------------- - -.. versionadded:: 1.0 - -If you need to set an environment variable like ``PYTHONPATH`` you -can use the ``setenv`` directive:: - - [testenv] - setenv = - PYTHONPATH = {toxinidir}/subdir - -When your test commands execute they will execute with -a PYTHONPATH setting that will lead Python to also import -from the ``subdir`` below the directory where your ``tox.ini`` -file resides. - -special handling of PYTHONHASHSEED -------------------------------------------- - -.. versionadded:: 1.6.2 - -By default, Tox sets PYTHONHASHSEED_ for test commands to a random integer -generated when ``tox`` is invoked. This mimics Python's hash randomization -enabled by default starting `in Python 3.3`_. To aid in reproducing test -failures, Tox displays the value of ``PYTHONHASHSEED`` in the test output. - -You can tell Tox to use an explicit hash seed value via the ``--hashseed`` -command-line option to ``tox``. You can also override the hash seed value -per test environment in ``tox.ini`` as follows:: - - [testenv] - setenv = - PYTHONHASHSEED = 100 - -If you wish to disable this feature, you can pass the command line option -``--hashseed=noset`` when ``tox`` is invoked. You can also disable it from the -``tox.ini`` by setting ``PYTHONHASHSEED = 0`` as described above. - -.. _`in Python 3.3`: http://docs.python.org/3/whatsnew/3.3.html#builtin-functions-and-types -.. _PYTHONHASHSEED: http://docs.python.org/using/cmdline.html#envvar-PYTHONHASHSEED - -Integration with setuptools/distribute test commands ----------------------------------------------------- - -Distribute/Setuptools support test requirements -and you can extend its test command to trigger -a test run when ``python setup.py test`` is issued:: - - from setuptools.command.test import test as TestCommand - import sys - - class Tox(TestCommand): - user_options = [('tox-args=', 'a', "Arguments to pass to tox")] - def initialize_options(self): - TestCommand.initialize_options(self) - self.tox_args = None - def finalize_options(self): - TestCommand.finalize_options(self) - self.test_args = [] - self.test_suite = True - def run_tests(self): - #import here, cause outside the eggs aren't loaded - import tox - import shlex - args = self.tox_args - if args: - args = shlex.split(self.tox_args) - tox.cmdline(args=args) - - setup( - #..., - tests_require=['tox'], - cmdclass = {'test': Tox}, - ) - -Now if you run:: - - python setup.py test - -this will install tox and then run tox. You can pass arguments to ``tox`` -using the ``--tox-args`` or ``-a`` command-line options. For example:: - - python setup.py test -a "-epy27" - -is equivalent to running ``tox -epy27``. - -Ignoring a command exit code ----------------------------- - -In some cases, you may want to ignore a command exit code. For example:: - - [testenv:py27] - commands = coverage erase - {envbindir}/python setup.py develop - coverage run -p setup.py test - coverage combine - - coverage html - {envbindir}/flake8 loads - -By using the ``-`` prefix, similar to a ``make`` recipe line, you can ignore -the exit code for that command. - -Compressing dependency matrix ------------------------------ - -If you have a large matrix of dependencies, python versions and/or environments you can -use :ref:`generative-envlist` and :ref:`conditional settings <factors>` to express that in a concise form:: - - [tox] - envlist = py{26,27,33}-django{15,16}-{sqlite,mysql} - - [testenv] - deps = - django15: Django>=1.5,<1.6 - django16: Django>=1.6,<1.7 - py33-mysql: PyMySQL ; use if both py33 and mysql are in an env name - py26,py27: urllib3 ; use if any of py26 or py27 are in an env name - py{26,27}-sqlite: mock ; mocking sqlite in python 2.x diff --git a/doc/example/devenv.txt b/doc/example/devenv.txt deleted file mode 100644 index f4afc37..0000000 --- a/doc/example/devenv.txt +++ /dev/null @@ -1,78 +0,0 @@ -======================= -Development environment -======================= - -Tox can be used for just preparing different virtual environments required by a -project. - -This feature can be used by deployment tools when preparing deployed project -environments. It can also be used for setting up normalized project development -environments and thus help reduce the risk of different team members using -mismatched development environments. - -Here are some examples illustrating how to set up a project's development -environment using tox. For illustration purposes, let us call the development -environment ``devenv``. - - -Example 1: Basic scenario -========================= - -Step 1 - Configure the development environment ----------------------------------------------- - -First, we prepare the tox configuration for our development environment by -defining a ``[testenv:devenv]`` section in the project's ``tox.ini`` -configuration file:: - - [testenv:devenv] - envdir = devenv - basepython = python2.7 - usedevelop = True - -In it we state: - -- what directory to locate the environment in, -- what Python executable to use in the environment, -- that our project should be installed into the environment using ``setup.py - develop``, as opposed to building and installing its source distribution using - ``setup.py install``. - -Actually, we can configure a lot more, and these are only the required settings. -For example, we can add the following to our configuration, telling tox not to -reuse ``commands`` or ``deps`` settings from the base ``[testenv]`` -configuration:: - - commands = - deps = - - -Step 2 - Create the development environment -------------------------------------------- - -Once the ``[testenv:devenv]`` configuration section has been defined, we create -the actual development environment by running the following:: - - tox -e devenv - -This creates the environment at the path specified by the environment's -``envdir`` configuration value. - - -Example 2: A more complex scenario -================================== - -Let us say we want our project development environment to: - -- be located in the ``devenv`` directory, -- use Python executable ``python2.7``, -- pull packages from ``requirements.txt``, located in the same directory as - ``tox.ini``. - -Here is an example configuration for the described scenario:: - - [testenv:devenv] - envdir = devenv - basepython = python2.7 - usedevelop = True - deps = -rrequirements.txt diff --git a/doc/example/general.txt b/doc/example/general.txt deleted file mode 100644 index 1a27549..0000000 --- a/doc/example/general.txt +++ /dev/null @@ -1,182 +0,0 @@ -.. be in -*- rst -*- mode! - -General tips and tricks -================================ - -Interactively passing positional arguments ------------------------------------------------ - -If you invoke ``tox`` like this:: - - tox -- -x tests/test_something.py - -the arguments after the ``--`` will be substituted -everywhere where you specify ``{posargs}`` in your -test commands, for example using ``py.test``:: - - # in the testenv or testenv:NAME section of your tox.ini - commands = - py.test {posargs} - -or using ``nosetests``:: - - commands = - nosetests {posargs} - -the above ``tox`` invocation will trigger the test runners to -stop after the first failure and to only run a particular test file. - -You can specify defaults for the positional arguments using this -syntax:: - - commands = - nosetests {posargs:--with-coverage} - -.. _`sphinx checks`: - -Integrating "sphinx" documentation checks ----------------------------------------------- - -In a ``testenv`` environment you can specify any command and -thus you can easily integrate sphinx_ documentation integrity during -a tox test run. Here is an example ``tox.ini`` configuration:: - - [testenv:docs] - basepython=python - changedir=doc - deps=sphinx - commands= - sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html - -This will create a dedicated ``docs`` virtual environment and install -the ``sphinx`` dependency which itself will install the ``sphinx-build`` tool -which you can then use as a test command. Note that sphinx output is redirected -to the virtualenv environment temporary directory to prevent sphinx -from caching results between runs. - -You can now call:: - - tox - -which will make the sphinx tests part of your test run. - - -.. _`TOXENV`: - -Selecting one or more environments to run tests against --------------------------------------------------------- - -Using the ``-e ENV[,ENV2,...]`` option you explicitely list -the environments where you want to run tests against. For -example, given the previous sphinx example you may call:: - - tox -e docs - -which will make ``tox`` only manage the ``docs`` environment -and call its test commands. You may specify more than -one environment like this:: - - tox -e py25,py26 - -which would run the commands of the ``py25`` and ``py26`` testenvironments -respectively. The special value ``ALL`` selects all environments. - -You can also specify an environment list in your ``tox.ini``:: - - [tox] - envlist = py25,py26 - -or override it from the command line or from the environment variable -``TOXENV``:: - - export TOXENV=py25,py26 # in bash style shells - -.. _artifacts: - -Access package artifacts between multiple tox-runs --------------------------------------------------------- - -If you have multiple projects using tox you can make use of -a ``distshare`` directory where ``tox`` will copy in sdist-packages so -that another tox run can find the "latest" dependency. This feature -allows to test a package against an unreleased development version -or even an uncommitted version on your own machine. - -By default, ``{homedir}/.tox/distshare`` will be used for -copying in and copying out artifacts (i.e. Python packages). - -For project ``two`` to depend on the ``one`` package you use -the following entry:: - - # example two/tox.ini - [testenv] - deps= - {distshare}/one-*.zip # install latest package from "one" project - -That's all. Tox running on project ``one`` will copy the sdist-package -into the ``distshare`` directory after which a ``tox`` run on project -``two`` will grab it because ``deps`` contain an entry with the -``one-*.zip`` pattern. If there is more than one matching package the -highest version will be taken. ``tox`` uses verlib_ to compare version -strings which must be compliant with :pep:`386`. - -If you want to use this with Jenkins_, also checkout the :ref:`jenkins artifact example`. - -.. _verlib: https://bitbucket.org/tarek/distutilsversion/ - -basepython defaults, overriding -++++++++++++++++++++++++++++++++++++++++++ - -By default, for any ``pyXY`` test environment name -the underlying "pythonX.Y" executable will be searched in -your system ``PATH``. It must exist in order to successfully create -virtualenv environments. On Windows a ``pythonX.Y`` named executable -will be searched in typical default locations using the -``C:\PythonX.Y\python.exe`` pattern. - -For ``jython`` and ``pypy`` the respective ``jython`` -and ``pypy-c`` names will be looked for. - -You can override any of the default settings by defining -the ``basepython`` variable in a specific test environment -section, for example:: - - [testenv:py27] - basepython=/my/path/to/python2.7 - -Avoiding expensive sdist ------------------------- - -Some projects are large enough that running an sdist, followed by -an install every time can be prohibitively costly. To solve this, -there are two different options you can add to the ``tox`` section. First, -you can simply ask tox to please not make an sdist:: - - [tox] - skipsdist=True - -If you do this, your local software package will not be installed into -the virtualenv. You should probably be okay with that, or take steps -to deal with it in your commands section:: - - [testenv] - commands = - python setup.py develop - py.test - -Running ``setup.py develop`` is a common enough model that it has its own -option:: - - [testenv] - usedevelop=True - -And a corresponding command line option ``--develop``, which will set -``skipsdist`` to True and then perform the ``setup.py develop`` -step at the place where ``tox`` normally perfoms the installation of the sdist. -Specifically, it actually runs ``pip install -e .`` behind the scenes, which -itself calls ``setup.py develop``. - -There is an optimization coded in to not bother re-running the command if -``$projectname.egg-info`` is newer than ``setup.py`` or ``setup.cfg``. - -.. include:: ../links.txt diff --git a/doc/example/jenkins.txt b/doc/example/jenkins.txt deleted file mode 100644 index 94cb22d..0000000 --- a/doc/example/jenkins.txt +++ /dev/null @@ -1,174 +0,0 @@ - -Using Tox with the Jenkins Integration Server -================================================= - -Using Jenkins multi-configuration jobs -------------------------------------------- - -The Jenkins_ continuous integration server allows to define "jobs" with -"build steps" which can be test invocations. If you :doc:`install <../install>` ``tox`` on your -default Python installation on each Jenkins slave, you can easily create -a Jenkins multi-configuration job that will drive your tox runs from the CI-server side, -using these steps: - -* install the Python plugin for Jenkins under "manage jenkins" -* create a "multi-configuration" job, give it a name of your choice -* configure your repository so that Jenkins can pull it -* (optional) configure multiple nodes so that tox-runs are performed - on multiple hosts -* configure ``axes`` by using :ref:`TOXENV <TOXENV>` as an axis - name and as values provide space-separated test environment names - you want Jenkins/tox to execute. - -* add a **Python-build step** with this content (see also next example):: - - import tox - tox.cmdline() # environment is selected by ``TOXENV`` env variable - -* check ``Publish JUnit test result report`` and enter - ``**/junit-*.xml`` as the pattern so that Jenkins collects - test results in the JUnit XML format. - -The last point requires that your test command creates JunitXML files, -for example with ``py.test`` it is done like this: - -.. code-block:: ini - - commands = py.test --junitxml=junit-{envname}.xml - - - -**zero-installation** for slaves -------------------------------------------------------------- - -.. note:: - - This feature is broken currently because "toxbootstrap.py" - has been removed. Please file an issue if you'd like to - see it back. - -If you manage many Jenkins slaves and want to use the latest officially -released tox (or latest development version) and want to skip manually -installing ``tox`` then substitute the above **Python build step** code -with this:: - - import urllib, os - url = "https://bitbucket.org/hpk42/tox/raw/default/toxbootstrap.py" - #os.environ['USETOXDEV']="1" # use tox dev version - d = dict(__file__='toxbootstrap.py') - exec urllib.urlopen(url).read() in d - d['cmdline'](['--recreate']) - -The downloaded `toxbootstrap.py` file downloads all neccessary files to -install ``tox`` in a virtual sub environment. Notes: - -* uncomment the line containing ``USETOXDEV`` to use the latest - development-release version of tox instead of the - latest released version. - -* adapt the options in the last line as needed (the example code - will cause tox to reinstall all virtual environments all the time - which is often what one wants in CI server contexts) - - -Integrating "sphinx" documentation checks in a Jenkins job ----------------------------------------------------------------- - -If you are using a multi-configuration Jenkins job which collects -JUnit Test results you will run into problems using the previous -method of running the sphinx-build command because it will not -generate JUnit results. To accomodate this issue one solution -is to have ``py.test`` wrap the sphinx-checks and create a -JUnit result file which wraps the result of calling sphinx-build. -Here is an example: - -1. create a ``docs`` environment in your ``tox.ini`` file like this:: - - [testenv:docs] - basepython=python - changedir=doc # or whereever you keep your sphinx-docs - deps=sphinx - py - commands= - py.test --tb=line -v --junitxml=junit-{envname}.xml check_sphinx.py - -2. create a ``doc/check_sphinx.py`` file like this:: - - import py - import subprocess - def test_linkcheck(tmpdir): - doctrees = tmpdir.join("doctrees") - htmldir = tmpdir.join("html") - subprocess.check_call( - ["sphinx-build", "-W", "-blinkcheck", - "-d", str(doctrees), ".", str(htmldir)]) - def test_build_docs(tmpdir): - doctrees = tmpdir.join("doctrees") - htmldir = tmpdir.join("html") - subprocess.check_call([ - "sphinx-build", "-W", "-bhtml", - "-d", str(doctrees), ".", str(htmldir)]) - -3. run ``tox -e docs`` and then you may integrate this environment - along with your other environments into Jenkins. - -Note that ``py.test`` is only installed into the docs environment -and does not need to be in use or installed with any other environment. - -.. _`jenkins artifact example`: - -Access package artifacts between Jenkins jobs --------------------------------------------------------- - -.. _`Jenkins Copy Artifact plugin`: http://wiki.jenkins-ci.org/display/HUDSON/Copy+Artifact+Plugin - -In an extension to :ref:`artifacts` you can also configure Jenkins jobs to -access each others artifacts. ``tox`` uses the ``distshare`` directory -to access artifacts and in a Jenkins context (detected via existence -of the environment variable ``HUDSON_URL``); it defaults to -to ``{toxworkdir}/distshare``. - -This means that each workspace will have its own ``distshare`` -directory and we need to configure Jenkins to perform artifact copying. -The recommend way to do this is to install the `Jenkins Copy Artifact plugin`_ -and for each job which "receives" artifacts you add a **Copy artifacts from another project** build step using roughly this configuration:: - - Project-name: name of the other (tox-managed) job you want the artifact from - Artifacts to copy: .tox/dist/*.zip # where tox jobs create artifacts - Target directory: .tox/distshare # where we want it to appear for us - Flatten Directories: CHECK # create no subdir-structure - -You also need to configure the "other" job to archive artifacts; This -is done by checking ``Archive the artifacts`` and entering:: - - Files to archive: .tox/dist/*.zip - -So our "other" job will create an sdist-package artifact and -the "copy-artifacts" plugin will copy it to our ``distshare`` area. -Now everything proceeds as :ref:`artifacts` shows it. - -So if you are using defaults you can re-use and debug exactly the -same ``tox.ini`` file and make use of automatic sharing of -your artifacts between runs or Jenkins jobs. - - -Avoiding the "path too long" error with long shebang lines ---------------------------------------------------------------- - -If you are using Jenkins builds you might run into the issue -that tox can not call ``pip`` because the so called "shebang" -line is too long. There is a limit of 127 chars on some systems. -Probably the best way to fix the problem is to use the -new ``--workdir`` option which tells tox to use a specific -directory for its virtualenvironments. Set it to some unique -enough short path. If somebody is interested to do a PR -you could add a new option to tox which uses a random -directory for storing its workdir results and removes -it after the tox run finishes. This could be used -from CI environments where you probably anyway want -to recreate everything on new runs. - - -.. include:: ../links.txt - - diff --git a/doc/example/nose.txt b/doc/example/nose.txt deleted file mode 100644 index ec97f18..0000000 --- a/doc/example/nose.txt +++ /dev/null @@ -1,41 +0,0 @@ - -nose and tox -================================= - -It is easy to integrate `nosetests`_ runs with tox. -For starters here is a simple ``tox.ini`` config to configure your project -for running with nose: - -Basic nosetests example --------------------------- - -Assuming the following layout:: - - tox.ini # see below for content - setup.py # a classic distutils/setuptools setup.py file - -and the following ``tox.ini`` content:: - - [testenv] - deps=nose - commands= - nosetests \ - [] # substitute with tox' positional arguments - -you can invoke ``tox`` in the directory where your ``tox.ini`` resides. -``tox`` will sdist-package your project create two virtualenv environments -with the ``python2.6`` and ``python2.5`` interpreters, respectively, and will -then run the specified test command. - - -More examples? ------------------------------------------- - -You can use and combine other features of ``tox`` with your tox runs, -e.g. :ref:`sphinx checks`. If you figure out some particular configurations -for nose/tox interactions please submit them. - -Also you might want to checkout :doc:`general`. - -.. include:: ../links.txt - diff --git a/doc/example/pytest.txt b/doc/example/pytest.txt deleted file mode 100755 index 6f98cf3..0000000 --- a/doc/example/pytest.txt +++ /dev/null @@ -1,111 +0,0 @@ - -py.test and tox -================================= - -It is easy to integrate `py.test`_ runs with tox. If you encounter -issues, please check if they are `listed as a known issue`_ and/or use -the :doc:`support channels <../support>`. - -Basic example --------------------------- - -Assuming the following layout:: - - tox.ini # see below for content - setup.py # a classic distutils/setuptools setup.py file - -and the following ``tox.ini`` content:: - - [tox] - envlist = py26,py31 - - [testenv] - deps=pytest # PYPI package providing py.test - commands= - py.test \ - {posargs} # substitute with tox' positional arguments - -you can now invoke ``tox`` in the directory where your ``tox.ini`` resides. -``tox`` will sdist-package your project, create two virtualenv environments -with the ``python2.6`` and ``python3.1`` interpreters, respectively, and will -then run the specified test command in each of them. - -Extended example: change dir before test and use per-virtualenv tempdir --------------------------------------------------------------------------- - -Assuming the following layout:: - - tox.ini # see below for content - setup.py # a classic distutils/setuptools setup.py file - tests # the directory containing tests - -and the following ``tox.ini`` content:: - - [tox] - envlist = py26,py31 - [testenv] - changedir=tests - deps=pytest - commands= - py.test \ - --basetemp={envtmpdir} \ # py.test tempdir setting - {posargs} # substitute with tox' positional arguments - -you can invoke ``tox`` in the directory where your ``tox.ini`` resides. -Differently than in the previous example the ``py.test`` command -will be executed with a current working directory set to ``tests`` -and the test run will use the per-virtualenv temporary directory. - -.. _`passing positional arguments`: - -Using multiple CPUs for test runs ------------------------------------ - -``py.test`` supports distributing tests to multiple processes and hosts -through the `pytest-xdist`_ plugin. Here is an example configuration -to make ``tox`` use this feature:: - - [testenv] - deps=pytest-xdist - changedir=tests - commands= - py.test \ - --basetemp={envtmpdir} \ - --confcutdir=.. \ - -n 3 \ # use three sub processes - {posargs} - -.. _`listed as a known issue`: - -Known Issues and limitations ------------------------------ - -**Too long filenames**. you may encounter "too long filenames" for temporarily -created files in your py.test run. Try to not use the "--basetemp" parameter. - -**installed-versus-checkout version**. ``py.test`` collects test -modules on the filesystem and then tries to import them under their -`fully qualified name`_. This means that if your test files are -importable from somewhere then your ``py.test`` invocation may end up -importing the package from the checkout directory rather than the -installed package. - -There are a few ways to prevent this. - -With installed tests (the tests packages are known to ``setup.py``), a -safe and explicit option is to give the explicit path -``{envsitepackagesdir}/mypkg`` to pytest. -Alternatively, it is possible to use ``changedir`` so that checked-out -files are outside the import path, then pass ``--pyargs mypkg`` to -pytest. - -With tests that won't be installed, the simplest way to run them -against your installed package is to avoid ``__init__.py`` files in test -directories; pytest will still find and import them by adding their -parent directory to ``sys.path`` but they won't be copied to -other places or be found by Python's import system outside of pytest. - -.. _`fully qualified name`: http://pytest.org/latest/goodpractises.html#test-package-name - - -.. include:: ../links.txt diff --git a/doc/example/result.txt b/doc/example/result.txt deleted file mode 100644 index b3b95b4..0000000 --- a/doc/example/result.txt +++ /dev/null @@ -1,44 +0,0 @@ - -Writing a json result file --------------------------------------------------------- - -.. versionadded: 1.6 - -You can instruct tox to write a json-report file via:: - - tox --result-json=PATH - -This will create a json-formatted result file using this schema:: - - { - "testenvs": { - "py27": { - "python": { - "executable": "/home/hpk/p/tox/.tox/py27/bin/python", - "version": "2.7.3 (default, Aug 1 2012, 05:14:39) \n[GCC 4.6.3]", - "version_info": [ 2, 7, 3, "final", 0 ] - }, - "test": [ - { - "output": "...", - "command": [ - "/home/hpk/p/tox/.tox/py27/bin/py.test", - "--instafail", - "--junitxml=/home/hpk/p/tox/.tox/py27/log/junit-py27.xml", - "tests/test_config.py" - ], - "retcode": "0" - } - ], - "setup": [] - } - }, - "platform": "linux2", - "installpkg": { - "basename": "tox-1.6.0.dev1.zip", - "sha256": "b6982dde5789a167c4c35af0d34ef72176d0575955f5331ad04aee9f23af4326", - "md5": "27ead99fd7fa39ee7614cede6bf175a6" - }, - "toxversion": "1.6.0.dev1", - "reportversion": "1" - } diff --git a/doc/example/unittest.txt b/doc/example/unittest.txt deleted file mode 100644 index 5dcaa8e..0000000 --- a/doc/example/unittest.txt +++ /dev/null @@ -1,89 +0,0 @@ - -unittest2, discover and tox -=============================== - -Running unittests with 'discover' ------------------------------------------- - -.. _Pygments: http://pypi.python.org/pypi/Pygments - -The discover_ project allows to discover and run unittests -and we can easily integrate it in a ``tox`` run. As an example, -perform a checkout of Pygments_:: - - hg clone https://bitbucket.org/birkenfeld/pygments-main - -and add the following ``tox.ini`` to it:: - - [tox] - envlist = py25,py26,py27 - - [testenv] - changedir=tests - commands=discover - deps=discover - -If you now invoke ``tox`` you will see the creation of -three virtual environments and a unittest-run performed -in each of them. - -Running unittest2 and sphinx tests in one go ------------------------------------------------------ - -.. _`Michael Foord`: http://www.voidspace.org.uk/ -.. _tox.ini: http://code.google.com/p/mock/source/browse/tox.ini - -`Michael Foord`_ has contributed a ``tox.ini`` file that -allows you to run all tests for his mock_ project, -including some sphinx-based doctests. If you checkout -its repository with: - - hg clone https://code.google.com/p/mock/ - -the checkout has a tox.ini_ that looks like this:: - - [tox] - envlist = py24,py25,py26,py27 - - [testenv] - deps=unittest2 - commands=unit2 discover [] - - [testenv:py26] - commands= - unit2 discover [] - sphinx-build -b doctest docs html - sphinx-build docs html - deps = - unittest2 - sphinx - - [testenv:py27] - commands= - unit2 discover [] - sphinx-build -b doctest docs html - sphinx-build docs html - deps = - unittest2 - sphinx - -mock uses unittest2_ to run the tests. Invoking ``tox`` starts test -discovery by executing the ``unit2 discover`` -commands on Python 2.4, 2.5, 2.6 and 2.7 respectively. Against -Python2.6 and Python2.7 it will additionally run sphinx-mediated -doctests. If building the docs fails, due to a reST error, or -any of the doctests fails, it will be reported by the tox run. - -The ``[]`` parentheses in the commands provide :ref:`positional substitution` which means -you can e.g. type:: - - tox -- -f -s SOMEPATH - -which will ultimately invoke:: - - unit2 discover -f -s SOMEPATH - -in each of the environments. This allows you to customize test discovery -in your ``tox`` runs. - -.. include:: ../links.txt |