Skip to content

Commit 52363fe

Browse files
nicoddemusnicoddemus
authored
Merge pull request #7756 from nicoddemus/backport-7747
[6.0] Add full command-line flags to the reference docs
2 parents 2d680da + c923dbc commit 52363fe

File tree

2 files changed

+295
-0
lines changed

2 files changed

+295
-0
lines changed

‎doc/en/reference.rst

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1659,3 +1659,296 @@ passed multiple times. The expected format is ``name=value``. For example::
16591659
16601660
[pytest]
16611661
xfail_strict = True
1662+
1663+
1664+
.. _`command-line-flags`:
1665+
1666+
Command-line Flags
1667+
------------------
1668+
1669+
All the command-line flags can be obtained by running ``pytest --help``::
1670+
1671+
$ pytest --help
1672+
usage: pytest [options] [file_or_dir] [file_or_dir] [...]
1673+
1674+
positional arguments:
1675+
file_or_dir
1676+
1677+
general:
1678+
-k EXPRESSION only run tests which match the given substring
1679+
expression. An expression is a python evaluatable
1680+
expression where all names are substring-matched
1681+
against test names and their parent classes.
1682+
Example: -k 'test_method or test_other' matches all
1683+
test functions and classes whose name contains
1684+
'test_method' or 'test_other', while -k 'not
1685+
test_method' matches those that don't contain
1686+
'test_method' in their names. -k 'not test_method
1687+
and not test_other' will eliminate the matches.
1688+
Additionally keywords are matched to classes and
1689+
functions containing extra names in their
1690+
'extra_keyword_matches' set, as well as functions
1691+
which have names assigned directly to them. The
1692+
matching is case-insensitive.
1693+
-m MARKEXPR only run tests matching given mark expression.
1694+
For example: -m 'mark1 and not mark2'.
1695+
--markers show markers (builtin, plugin and per-project ones).
1696+
-x, --exitfirst exit instantly on first error or failed test.
1697+
--fixtures, --funcargs
1698+
show available fixtures, sorted by plugin appearance
1699+
(fixtures with leading '_' are only shown with '-v')
1700+
--fixtures-per-test show fixtures per test
1701+
--pdb start the interactive Python debugger on errors or
1702+
KeyboardInterrupt.
1703+
--pdbcls=modulename:classname
1704+
start a custom interactive Python debugger on
1705+
errors. For example:
1706+
--pdbcls=IPython.terminal.debugger:TerminalPdb
1707+
--trace Immediately break when running each test.
1708+
--capture=method per-test capturing method: one of fd|sys|no|tee-sys.
1709+
-s shortcut for --capture=no.
1710+
--runxfail report the results of xfail tests as if they were
1711+
not marked
1712+
--lf, --last-failed rerun only the tests that failed at the last run (or
1713+
all if none failed)
1714+
--ff, --failed-first run all tests, but run the last failures first.
1715+
This may re-order tests and thus lead to repeated
1716+
fixture setup/teardown.
1717+
--nf, --new-first run tests from new files first, then the rest of the
1718+
tests sorted by file mtime
1719+
--cache-show=[CACHESHOW]
1720+
show cache contents, don't perform collection or
1721+
tests. Optional argument: glob (default: '*').
1722+
--cache-clear remove all cache contents at start of test run.
1723+
--lfnf={all,none}, --last-failed-no-failures={all,none}
1724+
which tests to run with no previously (known)
1725+
failures.
1726+
--sw, --stepwise exit on test failure and continue from last failing
1727+
test next time
1728+
--stepwise-skip ignore the first failing test but stop on the next
1729+
failing test
1730+
1731+
reporting:
1732+
--durations=N show N slowest setup/test durations (N=0 for all).
1733+
--durations-min=N Minimal duration in seconds for inclusion in slowest
1734+
list. Default 0.005
1735+
-v, --verbose increase verbosity.
1736+
--no-header disable header
1737+
--no-summary disable summary
1738+
-q, --quiet decrease verbosity.
1739+
--verbosity=VERBOSE set verbosity. Default is 0.
1740+
-r chars show extra test summary info as specified by chars:
1741+
(f)ailed, (E)rror, (s)kipped, (x)failed, (X)passed,
1742+
(p)assed, (P)assed with output, (a)ll except passed
1743+
(p/P), or (A)ll. (w)arnings are enabled by default
1744+
(see --disable-warnings), 'N' can be used to reset
1745+
the list. (default: 'fE').
1746+
--disable-warnings, --disable-pytest-warnings
1747+
disable warnings summary
1748+
-l, --showlocals show locals in tracebacks (disabled by default).
1749+
--tb=style traceback print mode
1750+
(auto/long/short/line/native/no).
1751+
--show-capture={no,stdout,stderr,log,all}
1752+
Controls how captured stdout/stderr/log is shown on
1753+
failed tests. Default is 'all'.
1754+
--full-trace don't cut any tracebacks (default is to cut).
1755+
--color=color color terminal output (yes/no/auto).
1756+
--code-highlight={yes,no}
1757+
Whether code should be highlighted (only if --color
1758+
is also enabled)
1759+
--pastebin=mode send failed|all info to bpaste.net pastebin service.
1760+
--junit-xml=path create junit-xml style report file at given path.
1761+
--junit-prefix=str prepend prefix to classnames in junit-xml output
1762+
1763+
pytest-warnings:
1764+
-W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS
1765+
set which warnings to report, see -W option of
1766+
python itself.
1767+
--maxfail=num exit after first num failures or errors.
1768+
--strict-config any warnings encountered while parsing the `pytest`
1769+
section of the configuration file raise errors.
1770+
--strict-markers, --strict
1771+
markers not registered in the `markers` section of
1772+
the configuration file raise errors.
1773+
-c file load configuration from `file` instead of trying to
1774+
locate one of the implicit configuration files.
1775+
--continue-on-collection-errors
1776+
Force test execution even if collection errors
1777+
occur.
1778+
--rootdir=ROOTDIR Define root directory for tests. Can be relative
1779+
path: 'root_dir', './root_dir',
1780+
'root_dir/another_dir/'; absolute path:
1781+
'/home/user/root_dir'; path with variables:
1782+
'$HOME/root_dir'.
1783+
1784+
collection:
1785+
--collect-only, --co only collect tests, don't execute them.
1786+
--pyargs try to interpret all arguments as python packages.
1787+
--ignore=path ignore path during collection (multi-allowed).
1788+
--ignore-glob=path ignore path pattern during collection (multi-
1789+
allowed).
1790+
--deselect=nodeid_prefix
1791+
deselect item (via node id prefix) during collection
1792+
(multi-allowed).
1793+
--confcutdir=dir only load conftest.py's relative to specified dir.
1794+
--noconftest Don't load any conftest.py files.
1795+
--keep-duplicates Keep duplicate tests.
1796+
--collect-in-virtualenv
1797+
Don't ignore tests in a local virtualenv directory
1798+
--import-mode={prepend,append,importlib}
1799+
prepend/append to sys.path when importing test
1800+
modules and conftest files, default is to prepend.
1801+
--doctest-modules run doctests in all .py modules
1802+
--doctest-report={none,cdiff,ndiff,udiff,only_first_failure}
1803+
choose another output format for diffs on doctest
1804+
failure
1805+
--doctest-glob=pat doctests file matching pattern, default: test*.txt
1806+
--doctest-ignore-import-errors
1807+
ignore doctest ImportErrors
1808+
--doctest-continue-on-failure
1809+
for a given doctest, continue to run after the first
1810+
failure
1811+
1812+
test session debugging and configuration:
1813+
--basetemp=dir base temporary directory for this test run.(warning:
1814+
this directory is removed if it exists)
1815+
-V, --version display pytest version and information about
1816+
plugins.When given twice, also display information
1817+
about plugins.
1818+
-h, --help show help message and configuration info
1819+
-p name early-load given plugin module name or entry point
1820+
(multi-allowed).
1821+
To avoid loading of plugins, use the `no:` prefix,
1822+
e.g. `no:doctest`.
1823+
--trace-config trace considerations of conftest.py files.
1824+
--debug store internal tracing debug information in
1825+
'pytestdebug.log'.
1826+
-o OVERRIDE_INI, --override-ini=OVERRIDE_INI
1827+
override ini option with "option=value" style, e.g.
1828+
`-o xfail_strict=True -o cache_dir=cache`.
1829+
--assert=MODE Control assertion debugging tools.
1830+
'plain' performs no assertion debugging.
1831+
'rewrite' (the default) rewrites assert statements
1832+
in test modules on import to provide assert
1833+
expression information.
1834+
--setup-only only setup fixtures, do not execute tests.
1835+
--setup-show show setup of fixtures while executing tests.
1836+
--setup-plan show what fixtures and tests would be executed but
1837+
don't execute anything.
1838+
1839+
logging:
1840+
--log-level=LEVEL level of messages to catch/display.
1841+
Not set by default, so it depends on the root/parent
1842+
log handler's effective level, where it is "WARNING"
1843+
by default.
1844+
--log-format=LOG_FORMAT
1845+
log format as used by the logging module.
1846+
--log-date-format=LOG_DATE_FORMAT
1847+
log date format as used by the logging module.
1848+
--log-cli-level=LOG_CLI_LEVEL
1849+
cli logging level.
1850+
--log-cli-format=LOG_CLI_FORMAT
1851+
log format as used by the logging module.
1852+
--log-cli-date-format=LOG_CLI_DATE_FORMAT
1853+
log date format as used by the logging module.
1854+
--log-file=LOG_FILE path to a file when logging will be written to.
1855+
--log-file-level=LOG_FILE_LEVEL
1856+
log file logging level.
1857+
--log-file-format=LOG_FILE_FORMAT
1858+
log format as used by the logging module.
1859+
--log-file-date-format=LOG_FILE_DATE_FORMAT
1860+
log date format as used by the logging module.
1861+
--log-auto-indent=LOG_AUTO_INDENT
1862+
Auto-indent multiline messages passed to the logging
1863+
module. Accepts true|on, false|off or an integer.
1864+
1865+
[pytest] ini-options in the first pytest.ini|tox.ini|setup.cfg file found:
1866+
1867+
markers (linelist): markers for test functions
1868+
empty_parameter_set_mark (string):
1869+
default marker for empty parametersets
1870+
norecursedirs (args): directory patterns to avoid for recursion
1871+
testpaths (args): directories to search for tests when no files or
1872+
directories are given in the command line.
1873+
filterwarnings (linelist):
1874+
Each line specifies a pattern for
1875+
warnings.filterwarnings. Processed after
1876+
-W/--pythonwarnings.
1877+
usefixtures (args): list of default fixtures to be used with this
1878+
project
1879+
python_files (args): glob-style file patterns for Python test module
1880+
discovery
1881+
python_classes (args):
1882+
prefixes or glob names for Python test class
1883+
discovery
1884+
python_functions (args):
1885+
prefixes or glob names for Python test function and
1886+
method discovery
1887+
disable_test_id_escaping_and_forfeit_all_rights_to_community_support (bool):
1888+
disable string escape non-ascii characters, might
1889+
cause unwanted side effects(use at your own risk)
1890+
console_output_style (string):
1891+
console output: "classic", or with additional
1892+
progress information ("progress" (percentage) |
1893+
"count").
1894+
xfail_strict (bool): default for the strict parameter of xfail markers
1895+
when not given explicitly (default: False)
1896+
enable_assertion_pass_hook (bool):
1897+
Enables the pytest_assertion_pass hook.Make sure to
1898+
delete any previously generated pyc cache files.
1899+
junit_suite_name (string):
1900+
Test suite name for JUnit report
1901+
junit_logging (string):
1902+
Write captured log messages to JUnit report: one of
1903+
no|log|system-out|system-err|out-err|all
1904+
junit_log_passing_tests (bool):
1905+
Capture log information for passing tests to JUnit
1906+
report:
1907+
junit_duration_report (string):
1908+
Duration time to report: one of total|call
1909+
junit_family (string):
1910+
Emit XML for schema: one of legacy|xunit1|xunit2
1911+
doctest_optionflags (args):
1912+
option flags for doctests
1913+
doctest_encoding (string):
1914+
encoding used for doctest files
1915+
cache_dir (string): cache directory path.
1916+
log_level (string): default value for --log-level
1917+
log_format (string): default value for --log-format
1918+
log_date_format (string):
1919+
default value for --log-date-format
1920+
log_cli (bool): enable log display during test run (also known as
1921+
"live logging").
1922+
log_cli_level (string):
1923+
default value for --log-cli-level
1924+
log_cli_format (string):
1925+
default value for --log-cli-format
1926+
log_cli_date_format (string):
1927+
default value for --log-cli-date-format
1928+
log_file (string): default value for --log-file
1929+
log_file_level (string):
1930+
default value for --log-file-level
1931+
log_file_format (string):
1932+
default value for --log-file-format
1933+
log_file_date_format (string):
1934+
default value for --log-file-date-format
1935+
log_auto_indent (string):
1936+
default value for --log-auto-indent
1937+
faulthandler_timeout (string):
1938+
Dump the traceback of all threads if a test takes
1939+
more than TIMEOUT seconds to finish.
1940+
addopts (args): extra command line options
1941+
minversion (string): minimally required pytest version
1942+
required_plugins (args):
1943+
plugins that must be present for pytest to run
1944+
1945+
environment variables:
1946+
PYTEST_ADDOPTS extra command line options
1947+
PYTEST_PLUGINS comma-separated plugins to load during startup
1948+
PYTEST_DISABLE_PLUGIN_AUTOLOAD set to disable plugin auto-loading
1949+
PYTEST_DEBUG set to enable debug tracing of pytest's internals
1950+
1951+
1952+
to see available markers type: pytest --markers
1953+
to see available fixtures type: pytest --fixtures
1954+
(shown according to specified file_or_dir or current dir if not specified; fixtures with leading '_' are only shown with the '-v' option

‎doc/en/usage.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ Getting help on version, option names, environment variables
5757
pytest -h | --help # show help on command line and config file options
5858
5959
60+
The full command-line flags can be found in the :ref:`reference <command-line-flags>`.
61+
6062
.. _maxfail:
6163

6264
Stopping after the first (or N) failures

0 commit comments

Comments
 (0)