NAME

       pytest - pytest usage

CALLING PY.TEST-3 THROUGH PYTHON -M PY.TEST-3

       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-3 [...]  directly.

GETTING HELP ON VERSION, OPTION NAMES, ENVIRONMENT VARIABLES

          py.test-3 --version   # shows where pytest was imported from
          py.test-3 --fixtures  # show available builtin function arguments
          py.test-3 -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-3 -x            # stop after first failure
          py.test-3 --maxfail=2    # stop after two failures

SPECIFYING TESTS / SELECTING TESTS

       Several test run options:

          py.test-3 test_mod.py   # run tests in module
          py.test-3 somepath      # run all tests below somepath
          py.test-3 -k stringexpr # only run tests with names that match the
                                # the "string expression", e.g. "MyClass and not method"
                                # will select TestMyClass.test_something
                                # but not TestMyClass.test_method_simple

       Import 'pkg' and use its filesystem location to find and run tests:

          py.test-3 --pyargs pkg # run all tests found below directory of pypkg

MODIFYING PYTHON TRACEBACK PRINTING

       Examples for modifying traceback printing:

          py.test-3 --showlocals # show local variables in tracebacks
          py.test-3 -l           # show local variables (shortcut)

          py.test-3 --tb=long    # the default informative traceback formatting
          py.test-3 --tb=native  # the Python standard library formatting
          py.test-3 --tb=short   # a shorter traceback format
          py.test-3 --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-3 allows one to drop into
       the PDB prompt via a command line option:

          py.test-3 --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-3 -x --pdb   # drop to PDB on first failure, then end test session
          py.test-3 --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-3 -s.

PROFILING TEST EXECUTION DURATION

       To get a list of the slowest 10 test durations:

          py.test-3 --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-3 --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-3 --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-3 --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-3 --pastebin=all

       Currently only pasting to the http://bpaste.net service is implemented.

CALLING PY.TEST-3 FROM PYTHON CODE

       New in version 2.0.

       You can invoke py.test-3 from Python code directly:

          pytest.main()

       this  acts  as  if  you  would  call "py.test-3" 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

AUTHOR

       holger krekel at merlinux eu

COPYRIGHT

       2012, holger krekel