.TH "PY.TEST" "1" "June 24, 2012" "2.2" "pytest"
.SH NAME
pytest \- pytest usage
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.SH CALLING PY.TEST THROUGH PYTHON -M PY.TEST
.sp
New in version 2.0.
.sp
If you use Python\-2.5 or later you can invoke testing through the
Python interpreter from the command line:
.sp
.nf
.ft C
python \-m pytest [...]
.ft P
.fi
.sp
This is equivalent to invoking the command line script \fBpy.test [...]\fP
directly.
.SH GETTING HELP ON VERSION, OPTION NAMES, ENVIRONMENT VARIABLES
.sp
.nf
.ft C
py.test \-\-version   # shows where pytest was imported from
py.test \-\-funcargs  # show available builtin function arguments
py.test \-h | \-\-help # show help on command line and config file options
.ft P
.fi
.SH STOPPING AFTER THE FIRST (OR N) FAILURES
.sp
To stop the testing process after the first (N) failures:
.sp
.nf
.ft C
py.test \-x            # stop after first failure
py.test \-\-maxfail=2    # stop after two failures
.ft P
.fi
.SH SPECIFYING TESTS / SELECTING TESTS
.sp
Several test run options:
.sp
.nf
.ft C
py.test test_mod.py   # run tests in module
py.test somepath      # run all tests below path
py.test \-k string     # only run tests whose names contain a string
.ft P
.fi
.sp
Import \(aqpkg\(aq and use its filesystem location to find and run tests:
.sp
.nf
.ft C
py.test \-\-pyargs pkg # run all tests found below directory of pypkg
.ft P
.fi
.SH MODIFYING PYTHON TRACEBACK PRINTING
.sp
Examples for modifying traceback printing:
.sp
.nf
.ft C
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
.ft P
.fi
.SH DROPPING TO PDB (PYTHON DEBUGGER) ON FAILURES
.sp
Python comes with a builtin Python debugger called \fI\%PDB\fP.  \fBpy.test\fP
allows one to drop into the PDB prompt via a command line option:
.sp
.nf
.ft C
py.test \-\-pdb
.ft P
.fi
.sp
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:
.sp
.nf
.ft C
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
.ft P
.fi
.SH SETTING A BREAKPOINT / AKA SET_TRACE()
.sp
If you want to set a breakpoint and enter the \fBpdb.set_trace()\fP you
can use a helper:
.sp
.nf
.ft C
import pytest
def test_function():
    ...
    pytest.set_trace()    # invoke PDB debugger and tracing
.ft P
.fi
.sp
In previous versions you could only enter PDB tracing if
you disabled capturing on the command line via \fBpy.test \-s\fP.
.SH PROFILING TEST EXECUTION DURATION
.sp
To get a list of the slowest 10 test durations:
.sp
.nf
.ft C
py.test \-\-durations=10
.ft P
.fi
.SH CREATING JUNITXML FORMAT FILES
.sp
To create result files which can be read by \fI\%Hudson\fP or other Continuous
integration servers, use this invocation:
.sp
.nf
.ft C
py.test \-\-junitxml=path
.ft P
.fi
.sp
to create an XML file at \fBpath\fP.
.SH CREATING RESULTLOG FORMAT FILES
.sp
To create plain\-text machine\-readable result files you can issue:
.sp
.nf
.ft C
py.test \-\-resultlog=path
.ft P
.fi
.sp
and look at the content at the \fBpath\fP location.  Such files are used e.g.
by the \fI\%PyPy-test\fP web page to show test results over several revisions.
.SH SENDING TEST REPORT TO POCOO PASTEBIN SERVICE
.sp
\fBCreating a URL for each test failure\fP:
.sp
.nf
.ft C
py.test \-\-pastebin=failed
.ft P
.fi
.sp
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 \fB\-x\fP if you only want to send one particular failure.
.sp
\fBCreating a URL for a whole test session log\fP:
.sp
.nf
.ft C
py.test \-\-pastebin=all
.ft P
.fi
.sp
Currently only pasting to the \fI\%http://paste.pocoo.org\fP service is implemented.
.SH CALLING PY.TEST FROM PYTHON CODE
.sp
New in version 2.0.
.sp
You can invoke \fBpy.test\fP from Python code directly:
.sp
.nf
.ft C
pytest.main()
.ft P
.fi
.sp
this acts as if you would call "py.test" from the command line.
It will not raise \fBSystemExit\fP but return the exitcode instead.
You can pass in options and arguments:
.sp
.nf
.ft C
pytest.main([\(aqx\(aq, \(aqmytestdir\(aq])
.ft P
.fi
.sp
or pass in a string:
.sp
.nf
.ft C
pytest.main("\-x mytestdir")
.ft P
.fi
.sp
You can specify additional plugins to \fBpytest.main\fP:
.sp
.nf
.ft C
# content of myinvoke.py
import pytest
class MyPlugin:
    def pytest_addoption(self, parser):
        raise pytest.UsageError("hi from our plugin")

pytest.main(plugins=[MyPlugin()])
.ft P
.fi
.sp
Running it will exit quickly:
.sp
.nf
.ft C
$ python myinvoke.py
ERROR: hi from our plugin
.ft P
.fi
.SH AUTHOR
holger krekel at merlinux eu
.SH COPYRIGHT
2011, holger krekel et alii
.\" Generated by docutils manpage writer.
.\" 
.