jiuyuan
/
test_ok1
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fix sphinx code-block types for remaining rst docs

This commit is contained in:
Grygorii Iermolenko 2019-02-15 15:10:37 +02:00
parent 5cf58a9ae9
commit 6e1ee0802f
15 changed files with 161 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/en/bash-completion.rst
View File

@ -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:
.. code-block:: bash
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
For permanent (but not global) ``pytest`` activation, use::
For permanent (but not global) ``pytest`` activation, use:
.. code-block:: bash
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)"

8
doc/en/cache.rst
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
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

4
doc/en/capture.rst
View File

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

28
doc/en/customize.rst
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
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.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
The actual command line executed is::
The actual command line executed is:
.. code-block:: bash
pytest -ra -q -v -m slow

12
doc/en/example/markers.rst
View File

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

8
doc/en/example/simple.rst
View File

@ -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/

12
doc/en/fixture.rst
View File

@ -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 <smtplib.SMTP object at 0xdeadbeef> (smtp.gmail.com)

12
doc/en/getting-started.rst
View File

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

2
doc/en/license.rst
View File

@ -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)

21
doc/en/logging.rst
View File

@ -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()

4
doc/en/nose.rst
View File

@ -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'

4
doc/en/parametrize.rst
View File

@ -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%]

10
doc/en/skipping.rst
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
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

4
doc/en/tmpdir.rst
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
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

72
doc/en/usage.rst
View File

@ -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 <mark>`.
**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 <https://docs.pytest.org/en/latest/deprecations.html#result-log-result-log>`__
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