
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 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
=============================================

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
