vite-plugin-istanbul

What is vite-plugin-istanbul?

vite-plugin-istanbul is a Vite plugin that integrates Istanbul for code coverage reporting. It allows you to instrument your code with Istanbul, which is useful for generating code coverage reports during testing.

What are vite-plugin-istanbul's main functionalities?

Code Instrumentation

This feature allows you to instrument your code for coverage reporting. You can specify which files to include or exclude, the file extensions to consider, and whether to require an environment variable to enable instrumentation.

import { defineConfig } from 'vite';
import istanbul from 'vite-plugin-istanbul';

export default defineConfig({
  plugins: [
    istanbul({
      include: 'src/*',
      exclude: ['node_modules', 'test/'],
      extension: ['.js', '.ts', '.vue'],
      requireEnv: true,
    }),
  ],
});

Custom Reporting

This feature allows you to customize the reporting options for Istanbul. You can specify the reporters to use and the directory where the reports should be saved.

import { defineConfig } from 'vite';
import istanbul from 'vite-plugin-istanbul';

export default defineConfig({
  plugins: [
    istanbul({
      include: 'src/*',
      exclude: ['node_modules', 'test/'],
      extension: ['.js', '.ts', '.vue'],
      requireEnv: true,
      cypress: true,
      nyc: {
        reporter: ['html', 'text-summary'],
        reportDir: './coverage',
      },
    }),
  ],
});

Other packages similar to vite-plugin-istanbul

babel-plugin-istanbul

babel-plugin-istanbul is a Babel plugin for code coverage using Istanbul. It is similar to vite-plugin-istanbul but is used in Babel-based projects. It provides similar functionality for instrumenting code and generating coverage reports.

karma-coverage

karma-coverage is a Karma plugin that uses Istanbul to generate code coverage reports. It is used in projects that use the Karma test runner and provides similar functionality for code instrumentation and reporting.

jest

Jest is a JavaScript testing framework that has built-in support for code coverage using Istanbul. It provides a comprehensive testing solution with integrated code coverage reporting, making it a more all-in-one solution compared to vite-plugin-istanbul.

README

vite-plugin-istanbul

A Vite plugin to instrument your code for nyc/istanbul code coverage. In similar way as the Webpack Loader istanbul-instrumenter-loader. Only intended for use in development while running tests.

Only versions targeting the latest stable Vite version is actively developed.

Installation

npm i -D vite-plugin-istanbul

or if you use yarn

yarn add -D vite-plugin-istanbul

API

import IstanbulPlugin from 'vite-plugin-istanbul';

IstanbulPlugin( [ opts ] )

Creates the vite plugin from a set of optional plugin options.

Returns: Vite Plugin

Parameters

• opts {IstanbulPluginOptions} - Object of optional options to pass to the plugin.
• opts.cwd {string} - Optional string of the current working directory, used for the include/exclude patterns. Defaults to process.cwd().
• opts.include {string|string[]} - Optional string or array of strings of glob patterns to include.
• opts.exclude {string|string[]} - Optional string or array of strings of glob patterns to exclude.
• opts.extension {string|string[]} - Optional string or array of strings of extensions to include (dot prefixed like .js or .ts). By default this is set to ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.vue'].
• opts.requireEnv {boolean} - Optional boolean to require the environment variable (defaults to VITE_COVERAGE) to equal true in order to instrument the code. Otherwise it will instrument even if env variable is not set. However if requireEnv is not set the instrumentation will stop if the environment variable is equal to false.
• opts.cypress {boolean} - Optional boolean to change the environment variable to CYPRESS_COVERAGE instead of VITE_COVERAGE. For ease of use with `@cypress/code-coverage``.
• opts.checkProd {boolean} - Optional boolean to enforce the plugin to skip instrumentation for production environments. Looks at Vite's isProduction key from the ResolvedConfig.
• opts.forceBuildInstrument {boolean} - Optional boolean to enforce the plugin to add instrumentation in build mode. Defaults to false.
• opts.nycrcPath {string} - Path to specific nyc config to use instead of automatically searching for a nycconfig. This parameter is just passed down to @istanbuljs/load-nyc-config.

Notes

As of v2.1.0 you can toggle the coverage off by setting the env variable VITE_COVERAGE='false', by default it will always instrument the code. To require the explicit definition of the variable, set the option requireEnv to true.

This plugin also requires the Vite configuration build.sourcemap to be set to either true, 'inline', 'hidden'. But the plugin will automatically default to true if it is missing in order to give accurate code coverage. The plugin will notify when this happens in order for a developer to fix it. This notification will show even when the plugin is disabled by e.g opts.requireEnv, VITE_COVERAGE=false. This is due to a limitation of the API for this kind of feature.

Examples

To use this plugin define it using vite.config.js

// vite.config.js
import istanbul from 'vite-plugin-istanbul';

export default {
  open: true,
  port: 3000,
  plugins: [
    istanbul({
      include: 'src/*',
      exclude: ['node_modules', 'test/'],
      extension: ['.js', '.ts', '.vue'],
      requireEnv: true,
    }),
  ],
};

License

MIT