feat(coverage): add support for coverage reporter options

docs/config/index.md

@@ -684,13 +684,28 @@ When using `c8` provider a temporary `/tmp` directory is created for [V8 coverag
 
 #### reporter
 
-- **Type:** `string | string[]`
+- **Type:** `string | string[] | [string, {}][]`
 - **Default:** `['text', 'html', 'clover', 'json']`
 - **Available for providers:** `'c8' | 'istanbul'`
 - **CLI:** `--coverage.reporter=<reporter>`, `--coverage.reporter=<reporter1> --coverage.reporter=<reporter2>`
 
-Coverage reporters to use. See [istanbul documentation](https://istanbul.js.org/docs/advanced/alternative-reporters/) for detailed list of all reporters.
-
+Coverage reporters to use. See [istanbul documentation](https://istanbul.js.org/docs/advanced/alternative-reporters/) for detailed list of all reporters. See [`@types/istanbul-reporter`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/276d95e4304b3670eaf6e8e5a7ea9e265a14e338/types/istanbul-reports/index.d.ts) for details about reporter specific options.
+
+The reporter has three different types:
+
+- A single reporter: `{ reporter: 'html' }`
+- Multiple reporters without options: `{ reporter: ['html', 'json'] }`
+- A single or multiple reporters with reporter options:
+  <!-- eslint-skip -->
+  ```ts
+  {
+    reporter: [
+      ['lcov', { 'projectRoot': './src' }],
+      ['json', { 'file': 'coverage.json' }],
+      ['text']
+    ]
+  }
+  ```
 
 #### skipFull
 

packages/coverage-c8/src/provider.ts

@@ -6,7 +6,7 @@ import { extname, resolve } from 'pathe'
 import type { RawSourceMap } from 'vite-node'
 import { coverageConfigDefaults } from 'vitest/config'
 // eslint-disable-next-line no-restricted-imports
-import type { CoverageC8Options, CoverageProvider, ReportContext, ResolvedCoverageOptions } from 'vitest'
+import type { CoverageC8Options, CoverageOptions, CoverageProvider, ReportContext, ResolvedCoverageOptions } from 'vitest'
 import type { Vitest } from 'vitest/node'
 import type { Report } from 'c8'
 // @ts-expect-error missing types
@@ -55,6 +55,18 @@ export class C8CoverageProvider implements CoverageProvider {
     const options: ConstructorParameters<typeof Report>[0] = {
       ...this.options,
       all: this.options.all && allTestsRun,
+      reporter: this.options.reporter.map(([reporterName]) => reporterName),
+
+      // TODO: This requires unreleased c8@7.13.0
+      // @ts-expect-error -- untyped
+      reporterOptions: this.options.reporter.reduce((all, [name, options]) => ({
+        ...all,
+        [name]: {
+          skipFull: this.options.skipFull,
+          projectRoot: this.ctx.config.root,
+          ...options,
+        },
+      }), {}),
     }
 
     const report = createReport(options)
@@ -159,7 +171,6 @@ export class C8CoverageProvider implements CoverageProvider {
 
 function resolveC8Options(options: CoverageC8Options, root: string): Options {
   const reportsDirectory = resolve(root, options.reportsDirectory || coverageConfigDefaults.reportsDirectory)
-  const reporter = options.reporter || coverageConfigDefaults.reporter
 
   const resolved: Options = {
     ...coverageConfigDefaults,
@@ -174,7 +185,7 @@ function resolveC8Options(options: CoverageC8Options, root: string): Options {
     // Resolved fields
     provider: 'c8',
     tempDirectory: process.env.NODE_V8_COVERAGE || resolve(reportsDirectory, 'tmp'),
-    reporter: Array.isArray(reporter) ? reporter : [reporter],
+    reporter: resolveReporters(options.reporter || coverageConfigDefaults.reporter),
     reportsDirectory,
   }
 
@@ -187,3 +198,25 @@ function resolveC8Options(options: CoverageC8Options, root: string): Options {
 
   return resolved
 }
+
+// TODO: Move to some generic utility for sharing with istanbul-provider
+function resolveReporters(configReporters: NonNullable<CoverageOptions['reporter']>): Options['reporter'] {
+  // E.g. { reporter: "html" }
+  if (!Array.isArray(configReporters))
+    return [[configReporters, {}]]
+
+  const resolvedReporters: Options['reporter'] = []
+
+  for (const reporter of configReporters) {
+    if (Array.isArray(reporter)) {
+      // E.g. { reporter: [ ["html", { skipEmpty: true }], ["lcov"], ["json", { file: "map.json" }] ]}
+      resolvedReporters.push([reporter[0], reporter[1] || {}])
+    }
+    else {
+      // E.g. { reporter: ["html", "json"]}
+      resolvedReporters.push([reporter, {}])
+    }
+  }
+
+  return resolvedReporters
+}

packages/coverage-istanbul/src/provider.ts

@@ -2,7 +2,7 @@
 import { existsSync, promises as fs } from 'fs'
 import { relative, resolve } from 'pathe'
 import type { TransformPluginContext } from 'rollup'
-import type { AfterSuiteRunMeta, CoverageIstanbulOptions, CoverageProvider, ReportContext, ResolvedCoverageOptions, Vitest } from 'vitest'
+import type { AfterSuiteRunMeta, CoverageIstanbulOptions, CoverageOptions, CoverageProvider, ReportContext, ResolvedCoverageOptions, Vitest } from 'vitest'
 import { coverageConfigDefaults, defaultExclude, defaultInclude } from 'vitest/config'
 import libReport from 'istanbul-lib-report'
 import reports from 'istanbul-reports'
@@ -123,9 +123,10 @@ export class IstanbulCoverageProvider implements CoverageProvider {
     })
 
     for (const reporter of this.options.reporter) {
-      reports.create(reporter, {
+      reports.create(reporter[0], {
         skipFull: this.options.skipFull,
         projectRoot: this.ctx.config.root,
+        ...reporter[1],
       }).execute(context)
     }
 
@@ -221,7 +222,6 @@ export class IstanbulCoverageProvider implements CoverageProvider {
 
 function resolveIstanbulOptions(options: CoverageIstanbulOptions, root: string): Options {
   const reportsDirectory = resolve(root, options.reportsDirectory || coverageConfigDefaults.reportsDirectory)
-  const reporter = options.reporter || coverageConfigDefaults.reporter
 
   const resolved: Options = {
     ...coverageConfigDefaults,
@@ -232,7 +232,7 @@ function resolveIstanbulOptions(options: CoverageIstanbulOptions, root: string):
     // Resolved fields
     provider: 'istanbul',
     reportsDirectory,
-    reporter: Array.isArray(reporter) ? reporter : [reporter],
+    reporter: resolveReporters(options.reporter || coverageConfigDefaults.reporter),
   }
 
   return resolved
@@ -287,3 +287,25 @@ function isEmptyCoverageRange(range: libCoverage.Range) {
     || range.end.column === undefined
   )
 }
+
+// TODO: Move to some generic utility for sharing with c8-provider
+function resolveReporters(configReporters: NonNullable<CoverageOptions['reporter']>): Options['reporter'] {
+  // E.g. { reporter: "html" }
+  if (!Array.isArray(configReporters))
+    return [[configReporters, {}]]
+
+  const resolvedReporters: Options['reporter'] = []
+
+  for (const reporter of configReporters) {
+    if (Array.isArray(reporter)) {
+      // E.g. { reporter: [ ["html", { skipEmpty: true }], ["lcov"], ["json", { file: "map.json" }] ]}
+      resolvedReporters.push([reporter[0], reporter[1] || {}])
+    }
+    else {
+      // E.g. { reporter: ["html", "json"]}
+      resolvedReporters.push([reporter, {}])
+    }
+  }
+
+  return resolvedReporters
+}

packages/vitest/package.json

@@ -108,6 +108,7 @@
   "dependencies": {
     "@types/chai": "^4.3.4",
     "@types/chai-subset": "^1.3.3",
+    "@types/istanbul-reports": "^3.0.1",
     "@types/node": "*",
     "acorn": "^8.8.1",
     "acorn-walk": "^8.2.0",

packages/vitest/src/defaults.ts

@@ -32,7 +32,7 @@ export const coverageConfigDefaults: ResolvedCoverageOptions = {
   cleanOnRerun: true,
   reportsDirectory: './coverage',
   exclude: defaultCoverageExcludes,
-  reporter: ['text', 'html', 'clover', 'json'],
+  reporter: [['text', {}], ['html', {}], ['clover', {}], ['json', {}]],
   // default extensions used by c8, plus '.vue' and '.svelte'
   // see https://github.com/istanbuljs/schema/blob/master/default-extension.js
   extension: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.vue', '.svelte'],

packages/vitest/src/types/coverage.ts

@@ -1,4 +1,5 @@
 import type { TransformPluginContext, TransformResult } from 'rollup'
+import type { ReportOptions } from 'istanbul-reports'
 import type { Vitest } from '../node'
 import type { Arrayable } from './general'
 import type { AfterSuiteRunMeta } from './worker'
@@ -38,20 +39,14 @@ export interface CoverageProviderModule {
   takeCoverage?(): unknown | Promise<unknown>
 }
 
-export type CoverageReporter =
-  | 'clover'
-  | 'cobertura'
-  | 'html-spa'
-  | 'html'
-  | 'json-summary'
-  | 'json'
-  | 'lcov'
-  | 'lcovonly'
-  | 'none'
-  | 'teamcity'
-  | 'text-lcov'
-  | 'text-summary'
-  | 'text'
+export type CoverageReporter = keyof ReportOptions
+
+type CoverageReporterWithOptions<ReporterName extends CoverageReporter = CoverageReporter> =
+   ReporterName extends CoverageReporter
+     ? ReportOptions[ReporterName] extends never
+       ? [ReporterName, {}] // E.g. the "none" reporter
+       : [ReporterName, Partial<ReportOptions[ReporterName]>]
+     : never
 
 type Provider = 'c8' | 'istanbul' | CoverageProviderModule | undefined
 
@@ -68,14 +63,13 @@ type FieldsWithDefaultValues =
   | 'reportsDirectory'
   | 'exclude'
   | 'extension'
-  | 'reporter'
 
 export type ResolvedCoverageOptions<T extends Provider = Provider> =
   & CoverageOptions<T>
   & Required<Pick<CoverageOptions<T>, FieldsWithDefaultValues>>
   // Resolved fields which may have different typings as public configuration API has
   & {
-    reporter: CoverageReporter[]
+    reporter: CoverageReporterWithOptions[]
   }
 
 export interface BaseCoverageOptions {
@@ -137,7 +131,7 @@ export interface BaseCoverageOptions {
    *
    * @default ['text', 'html', 'clover', 'json']
    */
-  reporter?: Arrayable<CoverageReporter>
+  reporter?: Arrayable<CoverageReporter> | (CoverageReporter | [CoverageReporter] | CoverageReporterWithOptions)[]
 
   /**
    * Do not show files with 100% statement, branch, and function coverage

test/coverage-test/coverage-report-tests/utils.ts

@@ -17,7 +17,7 @@ interface CoverageFinalJson {
  */
 export async function readCoverageJson() {
   // @ts-expect-error -- generated file
-  const { default: jsonReport } = await import('./coverage/coverage-final.json') as CoverageFinalJson
+  const { default: jsonReport } = await import('./coverage/custom-json-report-name.json') as CoverageFinalJson
 
   const normalizedReport: CoverageFinalJson['default'] = {}
 

test/coverage-test/test/configuration-options.test-d.ts

@@ -28,7 +28,7 @@ test('providers, custom', () => {
               enabled: true,
               exclude: ['string'],
               extension: ['string'],
-              reporter: ['html', 'json'],
+              reporter: [['html', {}], ['json', { file: 'string' }]],
               reportsDirectory: 'string',
             }
           },
@@ -139,3 +139,55 @@ test('reporters, multiple', () => {
   // @ts-expect-error -- ... and all reporters must be known
   assertType<Coverage>({ reporter: ['html', 'json', 'unknown-reporter'] })
 })
+
+test('reporters, with options', () => {
+  assertType<Coverage>({
+    reporter: [
+      ['clover', { projectRoot: 'string', file: 'string' }],
+      ['cobertura', { projectRoot: 'string', file: 'string' }],
+      ['html-spa', { metricsToShow: ['branches', 'functions'], verbose: true, subdir: 'string' }],
+      ['html', { verbose: true, subdir: 'string' }],
+      ['json-summary', { file: 'string' }],
+      ['json', { file: 'string' }],
+      ['lcov', { projectRoot: 'string', file: 'string' }],
+      ['lcovonly', { projectRoot: 'string', file: 'string' }],
+      ['none'],
+      ['teamcity', { blockName: 'string' }],
+      ['text-lcov', { projectRoot: 'string' }],
+      ['text-summary', { file: 'string' }],
+      ['text', { skipEmpty: true, skipFull: true, maxCols: 1 }],
+    ],
+  })
+
+  assertType<Coverage>({
+    reporter: [
+      ['html', { subdir: 'string' }],
+      ['json'],
+      ['lcov', { projectRoot: 'string' }],
+    ],
+  })
+
+  assertType<Coverage>({
+    reporter: [
+      // @ts-expect-error -- teamcity report option on html reporter
+      ['html', { blockName: 'string' }],
+
+      // @ts-expect-error -- html-spa report option on json reporter
+      ['json', { metricsToShow: ['branches'] }],
+
+      // @ts-expect-error -- second value should be object even though TS intellisense prompts types of reporters
+      ['lcov', 'html-spa'],
+    ],
+  })
+})
+
+test('reporters, mixed variations', () => {
+  assertType<Coverage>({
+    reporter: [
+      'clover',
+      ['cobertura'],
+      ['html-spa', {}],
+      ['html', { verbose: true, subdir: 'string' }],
+    ],
+  })
+})

test/coverage-test/vitest.config.ts

@@ -15,7 +15,12 @@ export default defineConfig({
       enabled: true,
       clean: true,
       all: true,
-      reporter: ['html', 'text', 'lcov', 'json'],
+      reporter: [
+        'text',
+        ['html'],
+        ['lcov', {}],
+        ['json', { file: 'custom-json-report-name.json' }],
+      ],
     },
     setupFiles: [
       resolve(__dirname, './setup.ts'),