.. _cmdline:

Using the interactive command line
===============================================

Getting help on version, option names, environment vars
-----------------------------------------------------------

::

    py.test --version   # shows where pytest was imported from
    py.test --funcargs  # show available builtin function arguments
    py.test --help-config # show configuration values
    
    py.test -h | --help # show help


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

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

    def test_function():
        ...
        py.test.set_trace()    # invoke PDB debugger and tracing

.. versionadded: 2.0.0

In previous versions you could only enter PDB tracing if
you :ref:`disable capturing`.

creating JUnitXML format files
----------------------------------------------------

To create result files which can be read by Hudson_ or other Continous
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


send 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.

.. include:: links.inc