doc/plugins.rst

   1 .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
   2 .. For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt
   3
   4 .. _plugins:
   5
   6 =======
   7 Plugins
   8 =======
   9
  10 .. :history: 20150124T143000, new page.
  11 .. :history: 20150802T174600, updated for 4.0b1
  12
  13
  14 Coverage.py's behavior can be extended with third-party plugins.  A plugin is a
  15 separately installed Python class that you register in your .coveragerc.
  16 Plugins can be used to implement coverage measurement for non-Python files.
  17
  18 Plugins are only supported with the :ref:`C extension <install_extension>`,
  19 which must be installed for plugins to work.
  20
  21 Information about using plugins is on this page.  To write a plugin, see
  22 :ref:`api_plugin`.
  23
  24 .. versionadded:: 4.0
  25
  26
  27 Using plugins
  28 -------------
  29
  30 To use a coverage.py plugin, you install it, and configure it.  For this
  31 example, let's say there's a Python package called ``something`` that provides a
  32 coverage.py plugin called ``something.plugin``.
  33
  34 #. Install the plugin's package as you would any other Python package::
  35
  36     pip install something
  37
  38 #. Configure coverage.py to use the plugin.  You do this by editing (or
  39    creating) your .coveragerc file, as described in :ref:`config`.  The
  40    ``plugins`` setting indicates your plugin.  It's a list of importable module
  41    names of plugins::
  42
  43     [run]
  44     plugins =
  45         something.plugin
  46
  47 #. If the plugin needs its own configuration, you can add those settings in
  48    the .coveragerc file in a section named for the plugin::
  49
  50     [something.plugin]
  51     option1 = True
  52     option2 = abc.foo
  53
  54    Check the documentation for the plugin to see if it takes any options, and
  55    what they are.
  56
  57 #. Run your tests with coverage.py as you usually would.  If you get a message
  58    like "Plugin file tracers (something.plugin) aren't supported with
  59    PyTracer," then you don't have the :ref:`C extension <install_extension>`
  60    installed.
  61
  62
  63 Available plugins
  64 -----------------
  65
  66 Some coverage.py plugins you might find useful:
  67
  68 * `Django template coverage.py plugin`__: for measuring coverage in Django
  69   templates.
  70
  71   .. __: https://pypi.python.org/pypi/django_coverage_plugin
  72
  73 * `Mako template coverage plugin`__: for measuring coverage in Mako templates.
  74   Doesn't work yet, probably needs some changes in Mako itself.
  75
  76   .. __: https://bitbucket.org/ned/coverage-mako-plugin