1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
.. This file is processed with cog to create the tabbed multi-syntax
configuration examples. If those are wrong, the quality checks will fail.
Running "make prebuild" checks them and produces the output.
.. [[[cog
from cog_helpers import show_configs
.. ]]]
.. [[[end]]] (checksum: d41d8cd98f00b204e9800998ecf8427e)
.. _plugins:
========
Plug-ins
========
Coverage.py's behavior can be extended with third-party plug-ins. A plug-in is
a separately installed Python class that you register in your .coveragerc.
Plugins can alter a number of aspects of coverage.py's behavior, including
implementing coverage measurement for non-Python files.
Information about using plug-ins is on this page. To write a plug-in, see
:ref:`api_plugin`.
See :ref:`other` for available plug-ins.
.. versionadded:: 4.0
Using plug-ins
--------------
To use a coverage.py plug-in, you install it and configure it. For this
example, let's say there's a Python package called ``something`` that provides
a coverage.py plug-in called ``something.plugin``.
#. Install the plug-in's package as you would any other Python package:
.. code-block:: sh
$ python3 -m pip install something
#. Configure coverage.py to use the plug-in. You do this by editing (or
creating) your .coveragerc file, as described in :ref:`config`. The
``plugins`` setting indicates your plug-in. It's a list of importable
module names of plug-ins:
.. [[[cog
show_configs(
ini=r"""
[run]
plugins =
something.plugin
""",
toml=r"""
[tool.coverage.run]
plugins = [ "something.plugin" ]
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[run]
plugins =
something.plugin
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.run]
plugins = [ "something.plugin" ]
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:run]
plugins =
something.plugin
.. [[[end]]] (checksum: 6e866323d4bc319d42e3199b08615111)
#. If the plug-in needs its own configuration, you can add those settings in
the .coveragerc file in a section named for the plug-in:
.. [[[cog
show_configs(
ini=r"""
[something.plugin]
option1 = True
option2 = abc.foo
""",
toml=r"""
[tool.coverage.something.plugin]
option1 = true
option2 = "abc.foo"
""",
)
.. ]]]
.. tabs::
.. code-tab:: ini
:caption: .coveragerc
[something.plugin]
option1 = True
option2 = abc.foo
.. code-tab:: toml
:caption: pyproject.toml
[tool.coverage.something.plugin]
option1 = true
option2 = "abc.foo"
.. code-tab:: ini
:caption: setup.cfg or tox.ini
[coverage:something.plugin]
option1 = True
option2 = abc.foo
.. [[[end]]] (checksum: b690115dbe7f6c7806567e009b5715c4)
Check the documentation for the plug-in for details on the options it takes.
#. Run your tests with coverage.py as you usually would. If you get a message
like "Plugin file tracers (something.plugin) aren't supported with
PyTracer," then you don't have the :ref:`C extension <install_extension>`
installed. The C extension is needed for certain plug-ins.
|
