176 lines
4.9 KiB
Plaintext
176 lines
4.9 KiB
Plaintext
|
|
.. _usage:
|
|
|
|
Usage and Invocations
|
|
==========================================
|
|
|
|
|
|
.. _cmdline:
|
|
|
|
Calling pytest through ``python -m pytest``
|
|
-----------------------------------------------------
|
|
|
|
.. versionadded:: 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 --funcargs # 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 path
|
|
py.test -k string # only run tests whose names contain a string
|
|
|
|
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
|
|
----------------------------------------------
|
|
|
|
.. _PDB: http://docs.python.org/library/pdb.html
|
|
|
|
Python comes with a builtin Python debugger called PDB_. ``py.test``
|
|
allows 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
|
|
|
|
.. versionadded: 2.0.0
|
|
|
|
In previous versions you could only enter PDB tracing if
|
|
you disable capturing on the command line via ``py.test -s``.
|
|
|
|
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.
|
|
|
|
.. _`PyPy-test`: http://codespeak.net:8099/summary
|
|
|
|
|
|
Sending test report to pocoo 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://paste.pocoo.org service is implemented.
|
|
|
|
Calling pytest from Python code
|
|
----------------------------------------------------
|
|
|
|
.. versionadded:: 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_addoption(self, parser):
|
|
raise pytest.UsageError("hi from our plugin")
|
|
|
|
pytest.main(plugins=[MyPlugin()])
|
|
|
|
Running it will exit quickly::
|
|
|
|
$ python myinvoke.py
|
|
ERROR: hi from our plugin
|
|
|
|
.. include:: links.inc
|