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.
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
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
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 # "string expression", e.g. "MyClass and not method" # will select TestMyClass.test_something # but not TestMyClass.test_method_simple py.test test_mod.py::test_func # only run tests that match the "node ID", # e.g "test_mod.py::test_func" will select # only test_func in test_mod.py py.test test_mod.py::TestClass::test_method # run a single method in # a single class
Import ‘pkg’ and use its filesystem location to find and run tests:
py.test --pyargs pkg # run all tests found below directory of pypkg
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
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 first three failures
Note that on any failure the exception information is stored on sys.last_value, sys.last_type and sys.last_traceback. In interactive use, this allows one to drop into postmortem debugging with any debug tool. One can also manually access the exception information, for example:
>>> import sys >>> sys.last_traceback.tb_lineno 42 >>> sys.last_value AssertionError('assert result == "ok"',)
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
Prior to pytest version 2.0.0 you could only enter PDB tracing if you disabled capturing on the command line via py.test -s. In later versions, pytest automatically disables its output capture when you enter PDB tracing:
Since pytest version 2.4.0 you can also use the native Python import pdb;pdb.set_trace() call to enter PDB tracing without having to use the pytest.set_trace() wrapper or explicitly disable pytest’s output capturing via py.test -s.
To get a list of the slowest 10 test durations:
To create result files which can be read by Hudson or other Continuous integration servers, use this invocation:
to create an XML file at path.
New in version 2.8.
If you want to log additional information for a test, you can use the record_xml_property fixture:
def test_function(record_xml_property): record_xml_property("example_key", 1) assert 0
This will add an extra property example_key="1" to the generated testcase tag:
<testcase classname="test_function" file="test_function.py" line="0" name="test_function" time="0.0009"> <properties> <property name="example_key" value="1" /> </properties> </testcase>
This is an experimental feature, and its interface might be replaced by something more powerful and general in future versions. The functionality per-se will be kept, however.
Currently it does not work when used with the pytest-xdist plugin.
Also please note that using this feature will break any schema verification. This might be a problem when used with some CI servers.
To create plain-text machine-readable result files you can issue:
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.
Creating a URL for each test failure:
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:
Currently only pasting to the http://bpaste.net service is implemented.
To disable loading specific plugins at invocation time, use the -p option together with the prefix no:.
Example: to disable loading the plugin doctest, which is responsible for executing doctest tests from text files, invoke py.test like this:
py.test -p no:doctest
New in version 2.0.
You can invoke pytest from Python code directly:
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:
or pass in a string:
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