Merge pull request #4783 from gyermolenko/fix_syntax_highlighting_for_two_rst_docs

Fix sphinx code-block types (syntax highlighting) in two docs
This commit is contained in:
Zac Hatfield-Dodds 2019-02-20 06:31:10 +11:00 committed by GitHub
commit c8a87e48ab
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 212 additions and 79 deletions

View File

@ -8,18 +8,26 @@ When using bash as your shell, ``pytest`` can use argcomplete
(https://argcomplete.readthedocs.io/) for auto-completion. (https://argcomplete.readthedocs.io/) for auto-completion.
For this ``argcomplete`` needs to be installed **and** enabled. For this ``argcomplete`` needs to be installed **and** enabled.
Install argcomplete using:: Install argcomplete using:
.. code-block:: bash
sudo pip install 'argcomplete>=0.5.7' sudo pip install 'argcomplete>=0.5.7'
For global activation of all argcomplete enabled python applications run:: For global activation of all argcomplete enabled python applications run:
.. code-block:: bash
sudo activate-global-python-argcomplete sudo activate-global-python-argcomplete
For permanent (but not global) ``pytest`` activation, use:: For permanent (but not global) ``pytest`` activation, use:
.. code-block:: bash
register-python-argcomplete pytest >> ~/.bashrc register-python-argcomplete pytest >> ~/.bashrc
For one-time activation of argcomplete for ``pytest`` only, use:: For one-time activation of argcomplete for ``pytest`` only, use:
.. code-block:: bash
eval "$(register-python-argcomplete pytest)" eval "$(register-python-argcomplete pytest)"

View File

@ -168,7 +168,9 @@ Behavior when no tests failed in the last run
When no tests failed in the last run, or when no cached ``lastfailed`` data was When no tests failed in the last run, or when no cached ``lastfailed`` data was
found, ``pytest`` can be configured either to run all of the tests or no tests, found, ``pytest`` can be configured either to run all of the tests or no tests,
using the ``--last-failed-no-failures`` option, which takes one of the following values:: using the ``--last-failed-no-failures`` option, which takes one of the following values:
.. code-block:: bash
pytest --last-failed --last-failed-no-failures all # run all tests (default behavior) pytest --last-failed --last-failed-no-failures all # run all tests (default behavior)
pytest --last-failed --last-failed-no-failures none # run no tests and exit pytest --last-failed --last-failed-no-failures none # run no tests and exit
@ -283,7 +285,9 @@ Clearing Cache content
------------------------------- -------------------------------
You can instruct pytest to clear all cache files and values You can instruct pytest to clear all cache files and values
by adding the ``--cache-clear`` option like this:: by adding the ``--cache-clear`` option like this:
.. code-block:: bash
pytest --cache-clear pytest --cache-clear

View File

@ -35,7 +35,9 @@ There are two ways in which ``pytest`` can perform capturing:
.. _`disable capturing`: .. _`disable capturing`:
You can influence output capturing mechanisms from the command line:: You can influence output capturing mechanisms from the command line:
.. code-block:: bash
pytest -s # disable all capturing pytest -s # disable all capturing
pytest --capture=sys # replace sys.stdout/stderr with in-mem files pytest --capture=sys # replace sys.stdout/stderr with in-mem files

View File

@ -5,7 +5,9 @@ Command line options and configuration file settings
----------------------------------------------------------------- -----------------------------------------------------------------
You can get help on command line options and values in INI-style You can get help on command line options and values in INI-style
configurations files by using the general help option:: configurations files by using the general help option:
.. code-block:: bash
pytest -h # prints options _and_ config file settings pytest -h # prints options _and_ config file settings
@ -92,12 +94,16 @@ The rootdir is used a reference directory for constructing test
addresses ("nodeids") and can be used also by plugins for storing addresses ("nodeids") and can be used also by plugins for storing
per-testrun information. per-testrun information.
Example:: Example:
.. code-block:: bash
pytest path/to/testdir path/other/ pytest path/to/testdir path/other/
will determine the common ancestor as ``path`` and then will determine the common ancestor as ``path`` and then
check for ini-files as follows:: check for ini-files as follows:
.. code-block:: text
# first look for pytest.ini files # first look for pytest.ini files
path/pytest.ini path/pytest.ini
@ -133,19 +139,27 @@ progress output, you can write it into a configuration file:
addopts = -ra -q addopts = -ra -q
Alternatively, you can set a ``PYTEST_ADDOPTS`` environment variable to add command Alternatively, you can set a ``PYTEST_ADDOPTS`` environment variable to add command
line options while the environment is in use:: line options while the environment is in use:
.. code-block:: bash
export PYTEST_ADDOPTS="-v" export PYTEST_ADDOPTS="-v"
Here's how the command-line is built in the presence of ``addopts`` or the environment variable:: Here's how the command-line is built in the presence of ``addopts`` or the environment variable:
.. code-block:: text
<pytest.ini:addopts> $PYTEST_ADDOPTS <extra command-line arguments> <pytest.ini:addopts> $PYTEST_ADDOPTS <extra command-line arguments>
So if the user executes in the command-line:: So if the user executes in the command-line:
.. code-block:: bash
pytest -m slow pytest -m slow
The actual command line executed is:: The actual command line executed is:
.. code-block:: bash
pytest -ra -q -v -m slow pytest -ra -q -v -m slow

View File

@ -4,7 +4,9 @@ Doctest integration for modules and test files
By default all files matching the ``test*.txt`` pattern will By default all files matching the ``test*.txt`` pattern will
be run through the python standard ``doctest`` module. You be run through the python standard ``doctest`` module. You
can change the pattern by issuing:: can change the pattern by issuing:
.. code-block:: bash
pytest --doctest-glob='*.rst' pytest --doctest-glob='*.rst'
@ -26,7 +28,9 @@ can be given multiple times in the command-line.
You can also trigger running of doctests You can also trigger running of doctests
from docstrings in all python modules (including regular from docstrings in all python modules (including regular
python test modules):: python test modules):
.. code-block:: bash
pytest --doctest-modules pytest --doctest-modules
@ -39,7 +43,9 @@ putting them into a pytest.ini file like this:
[pytest] [pytest]
addopts = --doctest-modules addopts = --doctest-modules
If you then have a text file like this:: If you then have a text file like this:
.. code-block:: text
# content of example.rst # content of example.rst
@ -73,7 +79,9 @@ then you can just invoke ``pytest`` without command line options:
========================= 1 passed in 0.12 seconds ========================= ========================= 1 passed in 0.12 seconds =========================
It is possible to use fixtures using the ``getfixture`` helper:: It is possible to use fixtures using the ``getfixture`` helper:
.. code-block:: text
# content of example.rst # content of example.rst
>>> tmp = getfixture('tmpdir') >>> tmp = getfixture('tmpdir')
@ -112,14 +120,18 @@ the ``doctest_optionflags`` ini option:
Alternatively, it can be enabled by an inline comment in the doc test Alternatively, it can be enabled by an inline comment in the doc test
itself:: itself:
.. code-block:: rst
# content of example.rst # content of example.rst
>>> get_unicode_greeting() # doctest: +ALLOW_UNICODE >>> get_unicode_greeting() # doctest: +ALLOW_UNICODE
'Hello' 'Hello'
By default, pytest would report only the first failure for a given doctest. If By default, pytest would report only the first failure for a given doctest. If
you want to continue the test even when you have failures, do:: you want to continue the test even when you have failures, do:
.. code-block:: bash
pytest --doctest-modules --doctest-continue-on-failure pytest --doctest-modules --doctest-continue-on-failure
@ -167,7 +179,9 @@ Output format
You can change the diff output format on failure for your doctests You can change the diff output format on failure for your doctests
by using one of standard doctest modules format in options by using one of standard doctest modules format in options
(see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`, (see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`,
:data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`):: :data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`):
.. code-block:: bash
pytest --doctest-modules --doctest-report none pytest --doctest-modules --doctest-report none
pytest --doctest-modules --doctest-report udiff pytest --doctest-modules --doctest-report udiff

View File

@ -204,14 +204,18 @@ Registering markers
.. ini-syntax for custom markers: .. ini-syntax for custom markers:
Registering markers for your test suite is simple:: Registering markers for your test suite is simple:
.. code-block:: ini
# content of pytest.ini # content of pytest.ini
[pytest] [pytest]
markers = markers =
webtest: mark a test as a webtest. webtest: mark a test as a webtest.
You can ask which markers exist for your test suite - the list includes our just defined ``webtest`` markers:: You can ask which markers exist for your test suite - the list includes our just defined ``webtest`` markers:
.. code-block:: pytest
$ pytest --markers $ pytest --markers
@pytest.mark.webtest: mark a test as a webtest. @pytest.mark.webtest: mark a test as a webtest.
@ -388,7 +392,9 @@ and here is one that specifies exactly the environment needed:
========================= 1 passed in 0.12 seconds ========================= ========================= 1 passed in 0.12 seconds =========================
The ``--markers`` option always gives you a list of available markers:: The ``--markers`` option always gives you a list of available markers:
.. code-block:: pytest
$ pytest --markers $ pytest --markers
@pytest.mark.env(name): mark test to run only on named environment @pytest.mark.env(name): mark test to run only on named environment

View File

@ -6,7 +6,9 @@ Ignore paths during test collection
You can easily ignore certain test directories and modules during collection You can easily ignore certain test directories and modules during collection
by passing the ``--ignore=path`` option on the cli. ``pytest`` allows multiple by passing the ``--ignore=path`` option on the cli. ``pytest`` allows multiple
``--ignore`` options. Example:: ``--ignore`` options. Example:
.. code-block:: text
tests/ tests/
|-- example |-- example
@ -57,7 +59,9 @@ Keeping duplicate paths specified from command line
---------------------------------------------------- ----------------------------------------------------
Default behavior of ``pytest`` is to ignore duplicate paths specified from the command line. Default behavior of ``pytest`` is to ignore duplicate paths specified from the command line.
Example:: Example:
.. code-block:: pytest
pytest path_a path_a pytest path_a path_a
@ -68,7 +72,9 @@ Example::
Just collect tests once. Just collect tests once.
To collect duplicate tests, use the ``--keep-duplicates`` option on the cli. To collect duplicate tests, use the ``--keep-duplicates`` option on the cli.
Example:: Example:
.. code-block:: pytest
pytest --keep-duplicates path_a path_a pytest --keep-duplicates path_a path_a
@ -78,7 +84,9 @@ Example::
As the collector just works on directories, if you specify twice a single test file, ``pytest`` will As the collector just works on directories, if you specify twice a single test file, ``pytest`` will
still collect it twice, no matter if the ``--keep-duplicates`` is not specified. still collect it twice, no matter if the ``--keep-duplicates`` is not specified.
Example:: Example:
.. code-block:: pytest
pytest test_a.py test_a.py pytest test_a.py test_a.py
@ -90,7 +98,9 @@ Example::
Changing directory recursion Changing directory recursion
----------------------------------------------------- -----------------------------------------------------
You can set the :confval:`norecursedirs` option in an ini-file, for example your ``pytest.ini`` in the project root directory:: You can set the :confval:`norecursedirs` option in an ini-file, for example your ``pytest.ini`` in the project root directory:
.. code-block:: ini
# content of pytest.ini # content of pytest.ini
[pytest] [pytest]
@ -106,7 +116,9 @@ Changing naming conventions
You can configure different naming conventions by setting You can configure different naming conventions by setting
the :confval:`python_files`, :confval:`python_classes` and the :confval:`python_files`, :confval:`python_classes` and
:confval:`python_functions` configuration options. :confval:`python_functions` configuration options.
Here is an example:: Here is an example:
.. code-block:: ini
# content of pytest.ini # content of pytest.ini
# Example 1: have pytest look for "check" instead of "test" # Example 1: have pytest look for "check" instead of "test"
@ -145,7 +157,9 @@ The test collection would look like this:
======================= no tests ran in 0.12 seconds ======================= ======================= no tests ran in 0.12 seconds =======================
You can check for multiple glob patterns by adding a space between the patterns:: You can check for multiple glob patterns by adding a space between the patterns:
.. code-block:: ini
# Example 2: have pytest look for files with "test" and "example" # Example 2: have pytest look for files with "test" and "example"
# content of pytest.ini, tox.ini, or setup.cfg file (replace "pytest" # content of pytest.ini, tox.ini, or setup.cfg file (replace "pytest"
@ -165,13 +179,17 @@ Interpreting cmdline arguments as Python packages
You can use the ``--pyargs`` option to make ``pytest`` try You can use the ``--pyargs`` option to make ``pytest`` try
interpreting arguments as python package names, deriving interpreting arguments as python package names, deriving
their file system path and then running the test. For their file system path and then running the test. For
example if you have unittest2 installed you can type:: example if you have unittest2 installed you can type:
.. code-block:: bash
pytest --pyargs unittest2.test.test_skipping -q pytest --pyargs unittest2.test.test_skipping -q
which would run the respective test module. Like with which would run the respective test module. Like with
other options, through an ini-file and the :confval:`addopts` option you other options, through an ini-file and the :confval:`addopts` option you
can make this change more permanently:: can make this change more permanently:
.. code-block:: ini
# content of pytest.ini # content of pytest.ini
[pytest] [pytest]
@ -209,7 +227,9 @@ Customizing test collection
.. regendoc:wipe .. regendoc:wipe
You can easily instruct ``pytest`` to discover tests from every Python file:: You can easily instruct ``pytest`` to discover tests from every Python file:
.. code-block:: ini
# content of pytest.ini # content of pytest.ini
[pytest] [pytest]

View File

@ -731,7 +731,9 @@ and run them:
test_module.py:6: AssertionError test_module.py:6: AssertionError
========================= 2 failed in 0.12 seconds ========================= ========================= 2 failed in 0.12 seconds =========================
you will have a "failures" file which contains the failing test ids:: you will have a "failures" file which contains the failing test ids:
.. code-block:: bash
$ cat failures $ cat failures
test_module.py::test_fail1 (PYTEST_TMPDIR/test_fail10) test_module.py::test_fail1 (PYTEST_TMPDIR/test_fail10)
@ -935,6 +937,8 @@ like ``pytest-timeout`` they must be imported explicitly and passed on to pytest
This allows you to execute tests using the frozen This allows you to execute tests using the frozen
application with standard ``pytest`` command-line options:: application with standard ``pytest`` command-line options:
.. code-block:: bash
./app_main --pytest --verbose --tb=long --junitxml=results.xml test-suite/ ./app_main --pytest --verbose --tb=long --junitxml=results.xml test-suite/

View File

@ -114,7 +114,9 @@ with a list of available function arguments.
.. note:: .. note::
You can always issue :: You can always issue:
.. code-block:: bash
pytest --fixtures test_simplefactory.py pytest --fixtures test_simplefactory.py
@ -362,7 +364,9 @@ The ``print`` and ``smtp.close()`` statements will execute when the last test in
the module has finished execution, regardless of the exception status of the the module has finished execution, regardless of the exception status of the
tests. tests.
Let's execute it:: Let's execute it:
.. code-block:: pytest
$ pytest -s -q --tb=no $ pytest -s -q --tb=no
FFteardown smtp FFteardown smtp
@ -471,7 +475,9 @@ read an optional server URL from the test module which uses our fixture::
We use the ``request.module`` attribute to optionally obtain an We use the ``request.module`` attribute to optionally obtain an
``smtpserver`` attribute from the test module. If we just execute ``smtpserver`` attribute from the test module. If we just execute
again, nothing much has changed:: again, nothing much has changed:
.. code-block:: pytest
$ pytest -s -q --tb=no $ pytest -s -q --tb=no
FFfinalizing <smtplib.SMTP object at 0xdeadbeef> (smtp.gmail.com) FFfinalizing <smtplib.SMTP object at 0xdeadbeef> (smtp.gmail.com)

View File

@ -17,11 +17,15 @@ Installation and Getting Started
Install ``pytest`` Install ``pytest``
---------------------------------------- ----------------------------------------
1. Run the following command in your command line:: 1. Run the following command in your command line:
.. code-block:: bash
pip install -U pytest pip install -U pytest
2. Check that you installed the correct version:: 2. Check that you installed the correct version:
.. code-block:: bash
$ pytest --version $ pytest --version
This is pytest version 4.x.y, imported from $PYTHON_PREFIX/lib/python3.6/site-packages/pytest.py This is pytest version 4.x.y, imported from $PYTHON_PREFIX/lib/python3.6/site-packages/pytest.py
@ -168,7 +172,9 @@ List the name ``tmpdir`` in the test function signature and ``pytest`` will look
More info on tmpdir handling is available at :ref:`Temporary directories and files <tmpdir handling>`. More info on tmpdir handling is available at :ref:`Temporary directories and files <tmpdir handling>`.
Find out what kind of builtin :ref:`pytest fixtures <fixtures>` exist with the command:: Find out what kind of builtin :ref:`pytest fixtures <fixtures>` exist with the command:
.. code-block:: bash
pytest --fixtures # shows builtin and custom fixtures pytest --fixtures # shows builtin and custom fixtures

View File

@ -5,7 +5,7 @@ License
Distributed under the terms of the `MIT`_ license, pytest is free and open source software. Distributed under the terms of the `MIT`_ license, pytest is free and open source software.
:: .. code-block:: text
The MIT License (MIT) The MIT License (MIT)

View File

@ -9,11 +9,15 @@ Logging
pytest captures log messages of level ``WARNING`` or above automatically and displays them in their own section pytest captures log messages of level ``WARNING`` or above automatically and displays them in their own section
for each failed test in the same manner as captured stdout and stderr. for each failed test in the same manner as captured stdout and stderr.
Running without options:: Running without options:
.. code-block:: bash
pytest pytest
Shows failed tests like so:: Shows failed tests like so:
.. code-block:: pytest
----------------------- Captured stdlog call ---------------------- ----------------------- Captured stdlog call ----------------------
test_reporting.py 26 WARNING text going to logger test_reporting.py 26 WARNING text going to logger
@ -27,12 +31,16 @@ By default each captured log message shows the module, line number, log level
and message. and message.
If desired the log and date format can be specified to If desired the log and date format can be specified to
anything that the logging module supports by passing specific formatting options:: anything that the logging module supports by passing specific formatting options:
.. code-block:: bash
pytest --log-format="%(asctime)s %(levelname)s %(message)s" \ pytest --log-format="%(asctime)s %(levelname)s %(message)s" \
--log-date-format="%Y-%m-%d %H:%M:%S" --log-date-format="%Y-%m-%d %H:%M:%S"
Shows failed tests like so:: Shows failed tests like so:
.. code-block:: pytest
----------------------- Captured stdlog call ---------------------- ----------------------- Captured stdlog call ----------------------
2010-04-10 14:48:44 WARNING text going to logger 2010-04-10 14:48:44 WARNING text going to logger
@ -51,7 +59,9 @@ These options can also be customized through ``pytest.ini`` file:
log_date_format = %Y-%m-%d %H:%M:%S log_date_format = %Y-%m-%d %H:%M:%S
Further it is possible to disable reporting of captured content (stdout, Further it is possible to disable reporting of captured content (stdout,
stderr and logs) on failed tests completely with:: stderr and logs) on failed tests completely with:
.. code-block:: bash
pytest --show-capture=no pytest --show-capture=no
@ -133,7 +143,6 @@ the records for the ``setup`` and ``call`` stages during teardown like so:
.. code-block:: python .. code-block:: python
@pytest.fixture @pytest.fixture
def window(caplog): def window(caplog):
window = create_window() window = create_window()

View File

@ -12,7 +12,9 @@ Running tests written for nose
Usage Usage
------------- -------------
After :ref:`installation` type:: After :ref:`installation` type:
.. code-block:: bash
python setup.py develop # make sure tests can import our package python setup.py develop # make sure tests can import our package
pytest # instead of 'nosetests' pytest # instead of 'nosetests'

View File

@ -172,7 +172,9 @@ command line option and the parametrization of our test function::
metafunc.parametrize("stringinput", metafunc.parametrize("stringinput",
metafunc.config.getoption('stringinput')) metafunc.config.getoption('stringinput'))
If we now pass two stringinput values, our test will run twice:: If we now pass two stringinput values, our test will run twice:
.. code-block:: pytest
$ pytest -q --stringinput="hello" --stringinput="world" test_strings.py $ pytest -q --stringinput="hello" --stringinput="world" test_strings.py
.. [100%] .. [100%]

View File

@ -22,7 +22,9 @@ it's an **xpass** and will be reported in the test summary.
``pytest`` counts and lists *skip* and *xfail* tests separately. Detailed ``pytest`` counts and lists *skip* and *xfail* tests separately. Detailed
information about skipped/xfailed tests is not shown by default to avoid information about skipped/xfailed tests is not shown by default to avoid
cluttering the output. You can use the ``-r`` option to see details cluttering the output. You can use the ``-r`` option to see details
corresponding to the "short" letters shown in the test progress:: corresponding to the "short" letters shown in the test progress:
.. code-block:: bash
pytest -rxXs # show extra info on xfailed, xpassed, and skipped tests pytest -rxXs # show extra info on xfailed, xpassed, and skipped tests
@ -309,7 +311,9 @@ investigated later.
Ignoring xfail Ignoring xfail
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
By specifying on the commandline:: By specifying on the commandline:
.. code-block:: bash
pytest --runxfail pytest --runxfail

View File

@ -174,7 +174,9 @@ the system temporary directory. The base name will be ``pytest-NUM`` where
``NUM`` will be incremented with each test run. Moreover, entries older ``NUM`` will be incremented with each test run. Moreover, entries older
than 3 temporary directories will be removed. than 3 temporary directories will be removed.
You can override the default temporary directory setting like this:: You can override the default temporary directory setting like this:
.. code-block:: bash
pytest --basetemp=mydir pytest --basetemp=mydir

View File

@ -12,7 +12,9 @@ Calling pytest through ``python -m pytest``
.. versionadded:: 2.0 .. versionadded:: 2.0
You can invoke testing through the Python interpreter from the command line:: You can invoke testing through the Python interpreter from the command line:
.. code-block:: text
python -m pytest [...] python -m pytest [...]
@ -34,7 +36,7 @@ Running ``pytest`` can result in six different exit codes:
Getting help on version, option names, environment variables Getting help on version, option names, environment variables
-------------------------------------------------------------- --------------------------------------------------------------
:: .. code-block:: bash
pytest --version # shows where pytest was imported from pytest --version # shows where pytest was imported from
pytest --fixtures # show available builtin function arguments pytest --fixtures # show available builtin function arguments
@ -46,7 +48,9 @@ Getting help on version, option names, environment variables
Stopping after the first (or N) failures Stopping after the first (or N) failures
--------------------------------------------------- ---------------------------------------------------
To stop the testing process after the first (N) failures:: To stop the testing process after the first (N) failures:
.. code-block:: bash
pytest -x # stop after first failure pytest -x # stop after first failure
pytest --maxfail=2 # stop after two failures pytest --maxfail=2 # stop after two failures
@ -60,19 +64,19 @@ Pytest supports several ways to run and select tests from the command-line.
**Run tests in a module** **Run tests in a module**
:: .. code-block:: bash
pytest test_mod.py pytest test_mod.py
**Run tests in a directory** **Run tests in a directory**
:: .. code-block:: bash
pytest testing/ pytest testing/
**Run tests by keyword expressions** **Run tests by keyword expressions**
:: .. code-block:: bash
pytest -k "MyClass and not method" pytest -k "MyClass and not method"
@ -87,18 +91,22 @@ The example above will run ``TestMyClass.test_something`` but not ``TestMyClass
Each collected test is assigned a unique ``nodeid`` which consist of the module filename followed Each collected test is assigned a unique ``nodeid`` which consist of the module filename followed
by specifiers like class names, function names and parameters from parametrization, separated by ``::`` characters. by specifiers like class names, function names and parameters from parametrization, separated by ``::`` characters.
To run a specific test within a module:: To run a specific test within a module:
.. code-block:: bash
pytest test_mod.py::test_func pytest test_mod.py::test_func
Another example specifying a test method in the command line:: Another example specifying a test method in the command line:
.. code-block:: bash
pytest test_mod.py::TestClass::test_method pytest test_mod.py::TestClass::test_method
**Run tests by marker expressions** **Run tests by marker expressions**
:: .. code-block:: bash
pytest -m slow pytest -m slow
@ -108,7 +116,7 @@ For more information see :ref:`marks <mark>`.
**Run tests from packages** **Run tests from packages**
:: .. code-block:: bash
pytest --pyargs pkg.testing pytest --pyargs pkg.testing
@ -118,7 +126,9 @@ This will import ``pkg.testing`` and use its filesystem location to find and run
Modifying Python traceback printing Modifying Python traceback printing
---------------------------------------------- ----------------------------------------------
Examples for modifying traceback printing:: Examples for modifying traceback printing:
.. code-block:: bash
pytest --showlocals # show local variables in tracebacks pytest --showlocals # show local variables in tracebacks
pytest -l # show local variables (shortcut) pytest -l # show local variables (shortcut)
@ -320,13 +330,17 @@ Dropping to PDB_ (Python Debugger) on failures
.. _PDB: http://docs.python.org/library/pdb.html .. _PDB: http://docs.python.org/library/pdb.html
Python comes with a builtin Python debugger called PDB_. ``pytest`` Python comes with a builtin Python debugger called PDB_. ``pytest``
allows one to drop into the PDB_ prompt via a command line option:: allows one to drop into the PDB_ prompt via a command line option:
.. code-block:: bash
pytest --pdb pytest --pdb
This will invoke the Python debugger on every failure (or KeyboardInterrupt). This will invoke the Python debugger on every failure (or KeyboardInterrupt).
Often you might only want to do this for the first failing test to understand Often you might only want to do this for the first failing test to understand
a certain failure situation:: a certain failure situation:
.. code-block:: bash
pytest -x --pdb # drop to PDB on first failure, then end test session pytest -x --pdb # drop to PDB on first failure, then end test session
pytest --pdb --maxfail=3 # drop to PDB for first three failures pytest --pdb --maxfail=3 # drop to PDB for first three failures
@ -349,7 +363,9 @@ Dropping to PDB_ (Python Debugger) at the start of a test
---------------------------------------------------------- ----------------------------------------------------------
``pytest`` allows one to drop into the PDB_ prompt immediately at the start of each test via a command line option:: ``pytest`` allows one to drop into the PDB_ prompt immediately at the start of each test via a command line option:
.. code-block:: bash
pytest --trace pytest --trace
@ -394,7 +410,9 @@ Profiling test execution duration
.. versionadded: 2.2 .. versionadded: 2.2
To get a list of the slowest 10 test durations:: To get a list of the slowest 10 test durations:
.. code-block:: bash
pytest --durations=10 pytest --durations=10
@ -404,7 +422,9 @@ Creating JUnitXML format files
---------------------------------------------------- ----------------------------------------------------
To create result files which can be read by Jenkins_ or other Continuous To create result files which can be read by Jenkins_ or other Continuous
integration servers, use this invocation:: integration servers, use this invocation:
.. code-block:: bash
pytest --junitxml=path pytest --junitxml=path
@ -627,7 +647,9 @@ Creating resultlog format files
See `the deprecation docs <https://docs.pytest.org/en/latest/deprecations.html#result-log-result-log>`__ See `the deprecation docs <https://docs.pytest.org/en/latest/deprecations.html#result-log-result-log>`__
for more information. for more information.
To create plain-text machine-readable result files you can issue:: To create plain-text machine-readable result files you can issue:
.. code-block:: bash
pytest --resultlog=path pytest --resultlog=path
@ -640,7 +662,9 @@ by the `PyPy-test`_ web page to show test results over several revisions.
Sending test report to online pastebin service Sending test report to online pastebin service
----------------------------------------------------- -----------------------------------------------------
**Creating a URL for each test failure**:: **Creating a URL for each test failure**:
.. code-block:: bash
pytest --pastebin=failed pytest --pastebin=failed
@ -648,7 +672,9 @@ 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 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. for example ``-x`` if you only want to send one particular failure.
**Creating a URL for a whole test session log**:: **Creating a URL for a whole test session log**:
.. code-block:: bash
pytest --pastebin=all pytest --pastebin=all
@ -661,7 +687,9 @@ To disable loading specific plugins at invocation time, use the ``-p`` option
together with the prefix ``no:``. together with the prefix ``no:``.
Example: to disable loading the plugin ``doctest``, which is responsible for Example: to disable loading the plugin ``doctest``, which is responsible for
executing doctest tests from text files, invoke pytest like this:: executing doctest tests from text files, invoke pytest like this:
.. code-block:: bash
pytest -p no:doctest pytest -p no:doctest
@ -693,7 +721,9 @@ You can specify additional plugins to ``pytest.main``::
pytest.main(["-qq"], plugins=[MyPlugin()]) pytest.main(["-qq"], plugins=[MyPlugin()])
Running it will show that ``MyPlugin`` was added and its Running it will show that ``MyPlugin`` was added and its
hook was invoked:: hook was invoked:
.. code-block:: pytest
$ python myinvoke.py $ python myinvoke.py
.FEsxX. [100%]*** test run reporting finishing .FEsxX. [100%]*** test run reporting finishing