From c6ba995e32676f37d396aad0b4f70ff92325b803 Mon Sep 17 00:00:00 2001 From: Olena Date: Thu, 16 Apr 2026 00:41:01 +0300 Subject: [PATCH 1/5] Edit double-dash escaping for --cov= option in config.rst --- docs/config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config.rst b/docs/config.rst index ef8754e2..1dbf1021 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -6,7 +6,7 @@ This plugin provides a clean minimal set of command line options that are added further control of coverage use a `coverage config file`_. CLI options: - --cov [SOURCE] Path or package name to measure during execution (multi-allowed). Use --cov= to not do any source filtering and record everything. + --cov [SOURCE] Path or package name to measure during execution (multi-allowed). Use ``--cov=`` to not do any source filtering and record everything. --cov-reset Reset cov sources accumulated in options so far. --cov-report TYPE Type of report to generate: term, term-missing, annotate, html, xml, json, markdown, markdown-append, lcov (multi-allowed). term, term-missing may be followed by ":skip-covered". annotate, html, xml, json, markdown, markdown-append and lcov may be followed by ":DEST" where DEST specifies the output location. Use --cov-report= to not generate any output. From ea6171ec0e585763c735cc4bf124359d14aa2428 Mon Sep 17 00:00:00 2001 From: Olena <107187316+OlenaYefymenko@users.noreply.github.com> Date: Mon, 20 Apr 2026 00:19:48 +0300 Subject: [PATCH 2/5] Apply suggestion from @webknjaz MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) --- docs/config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config.rst b/docs/config.rst index 1dbf1021..e87be1c2 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -5,7 +5,7 @@ Configuration This plugin provides a clean minimal set of command line options that are added to pytest. For further control of coverage use a `coverage config file`_. -CLI options: +CLI options:: --cov [SOURCE] Path or package name to measure during execution (multi-allowed). Use ``--cov=`` to not do any source filtering and record everything. --cov-reset Reset cov sources accumulated in options so far. --cov-report TYPE Type of report to generate: term, term-missing, annotate, html, xml, json, markdown, markdown-append, lcov (multi-allowed). term, term-missing may be followed by ":skip-covered". From c4a5d28445362defb90e90084172bc2ca8620778 Mon Sep 17 00:00:00 2001 From: Olena Date: Fri, 24 Apr 2026 22:17:43 +0300 Subject: [PATCH 3/5] Use option directives for CLI options and fix hyperlink --- docs/config.rst | 63 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index e87be1c2..1c883400 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -5,21 +5,52 @@ Configuration This plugin provides a clean minimal set of command line options that are added to pytest. For further control of coverage use a `coverage config file`_. -CLI options:: - --cov [SOURCE] Path or package name to measure during execution (multi-allowed). Use ``--cov=`` to not do any source filtering and record everything. - --cov-reset Reset cov sources accumulated in options so far. - --cov-report TYPE Type of report to generate: term, term-missing, annotate, html, xml, json, markdown, markdown-append, lcov (multi-allowed). term, term-missing may be followed by ":skip-covered". - annotate, html, xml, json, markdown, markdown-append and lcov may be followed by ":DEST" where DEST specifies the output location. Use --cov-report= to not generate any output. - --cov-config PATH Config file for coverage. Default: .coveragerc - --no-cov-on-fail Do not report coverage if test run fails. Default: False - --no-cov Disable coverage report completely (useful for debuggers). Default: False - --cov-fail-under MIN Fail if the total coverage is less than MIN. - --cov-append Do not delete coverage but append to current. Default: False - --cov-branch Enable branch coverage. Can also be specified in the `coverage config file`_ ``[run]`` section. - --cov-precision COV_PRECISION - Override the reporting precision. Can also be specified in the `coverage config file`_ ``[report]`` section. - --cov-context CONTEXT - Dynamic contexts to use. "test" for now. +CLI options: + +.. option:: --cov [SOURCE] + + Path or package name to measure during execution (multi-allowed). Use ``--cov=`` to not do any source filtering and record everything. + +.. option:: --cov-reset + + Reset cov sources accumulated in options so far. + +.. option:: --cov-report TYPE + + Type of report to generate: term, term-missing, annotate, html, xml, json, markdown, markdown-append, lcov (multi-allowed). term, term-missing may be followed by ":skip-covered". + annotate, html, xml, json, markdown, markdown-append and lcov may be followed by ":DEST" where DEST specifies the output location. Use ``--cov-report=`` to not generate any output. + +.. option:: --cov-config PATH + + Config file for coverage. Default: .coveragerc + +.. option:: --no-cov-on-fail + + Do not report coverage if test run fails. Default: False + +.. option:: --no-cov + + Disable coverage report completely (useful for debuggers). Default: False + +.. option:: --cov-fail-under MIN + + Fail if the total coverage is less than MIN. + +.. option:: --cov-append + + Do not delete coverage but append to current. Default: False + +.. option:: --cov-branch + + Enable branch coverage. Can also be specified in the `coverage config file`_ ``[run]`` section. + +.. option:: --cov-precision COV_PRECISION + + Override the reporting precision. Can also be specified in the `coverage config file`_ ``[report]`` section. + +.. option:: --cov-context CONTEXT + + Dynamic contexts to use. "test" for now. .. note:: Important Note @@ -65,4 +96,4 @@ Also, if you change the working directory and also use subprocesses in a test yo use the expected configuration file in the subprocess. .. _`coverage config file`: https://coverage.readthedocs.io/en/latest/config.html -.. _addopts: https://docs.pytest.org/en/stable/reference/reference.html#confval-addopts> +.. _addopts: https://docs.pytest.org/en/stable/reference/reference.html#confval-addopts From 192ee4faddfc3e0e91065ce2481eac25151a40a9 Mon Sep 17 00:00:00 2001 From: Olena Date: Fri, 24 Apr 2026 22:29:00 +0300 Subject: [PATCH 4/5] Replace inline code with :file: role for .coveragerc --- docs/config.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index 1c883400..7c1838e8 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -22,7 +22,7 @@ CLI options: .. option:: --cov-config PATH - Config file for coverage. Default: .coveragerc + Config file for coverage. Default: :file:`.coveragerc` .. option:: --no-cov-on-fail @@ -56,10 +56,10 @@ CLI options: .. note:: Important Note This plugin overrides the ``parallel`` option of coverage. Unless you also run coverage without pytest-cov it's - pointless to set those options in your ``.coveragerc``. + pointless to set those options in your :file:`.coveragerc`. If you use the ``--cov=something`` option (with a value) then coverage's ``source`` option will also get overridden. - If you have multiple sources it might be easier to set those in ``.coveragerc`` and always use ``--cov`` (without a value) + If you have multiple sources it might be easier to set those in :file:`.coveragerc` and always use ``--cov`` (without a value) instead of having a long command line with ``--cov=pkg1 --cov=pkg2 --cov=pkg3 ...``. If you use the ``--cov-branch`` option then coverage's ``branch`` option will also get overridden. @@ -86,7 +86,7 @@ Or for ``pyproject.toml``: :: Caveats ======= -An unfortunate consequence of coverage.py's history is that ``.coveragerc`` is a magic name: it's the default file but it also +An unfortunate consequence of coverage.py's history is that :file:`.coveragerc` is a magic name: it's the default file but it also means "try to also lookup coverage configuration in ``tox.ini`` or ``setup.cfg``". In practical terms this means that if you have multiple configuration files around (``tox.ini``, ``pyproject.toml`` or ``setup.cfg``) you From 6c575ed87f22f4adcc4bf23e5a8588801ecf3199 Mon Sep 17 00:00:00 2001 From: Olena Date: Fri, 24 Apr 2026 22:52:04 +0300 Subject: [PATCH 5/5] Extend :file: role to setup.cfg, pyproject.toml, and tox.ini --- docs/config.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index 7c1838e8..ed8a9c1c 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -65,14 +65,14 @@ CLI options: If you use the ``--cov-branch`` option then coverage's ``branch`` option will also get overridden. If you wish to always run pytest-cov with pytest, you can use ``addopts`` under the ``pytest`` or ``tool:pytest`` section of -your ``setup.cfg``, or the ``tool.pytest.ini_options`` section of your ``pyproject.toml`` file. +your :file:`setup.cfg`, or the ``tool.pytest.ini_options`` section of your :file:`pyproject.toml` file. -For example, in ``setup.cfg``: :: +For example, in :file:`setup.cfg`: :: [tool:pytest] addopts = --cov= --cov-report html -Or for ``pyproject.toml``: :: +Or for :file:`pyproject.toml`: :: [tool.pytest.ini_options] addopts = "--cov= --cov-report html" @@ -87,9 +87,9 @@ Caveats ======= An unfortunate consequence of coverage.py's history is that :file:`.coveragerc` is a magic name: it's the default file but it also -means "try to also lookup coverage configuration in ``tox.ini`` or ``setup.cfg``". +means "try to also lookup coverage configuration in :file:`tox.ini` or :file:`setup.cfg`". -In practical terms this means that if you have multiple configuration files around (``tox.ini``, ``pyproject.toml`` or ``setup.cfg``) you +In practical terms this means that if you have multiple configuration files around (:file:`tox.ini`, :file:`pyproject.toml` or :file:`setup.cfg`) you might need to use ``--cov-config`` to make coverage use the correct configuration file. Also, if you change the working directory and also use subprocesses in a test you might also need to use ``--cov-config`` to make pytest-cov