From 799bcccd1b73af5dde411a8fd564f699b64ddd70 Mon Sep 17 00:00:00 2001 From: Grygorii Iermolenko Date: Wed, 13 Feb 2019 17:08:49 +0200 Subject: [PATCH 1/3] Fix sphinx code-block types (syntax highlighting) in two docs --- doc/en/doctest.rst | 44 +++++++++++++++--------- doc/en/example/pythoncollection.rst | 52 ++++++++++++++++++++--------- 2 files changed, 65 insertions(+), 31 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index 5aadc1112..e1e6b1b50 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -4,9 +4,11 @@ Doctest integration for modules and test files By default all files matching the ``test*.txt`` pattern will be run through the python standard ``doctest`` module. You -can change the pattern by issuing:: +can change the pattern by issuing: - pytest --doctest-glob='*.rst' +.. code-block:: bash + + $ pytest --doctest-glob='*.rst' on the command line. Since version ``2.9``, ``--doctest-glob`` can be given multiple times in the command-line. @@ -26,9 +28,11 @@ can be given multiple times in the command-line. You can also trigger running of doctests from docstrings in all python modules (including regular -python test modules):: +python test modules): - pytest --doctest-modules +.. code-block:: bash + + $ pytest --doctest-modules You can make these changes permanent in your project by putting them into a pytest.ini file like this: @@ -39,7 +43,9 @@ putting them into a pytest.ini file like this: [pytest] 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 @@ -73,7 +79,9 @@ then you can just invoke ``pytest`` without command line options: ========================= 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 >>> tmp = getfixture('tmpdir') @@ -112,16 +120,20 @@ the ``doctest_optionflags`` ini option: Alternatively, it can be enabled by an inline comment in the doc test -itself:: +itself: + +.. code-block:: rst # content of example.rst >>> get_unicode_greeting() # doctest: +ALLOW_UNICODE 'Hello' 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: - pytest --doctest-modules --doctest-continue-on-failure +.. code-block:: bash + + $ pytest --doctest-modules --doctest-continue-on-failure .. _`doctest_namespace`: @@ -167,10 +179,12 @@ Output format You can change the diff output format on failure for your doctests by using one of standard doctest modules format in options (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`): - pytest --doctest-modules --doctest-report none - pytest --doctest-modules --doctest-report udiff - pytest --doctest-modules --doctest-report cdiff - pytest --doctest-modules --doctest-report ndiff - pytest --doctest-modules --doctest-report only_first_failure +.. code-block:: bash + + $ pytest --doctest-modules --doctest-report none + $ pytest --doctest-modules --doctest-report udiff + $ pytest --doctest-modules --doctest-report cdiff + $ pytest --doctest-modules --doctest-report ndiff + $ pytest --doctest-modules --doctest-report only_first_failure diff --git a/doc/en/example/pythoncollection.rst b/doc/en/example/pythoncollection.rst index 8dcaa97d7..7ec86dc7e 100644 --- a/doc/en/example/pythoncollection.rst +++ b/doc/en/example/pythoncollection.rst @@ -6,7 +6,9 @@ Ignore paths during test collection You can easily ignore certain test directories and modules during collection by passing the ``--ignore=path`` option on the cli. ``pytest`` allows multiple -``--ignore`` options. Example:: +``--ignore`` options. Example: + +.. code-block:: text tests/ |-- example @@ -54,9 +56,11 @@ Keeping duplicate paths specified from command line ---------------------------------------------------- Default behavior of ``pytest`` is to ignore duplicate paths specified from the command line. -Example:: +Example: - pytest path_a path_a +.. code-block:: pytest + + $ pytest path_a path_a ... collected 1 item @@ -65,9 +69,11 @@ Example:: Just collect tests once. To collect duplicate tests, use the ``--keep-duplicates`` option on the cli. -Example:: +Example: - pytest --keep-duplicates path_a path_a +.. code-block:: pytest + + $ pytest --keep-duplicates path_a path_a ... collected 2 items @@ -75,9 +81,11 @@ Example:: 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. -Example:: +Example: - pytest test_a.py test_a.py +.. code-block:: pytest + + $ pytest test_a.py test_a.py ... collected 2 items @@ -87,7 +95,9 @@ Example:: 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 [pytest] @@ -103,7 +113,9 @@ Changing naming conventions You can configure different naming conventions by setting the :confval:`python_files`, :confval:`python_classes` and :confval:`python_functions` configuration options. -Here is an example:: +Here is an example: + +.. code-block:: ini # content of pytest.ini # Example 1: have pytest look for "check" instead of "test" @@ -142,7 +154,9 @@ The test collection would look like this: ======================= 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" # content of pytest.ini, tox.ini, or setup.cfg file (replace "pytest" @@ -162,13 +176,17 @@ Interpreting cmdline arguments as Python packages You can use the ``--pyargs`` option to make ``pytest`` try interpreting arguments as python package names, deriving 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: - pytest --pyargs unittest2.test.test_skipping -q +.. code-block:: bash + + $ pytest --pyargs unittest2.test.test_skipping -q which would run the respective test module. Like with 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 [pytest] @@ -185,7 +203,7 @@ You can always peek at the collection tree without running tests like this: .. code-block:: pytest - . $ pytest --collect-only pythoncollection.py + $ pytest --collect-only pythoncollection.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y cachedir: $PYTHON_PREFIX/.pytest_cache @@ -206,7 +224,9 @@ Customizing test collection .. 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 [pytest] @@ -243,7 +263,7 @@ leave out the ``setup.py`` file: .. code-block:: pytest - #$ pytest --collect-only + $ pytest --collect-only ====== test session starts ====== platform linux2 -- Python 2.7.10, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini From 5cf58a9ae9309bfa4b8be701873cbf981ed113d9 Mon Sep 17 00:00:00 2001 From: Grygorii Iermolenko Date: Fri, 15 Feb 2019 14:09:37 +0200 Subject: [PATCH 2/3] Revert '$' changes to not trigger regendoc --- doc/en/doctest.rst | 16 ++++++++-------- doc/en/example/pythoncollection.rst | 12 ++++++------ 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst index e1e6b1b50..549ebb00f 100644 --- a/doc/en/doctest.rst +++ b/doc/en/doctest.rst @@ -8,7 +8,7 @@ can change the pattern by issuing: .. code-block:: bash - $ pytest --doctest-glob='*.rst' + pytest --doctest-glob='*.rst' on the command line. Since version ``2.9``, ``--doctest-glob`` can be given multiple times in the command-line. @@ -32,7 +32,7 @@ python test modules): .. code-block:: bash - $ pytest --doctest-modules + pytest --doctest-modules You can make these changes permanent in your project by putting them into a pytest.ini file like this: @@ -133,7 +133,7 @@ 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 .. _`doctest_namespace`: @@ -183,8 +183,8 @@ by using one of standard doctest modules format in options .. code-block:: bash - $ pytest --doctest-modules --doctest-report none - $ pytest --doctest-modules --doctest-report udiff - $ pytest --doctest-modules --doctest-report cdiff - $ pytest --doctest-modules --doctest-report ndiff - $ pytest --doctest-modules --doctest-report only_first_failure + pytest --doctest-modules --doctest-report none + pytest --doctest-modules --doctest-report udiff + pytest --doctest-modules --doctest-report cdiff + pytest --doctest-modules --doctest-report ndiff + pytest --doctest-modules --doctest-report only_first_failure diff --git a/doc/en/example/pythoncollection.rst b/doc/en/example/pythoncollection.rst index 7ec86dc7e..52dc2545d 100644 --- a/doc/en/example/pythoncollection.rst +++ b/doc/en/example/pythoncollection.rst @@ -60,7 +60,7 @@ Example: .. code-block:: pytest - $ pytest path_a path_a + pytest path_a path_a ... collected 1 item @@ -73,7 +73,7 @@ Example: .. code-block:: pytest - $ pytest --keep-duplicates path_a path_a + pytest --keep-duplicates path_a path_a ... collected 2 items @@ -85,7 +85,7 @@ Example: .. code-block:: pytest - $ pytest test_a.py test_a.py + pytest test_a.py test_a.py ... collected 2 items @@ -180,7 +180,7 @@ 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 other options, through an ini-file and the :confval:`addopts` option you @@ -203,7 +203,7 @@ You can always peek at the collection tree without running tests like this: .. code-block:: pytest - $ pytest --collect-only pythoncollection.py + . $ pytest --collect-only pythoncollection.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y cachedir: $PYTHON_PREFIX/.pytest_cache @@ -263,7 +263,7 @@ leave out the ``setup.py`` file: .. code-block:: pytest - $ pytest --collect-only + #$ pytest --collect-only ====== test session starts ====== platform linux2 -- Python 2.7.10, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini From 6e1ee0802fd500500ec984240dc7fe694cbd8338 Mon Sep 17 00:00:00 2001 From: Grygorii Iermolenko Date: Fri, 15 Feb 2019 15:10:37 +0200 Subject: [PATCH 3/3] Fix sphinx code-block types for remaining rst docs --- doc/en/bash-completion.rst | 22 ++++++++---- doc/en/cache.rst | 8 +++-- doc/en/capture.rst | 4 ++- doc/en/customize.rst | 28 +++++++++++---- doc/en/example/markers.rst | 12 +++++-- doc/en/example/simple.rst | 8 +++-- doc/en/fixture.rst | 12 +++++-- doc/en/getting-started.rst | 12 +++++-- doc/en/license.rst | 2 +- doc/en/logging.rst | 21 +++++++---- doc/en/nose.rst | 4 ++- doc/en/parametrize.rst | 4 ++- doc/en/skipping.rst | 10 ++++-- doc/en/tmpdir.rst | 4 ++- doc/en/usage.rst | 72 +++++++++++++++++++++++++++----------- 15 files changed, 161 insertions(+), 62 deletions(-) diff --git a/doc/en/bash-completion.rst b/doc/en/bash-completion.rst index 08d978209..eaa078814 100644 --- a/doc/en/bash-completion.rst +++ b/doc/en/bash-completion.rst @@ -8,18 +8,26 @@ When using bash as your shell, ``pytest`` can use argcomplete (https://argcomplete.readthedocs.io/) for auto-completion. For this ``argcomplete`` needs to be installed **and** enabled. -Install argcomplete using:: +Install argcomplete using: - sudo pip install 'argcomplete>=0.5.7' +.. code-block:: bash -For global activation of all argcomplete enabled python applications run:: + sudo pip install 'argcomplete>=0.5.7' + +For global activation of all argcomplete enabled python applications run: + +.. code-block:: bash sudo activate-global-python-argcomplete -For permanent (but not global) ``pytest`` activation, use:: +For permanent (but not global) ``pytest`` activation, use: - register-python-argcomplete pytest >> ~/.bashrc +.. code-block:: bash -For one-time activation of argcomplete for ``pytest`` only, use:: + register-python-argcomplete pytest >> ~/.bashrc - eval "$(register-python-argcomplete pytest)" +For one-time activation of argcomplete for ``pytest`` only, use: + +.. code-block:: bash + + eval "$(register-python-argcomplete pytest)" diff --git a/doc/en/cache.rst b/doc/en/cache.rst index 0cb42e6e9..89a1e2634 100644 --- a/doc/en/cache.rst +++ b/doc/en/cache.rst @@ -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 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 none # run no tests and exit @@ -283,7 +285,9 @@ Clearing Cache content ------------------------------- 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 diff --git a/doc/en/capture.rst b/doc/en/capture.rst index 78390034a..f62ec60ca 100644 --- a/doc/en/capture.rst +++ b/doc/en/capture.rst @@ -35,7 +35,9 @@ There are two ways in which ``pytest`` can perform 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 --capture=sys # replace sys.stdout/stderr with in-mem files diff --git a/doc/en/customize.rst b/doc/en/customize.rst index 47b92ab9e..310b5c7b3 100644 --- a/doc/en/customize.rst +++ b/doc/en/customize.rst @@ -5,7 +5,9 @@ Command line options and configuration file settings ----------------------------------------------------------------- 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 @@ -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 per-testrun information. -Example:: +Example: + +.. code-block:: bash pytest path/to/testdir path/other/ 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 path/pytest.ini @@ -133,19 +139,27 @@ progress output, you can write it into a configuration file: addopts = -ra -q 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" -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_ADDOPTS -So if the user executes in the command-line:: +So if the user executes in the command-line: + +.. code-block:: bash pytest -m slow -The actual command line executed is:: +The actual command line executed is: + +.. code-block:: bash pytest -ra -q -v -m slow diff --git a/doc/en/example/markers.rst b/doc/en/example/markers.rst index 864c1e808..5ec57caed 100644 --- a/doc/en/example/markers.rst +++ b/doc/en/example/markers.rst @@ -204,14 +204,18 @@ Registering 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 [pytest] markers = 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.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 ========================= -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.mark.env(name): mark test to run only on named environment diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index 5904ea5a1..1c6cf36c9 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -731,7 +731,9 @@ and run them: test_module.py:6: AssertionError ========================= 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 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 -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/ diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index 4c8e24b9c..390f8abcc 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -114,7 +114,9 @@ with a list of available function arguments. .. note:: - You can always issue :: + You can always issue: + + .. code-block:: bash 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 tests. -Let's execute it:: +Let's execute it: + +.. code-block:: pytest $ pytest -s -q --tb=no 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 ``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 FFfinalizing (smtp.gmail.com) diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index a9f7d1d11..222ae65ba 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -17,11 +17,15 @@ Installation and Getting Started 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 -2. Check that you installed the correct version:: +2. Check that you installed the correct version: + +.. code-block:: bash $ pytest --version 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 `. -Find out what kind of builtin :ref:`pytest fixtures ` exist with the command:: +Find out what kind of builtin :ref:`pytest fixtures ` exist with the command: + +.. code-block:: bash pytest --fixtures # shows builtin and custom fixtures diff --git a/doc/en/license.rst b/doc/en/license.rst index b8c0dce1b..5ee55cf96 100644 --- a/doc/en/license.rst +++ b/doc/en/license.rst @@ -5,7 +5,7 @@ License Distributed under the terms of the `MIT`_ license, pytest is free and open source software. -:: +.. code-block:: text The MIT License (MIT) diff --git a/doc/en/logging.rst b/doc/en/logging.rst index 00829c15e..59d89901c 100644 --- a/doc/en/logging.rst +++ b/doc/en/logging.rst @@ -9,11 +9,15 @@ Logging 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. -Running without options:: +Running without options: + +.. code-block:: bash pytest -Shows failed tests like so:: +Shows failed tests like so: + +.. code-block:: pytest ----------------------- Captured stdlog call ---------------------- 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. 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" \ --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 ---------------------- 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 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 @@ -133,7 +143,6 @@ the records for the ``setup`` and ``call`` stages during teardown like so: .. code-block:: python - @pytest.fixture def window(caplog): window = create_window() diff --git a/doc/en/nose.rst b/doc/en/nose.rst index 1f7b7b638..701ea44ec 100644 --- a/doc/en/nose.rst +++ b/doc/en/nose.rst @@ -12,7 +12,9 @@ Running tests written for nose Usage ------------- -After :ref:`installation` type:: +After :ref:`installation` type: + +.. code-block:: bash python setup.py develop # make sure tests can import our package pytest # instead of 'nosetests' diff --git a/doc/en/parametrize.rst b/doc/en/parametrize.rst index d1d23c67f..9a237dcd7 100644 --- a/doc/en/parametrize.rst +++ b/doc/en/parametrize.rst @@ -172,7 +172,9 @@ command line option and the parametrization of our test function:: metafunc.parametrize("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 .. [100%] diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst index dd0b57110..96af8ee35 100644 --- a/doc/en/skipping.rst +++ b/doc/en/skipping.rst @@ -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 information about skipped/xfailed tests is not shown by default to avoid 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 @@ -82,7 +84,7 @@ It is also possible to skip the whole module using If you wish to skip something conditionally then you can use ``skipif`` instead. Here is an example of marking a test function to be skipped -when run on an interpreter earlier than Python3.6 :: +when run on an interpreter earlier than Python3.6:: import sys @pytest.mark.skipif(sys.version_info < (3,6), @@ -309,7 +311,9 @@ investigated later. Ignoring xfail ~~~~~~~~~~~~~~ -By specifying on the commandline:: +By specifying on the commandline: + +.. code-block:: bash pytest --runxfail diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst index 3d73d6147..df490d7fb 100644 --- a/doc/en/tmpdir.rst +++ b/doc/en/tmpdir.rst @@ -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 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 diff --git a/doc/en/usage.rst b/doc/en/usage.rst index b894e0fd4..2efb63ae2 100644 --- a/doc/en/usage.rst +++ b/doc/en/usage.rst @@ -12,7 +12,9 @@ Calling pytest through ``python -m pytest`` .. 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 [...] @@ -34,7 +36,7 @@ Running ``pytest`` can result in six different exit codes: Getting help on version, option names, environment variables -------------------------------------------------------------- -:: +.. code-block:: bash pytest --version # shows where pytest was imported from 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 --------------------------------------------------- -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 --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** -:: +.. code-block:: bash pytest test_mod.py **Run tests in a directory** -:: +.. code-block:: bash pytest testing/ **Run tests by keyword expressions** -:: +.. code-block:: bash 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 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 -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 **Run tests by marker expressions** -:: +.. code-block:: bash pytest -m slow @@ -108,7 +116,7 @@ For more information see :ref:`marks `. **Run tests from packages** -:: +.. code-block:: bash 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 ---------------------------------------------- -Examples for modifying traceback printing:: +Examples for modifying traceback printing: + +.. code-block:: bash pytest --showlocals # show local variables in tracebacks 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 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 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 -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 --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 @@ -394,7 +410,9 @@ Profiling test execution duration .. 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 @@ -404,7 +422,9 @@ Creating JUnitXML format files ---------------------------------------------------- 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 @@ -627,7 +647,9 @@ Creating resultlog format files See `the deprecation docs `__ 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 @@ -640,7 +662,9 @@ 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**:: +**Creating a URL for each test failure**: + +.. code-block:: bash 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 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 @@ -661,7 +687,9 @@ To disable loading specific plugins at invocation time, use the ``-p`` option together with the prefix ``no:``. 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 @@ -693,7 +721,9 @@ You can specify additional plugins to ``pytest.main``:: pytest.main(["-qq"], plugins=[MyPlugin()]) Running it will show that ``MyPlugin`` was added and its -hook was invoked:: +hook was invoked: + +.. code-block:: pytest $ python myinvoke.py .FEsxX. [100%]*** test run reporting finishing