Plug-ins — Coverage.py 7.8.0 documentation (original) (raw)

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, seePlug-in classes.

See Other resources for available plug-ins.

Added in version 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:
$ 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 Configuration reference. Theplugins setting indicates your plug-in. It’s a list of importable module names of plug-ins:
- .coveragerc
- pyproject.toml
- setup.cfg or tox.ini
  [run]
  plugins =
  something.plugin
  [tool.coverage.run]
  plugins = [ "something.plugin" ]
  [coverage:run]
  plugins =
  something.plugin
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:
- .coveragerc
- pyproject.toml
- setup.cfg or tox.ini
  [something.plugin]
  option1 = True
  option2 = abc.foo
  [tool.coverage.something.plugin]
  option1 = true
  option2 = "abc.foo"
  [coverage:something.plugin]
  option1 = True
  option2 = abc.foo
  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 C extensioninstalled. The C extension is needed for certain plug-ins.