Usage and Invocations

Calling pytest through python -m pytest

New in version 2.0.

If you use Python-2.5 or later you can invoke testing through the Python interpreter from the command line:

python -m pytest [...]

This is equivalent to invoking the command line script py.test [...] directly.

Getting help on version, option names, environment variables

py.test --version   # shows where pytest was imported from
py.test --fixtures  # show available builtin function arguments
py.test -h | --help # show help on command line and config file options

Stopping after the first (or N) failures

To stop the testing process after the first (N) failures:

py.test -x            # stop after first failure
py.test --maxfail=2    # stop after two failures

Specifying tests / selecting tests

Several test run options:

py.test test_mod.py   # run tests in module
py.test somepath      # run all tests below somepath
py.test -k stringexpr # only run tests with names that match the
                      # the "string expression", e.g. "MyClass and not method"
                      # will select TestMyClass.test_something
                      # but not TestMyClass.test_method_simple

Import ‘pkg’ and use its filesystem location to find and run tests:

py.test --pyargs pkg # run all tests found below directory of pypkg

Modifying Python traceback printing

Examples for modifying traceback printing:

py.test --showlocals # show local variables in tracebacks
py.test -l           # show local variables (shortcut)

py.test --tb=long    # the default informative traceback formatting
py.test --tb=native  # the Python standard library formatting
py.test --tb=short   # a shorter traceback format
py.test --tb=line    # only one line per failure

Dropping to PDB (Python Debugger) on failures

Python comes with a builtin Python debugger called PDB. py.test allows one to drop into the PDB prompt via a command line option:

py.test --pdb

This will invoke the Python debugger on every failure. Often you might only want to do this for the first failing test to understand a certain failure situation:

py.test -x --pdb   # drop to PDB on first failure, then end test session
py.test --pdb --maxfail=3  # drop to PDB for the first three failures

Setting a breakpoint / aka set_trace()

If you want to set a breakpoint and enter the pdb.set_trace() you can use a helper:

import pytest
def test_function():
    ...
    pytest.set_trace()    # invoke PDB debugger and tracing

In previous versions you could only enter PDB tracing if you disabled capturing on the command line via py.test -s.

Profiling test execution duration

To get a list of the slowest 10 test durations:

py.test --durations=10

Creating JUnitXML format files

To create result files which can be read by Hudson or other Continuous integration servers, use this invocation:

py.test --junitxml=path

to create an XML file at path.

Creating resultlog format files

To create plain-text machine-readable result files you can issue:

py.test --resultlog=path

and look at the content at the path location. Such files are used e.g. by the PyPy-test web page to show test results over several revisions.

Sending test report to online pastebin service

Creating a URL for each test failure:

py.test --pastebin=failed

This will submit test run information to a remote Paste service and provide a URL for each failure. You may select tests as usual or add for example -x if you only want to send one particular failure.

Creating a URL for a whole test session log:

py.test --pastebin=all

Currently only pasting to the http://bpaste.net service is implemented.

Calling pytest from Python code

New in version 2.0.

You can invoke py.test from Python code directly:

pytest.main()

this acts as if you would call “py.test” from the command line. It will not raise SystemExit but return the exitcode instead. You can pass in options and arguments:

pytest.main(['-x', 'mytestdir'])

or pass in a string:

pytest.main("-x mytestdir")

You can specify additional plugins to pytest.main:

# content of myinvoke.py
import pytest
class MyPlugin:
    def pytest_sessionfinish(self):
        print("*** test run reporting finishing")

pytest.main("-qq", plugins=[MyPlugin()])

Running it will show that MyPlugin was added and its hook was invoked:

$ python myinvoke.py
*** test run reporting finishing