# Test coverage reporting

Use this plugin to activate coverage report.

To use this plugin, you need to install `nose2[coverage_plugin]`. e.g.

    $ pip install nose2[coverage_plugin]>=0.6.5

Then, you can enable coverage reporting with :

    $ nose2 --with-coverage

Or with this lines in `unittest.cfg` :

    [coverage]
    always-on = True

You can further specify coverage behaviors with a `.coveragerc` file, as specified by Coverage Config. However, when doing so you should also be aware of Differences From coverage.

## Configuration [coverage]

always-on
  Default:

    False

  Type:

    boolean

coverage
  Default:

    []

  Type:

    list

coverage-combine
  Default:

    False

  Type:

    boolean

coverage-config
  Default:

  Type:

    str

coverage-report
  Default:

    []

  Type:

    list

### Sample configuration

The default configuration is equivalent to including the following in a `unittest.cfg` file.

    [coverage]
    always-on = False
    coverage =
    coverage-combine = False
    coverage-config =
    coverage-report =

## Command-line options

--coverage PATH

  Measure coverage for filesystem path (multi-allowed)

--coverage-report TYPE

  Generate selected reports, available types: term, term-missing, annotate, html, xml (multi-allowed)

--coverage-config FILE

  Config file for coverage, default: .coveragerc

-C DEFAULT, --with-coverage DEFAULT

  Turn on coverage reporting

## Plugin class reference: Coverage

class nose2.plugins.coverage.Coverage(*args, **kwargs)
  afterSummaryReport(event)

    Reporting data is collected, failure status determined and set. Now print any buffered error output saved from beforeSummaryReport

  beforeSummaryReport(event)

    Only called if active so stop coverage and produce reports.

  createTests(event)

    Start coverage early to catch imported modules.

    Only called if active so, safe to just start without checking flags

  handleArgs(event)

    Get our options in order command line, config file, hard coded.

  wasSuccessful(event)

    Mark full test run as successful or unsuccessful

## Differences From coverage

The `coverage` tool is the basis for nose2’s coverage reporting. nose2 will seek to emulate `coverage` behavior whenever possible, but there are known cases where this is not feasible.

If you need the exact behaviors of `coverage`, consider having `coverage` invoke `nose2`.

Otherwise, please be aware of the following known differences:

- The `fail_under` parameter results in an exit status of 2 for `coverage`, but an exit status of 1 for `nose2`

## Compatibility with mp plugin

The `coverage` and `mp` plugins may be used in conjunction to enable multiprocess testing with coverage reporting.

Special instructions:

- Due to the way the plugin is reloaded in subprocesses, command-line options for the `coverage` plugin have no effect. If you need to change any `coverage` plugin options, use a configuration file.

- Do not use the `concurrency` option within a `.coveragerc` file ; this interferes with the `coverage` plugin, which automatically handles multiprocess coverage reporting.