py.test/pylib installation info in a nutshell

Pythons: 2.4, 2.5, 2.6, 3.0, 3.1, Jython-2.5.1, PyPy-1.1

Operating systems: Linux, Windows, OSX, Unix

Requirements: setuptools or Distribute

Installers: easy_install and pip or standalone (new for 1.2)

Distribution names:

Installed scripts: see bin for which and how scripts are installed.

hg repository: https://bitbucket.org/hpk42/py-trunk

Best practise: install tool and dependencies virtually

It is recommended to work with virtual environments (e.g. virtualenv or buildout based) and use easy_install (or pip) for installing py.test/pylib and any dependencies you need to run your tests. Local virtual Python environments (as opposed to system-wide "global" environments) make for a more reproducible and reliable test environment.

using easy_install (from setuptools or Distribute)

Both Distribute and setuptools provide the easy_install installation tool. While setuptools should work ok with Python2 interpreters, Distribute also works with Python3 and it avoids some issues on Windows. In both cases you can open a command line window and then type:

easy_install -U py

to install the latest release of the py lib and py.test. The -U switch will trigger an upgrade if you already have an older version installed.

If you now type:

py.test --version

you should see the version number and the import location of the tool. Maybe you want to head on with the quickstart now?

Generating a py.test standalone Script

If you are a maintainer or application developer and want users to run tests you can use a facility to generate a standalone "py.test" script that you can tell users to run:

py.test --genscript=mytest

will generate a mytest script that is, in fact, a py.test under disguise. You can tell people to download and then e.g. run it like this:

python mytest --pastebin=all

and ask them to send you the resulting URL. The resulting script has all core features and runs unchanged under Python2 and Python3 interpreters.

Troubleshooting

On Linux: If easy_install fails because it needs to run as the superuser you are trying to install things globally and need to put sudo in front of the command.

On Windows: If "easy_install" or "py.test" are not found please see here: How do i run a Python program under Windows?

Working from version control or a tarball

To follow development or start experiments, checkout the complete code and documentation source with mercurial:

hg clone https://bitbucket.org/hpk42/py-trunk/

Development takes place on the 'trunk' branch.

You can also go to the python package index and download and unpack a TAR file:

http://pypi.python.org/pypi/py/

activating a checkout with setuptools

With a working Distribute or setuptools installation you can type:

python setup.py develop

in order to work inline with the tools and the lib of your checkout.

directly use a checkout or tarball / avoid setuptools

Get a checkout or tarball and add paths to your environment variables:

  • PYTHONPATH needs to contain the root directory (where py resides)
  • PATH needs to contain ROOT/bin or ROOT\bin\win32 respectively.

There also are helper scripts that set the variables accordingly. On windows execute:

# inside autoexec.bat or shell startup
c:\\path\to\checkout\bin\env.cmd

on linux/OSX add this to your shell initialization:

# inside e.g. .bashrc
eval `python ~/path/to/checkout/bin/env.py`

both of which which will get you good settings. If you install the pylib this way you can easily hg pull && hg up or download a new tarball to follow the development tree.

Note that the scripts manually added like this will look for py libs in the chain of parent directories of the current working dir. For example, if you have a layout like this:

mypkg/
    subpkg1/
        tests/
    tests/
py/

issuing py.test subpkg1 will use the py lib from that projects root directory. If in doubt over where the pylib comes from you can always do:

py.test --version

to see where py.test is imported from.