Jest ignore or exclude file/function/statement from test coverage

In computer science, test coverage is a measure used to describe the degree to which the source code of a program is executed when a particular test suite runs.

Code coverage - Wikipedia

Code coverage is usually used as a quality metric for software eg. “Our code has to have 80%+ test coverage”. Gathering test coverage with Jest is as simple as using the --coverage flag on invocation.

This post goes through how to ignore files, functions, lines and statements from coverage in Jest using configuration or istanbul pragmas. As well as reasons and limits to why/how you would do such a thing.

You can find a working examples repository at github.com/HugoDF/jest-ignore-coverage.

How does Jest even calculate coverage?

Jest uses istanbul under the hood to calculate coverage. Mostly Jest abstracts this from the end user, all you have to do in your application is call jest --coverage (and configured the appropriate coverage configuration fields). The fact that istanbul is used internally does show, for example, the documentation for coverageReporters mentions that “Any istanbul reporter can be used.”, which shows what’s actually collecting coverage data and generating the reports.

Why would I want to exclude/ignore files or lines from coverage?

As stated by the maintainers and authors of the istanbul coverage libary:

Some branches in JS code are typically hard, if not impossible to test. Examples are a hasOwnProperty check, UMD wrappers and so on. Istanbul now has a facility by which coverage can be excluded for certain sections of code.

Istanbul - Ignore code for coverage purposes

What’s more, 100% coverage isn’t necessary or even reasonable in most cases. Some files don’t contain any (business) logic. Or they contain logic that would fail in a very obvious way (eg. a starter crashing on start).

For example the script that would bootstrap an application might bind to a port, which makes it unwieldy to test. The file that imports all the different dependencies and app.use()-es them in an Express setting would be another candidate for maybe avoiding the unit testing/dependency mocking hell.

Another class of files/functions you might want to ignore for coverage purposes are test-specific helpers. It doesn’t matter that some of them aren’t run as part of tests, as they’re not the code under test.

As with a lot of things in software, it’s about tradeoffs.

Exclude/ignore file(s) from Jest coverage by not running relevant tests using configuration

There’s a Jest configuration option testPathIgnorePatterns (see the docs for testPathIgnorePatterns)

The simplest way to configure this is through the package.json:

{
  "jest": {
    "testPathIgnorePatterns" : [
      "<rootDir>/ignore/this/path/" 
    ]
  }
}

See it in action at Exclude file(s) from Jest coverage using configuration on GitHub.

Exclude/ignore file(s) from coverage by not including it in the coverage collection configuration

As an alternative or augmentation to not running tests (as seen in “Exclude file from Jest coverage by not running relevant tests using configuration”) from Jest coverage by not including it in coverage reports, that’s controlled by the collectCoverageFrom Jest configuration option (see the docs for Jest collectCoverageFrom).

Use something like the following:

{
  "jest": {
    "collectCoverageFrom": [
      "src/**/{!(ignore-me),}.js"
    ]
  }
}

Important: make sure to wrap the ignored file’s name with ().

See it in action at Exclude file(s) from Jest coverage using configuration on GitHub.

Exclude/ignore file from Jest coverage at the file level

We can use istanbul pragmas to ignore files using the following comment at the top of any file:

/* istanbul ignore file */

See it in action at Exclude file from Jest coverage at the file level on GitHub

Exclude/ignore function from Jest coverage

/* istanbul ignore next */
function myFunc() {
  console.log(
    "Not covered but won't appear on coverage reports as such"
  );
}

See it in action at Exclude function or statement from Jest coverage on GitHub.

Exclude/ignore line(s) from Jest coverage

Avoid this if you can, if you’re testing some code you should probably test all of that code.

istanbul ignore next also works to ignore JS statements, definitions and expressions which equates to ignoring/excluding the line from coverage:

// this function will appear as uncovered
function ignoreLine() {
  /* istanbul ignore next */
  console.log(
    'This line won\'t appear as uncovered'
	);
}

You can see the full snippet at github.com/HugoDF/jest-ignore-coverage/blob/master/src/snippet.js#L8-L14

Exclude/ignore statement or clause from Jest coverage

Avoid this if you can, if you’re testing some code you should probably test all of that code.

function myFunc(a) {
  /* istanbul ignore else */
  if (a) {
    // do some work
  } else {
    // do some other work
  }
}

See it in action at Exclude function or statement from Jest coverage on GitHub.

Further Reading

See the original istanbul documentation on ignoring code for coverage for a more extensive look at how to do this in different situations.

I’ve also put a together an examples repo with all the different cases in action github.com/HugoDF/jest-ignore-coverage.

Charles 🇵🇭