From 1ddab06f013e44bd733ceae9f093ac3a8d022aac Mon Sep 17 00:00:00 2001 From: yashwanth195 <59129034+yashwanth195@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:12:22 -0800 Subject: [PATCH 1/2] Validate managed Jest configuration --- .../jest-managed-config_2026-11-13.json | 10 + heft-plugins/heft-jest-plugin/README.md | 4 + .../src/JestManagedConfiguration.ts | 85 +++++++++ .../src/test/JestManagedConfiguration.test.ts | 171 ++++++++++++++++++ 4 files changed, 270 insertions(+) create mode 100644 common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json create mode 100644 heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts create mode 100644 heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts diff --git a/common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json b/common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json new file mode 100644 index 00000000000..44fdbd34ace --- /dev/null +++ b/common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@rushstack/heft-jest-plugin", + "comment": "Add managed Jest shard configuration preflight and a shared coverage reporter policy without enabling sharded execution.", + "type": "minor" + } + ], + "packageName": "@rushstack/heft-jest-plugin" +} diff --git a/heft-plugins/heft-jest-plugin/README.md b/heft-plugins/heft-jest-plugin/README.md index 25f82e5ef62..8fc3b8542aa 100644 --- a/heft-plugins/heft-jest-plugin/README.md +++ b/heft-plugins/heft-jest-plugin/README.md @@ -2,6 +2,10 @@ This is a Heft plugin for running Jest. +`lib/JestManagedConfiguration` provides a pure preflight foundation for managed Jest shards and a shared +coverage reporter policy. It rejects unsupported settings without changing configuration. Runtime integration +is not enabled; ordinary Jest hooks, reporters, and execution are unchanged. + ## Links - [CHANGELOG.md]( diff --git a/heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts b/heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts new file mode 100644 index 00000000000..937e0d81eb4 --- /dev/null +++ b/heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts @@ -0,0 +1,85 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +import type { Config } from '@jest/reporters'; + +const SUPPORTED_COVERAGE_REPORTERS: ReadonlySet = new Set([ + 'json', + 'json-summary', + 'lcov', + 'lcovonly', + 'html', + 'clover', + 'cobertura', + 'text', + 'text-summary' +]); + +/** + * The shared builtin coverage reporter policy for managed Jest shards. + */ +export function isSupportedCoverageReporter(reporter: string): boolean { + return SUPPORTED_COVERAGE_REPORTERS.has(reporter); +} + +/** + * Rejects unsupported managed-shard settings without modifying the configuration. + * This preflight is not enabled by the Jest plugin until managed shard execution is integrated. + */ +export function validateManagedJestConfiguration(jestConfig: Config.InitialOptions): void { + const unsupported: ReadonlyArray = [ + 'testResultsProcessor', + 'projects', + 'preset', + 'runner', + 'testRunner', + 'filter', + 'outputFile', + 'json', + 'forceExit', + 'globalSetup', + 'globalTeardown' + ]; + for (const property of unsupported) { + if (jestConfig[property] !== undefined) { + throw new Error( + `Managed Jest sharding does not support "${property}". Remove it or run without "--shard-output-directory".` + ); + } + } + if ( + jestConfig.reporters !== undefined && + (!Array.isArray(jestConfig.reporters) || jestConfig.reporters.some((reporter) => reporter !== 'default')) + ) { + throw new Error( + 'Managed Jest sharding supports only the default Heft reporter. Custom reporters may write shared ' + + 'output or report additional failures; use an unsharded run instead.' + ); + } + if (jestConfig.bail) { + throw new Error('Managed Jest sharding does not support "bail": every scheduled test suite must finish.'); + } + if (jestConfig.coverageThreshold !== undefined && !jestConfig.collectCoverage) { + throw new Error( + 'Managed Jest coverageThreshold requires collectCoverage. "--disable-code-coverage" cannot bypass required thresholds.' + ); + } + if ( + jestConfig.collectCoverage && + (jestConfig.coverageProvider ?? 'babel') === 'babel' && + !jestConfig.collectCoverageFrom?.length + ) { + throw new Error( + 'Managed Jest Babel coverage requires nonempty "collectCoverageFrom" to validate instrumentation completeness.' + ); + } + if ( + jestConfig.coverageReporters?.some( + (reporter) => typeof reporter !== 'string' || !isSupportedCoverageReporter(reporter) + ) + ) { + throw new Error( + 'Managed Jest sharding supports only builtin coverage reporters without options or output redirects.' + ); + } +} diff --git a/heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts b/heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts new file mode 100644 index 00000000000..f7a3c4fa1a3 --- /dev/null +++ b/heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts @@ -0,0 +1,171 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +import type { Config } from '@jest/reporters'; + +import { isSupportedCoverageReporter, validateManagedJestConfiguration } from '../JestManagedConfiguration'; + +describe('validateManagedJestConfiguration', () => { + it.each<[keyof Config.InitialOptions, Config.InitialOptions]>([ + ['testResultsProcessor', { testResultsProcessor: 'processor' }], + ['projects', { projects: ['another-project'] }], + ['projects', { projects: [] }], + ['preset', { preset: 'preset' }], + ['runner', { runner: 'custom-runner' }], + ['testRunner', { testRunner: 'jest-circus/runner' }], + ['filter', { filter: 'custom-filter' }], + ['outputFile', { outputFile: '../shared.json' }], + ['outputFile', { outputFile: '' }], + ['json', { json: true }], + ['json', { json: false }], + ['forceExit', { forceExit: true }], + ['forceExit', { forceExit: false }], + ['globalSetup', { globalSetup: '/global-setup.js' }], + ['globalTeardown', { globalTeardown: '/global-teardown.js' }] + ])('rejects explicitly configured %s: %j', (property, config) => { + expect(() => validateManagedJestConfiguration(config)).toThrow( + `Managed Jest sharding does not support "${property}". Remove it or run without "--shard-output-directory".` + ); + expect(() => validateManagedJestConfiguration({ ...config, [property]: undefined })).not.toThrow(); + }); + + it.each([ + { reporters: ['custom-reporter'] }, + { reporters: ['default', 'summary'] }, + { reporters: [['default', {}]] }, + { reporters: [['default', { outputFile: '../shared' }]] } + ])('rejects custom reporters and reporter options: %j', (config) => { + expect(() => validateManagedJestConfiguration(config)).toThrow( + 'Managed Jest sharding supports only the default Heft reporter. Custom reporters may write shared ' + + 'output or report additional failures; use an unsharded run instead.' + ); + }); + + it.each([{ bail: true }, { bail: 1 }, { bail: 2 }])( + 'rejects early termination: %j', + (config) => { + expect(() => validateManagedJestConfiguration(config)).toThrow( + 'Managed Jest sharding does not support "bail": every scheduled test suite must finish.' + ); + } + ); + + it.each([undefined, false])('rejects thresholds with collectCoverage=%s', (collectCoverage) => { + expect(() => + validateManagedJestConfiguration({ + collectCoverage, + coverageThreshold: { global: { lines: 90 } } + }) + ).toThrow( + 'Managed Jest coverageThreshold requires collectCoverage. "--disable-code-coverage" cannot bypass required thresholds.' + ); + }); + + it.each([ + { collectCoverage: true }, + { collectCoverage: true, collectCoverageFrom: [] }, + { collectCoverage: true, coverageProvider: 'babel' }, + { collectCoverage: true, coverageProvider: 'babel', collectCoverageFrom: [] } + ])('requires collection patterns for default or explicit Babel coverage: %j', (config) => { + expect(() => validateManagedJestConfiguration(config)).toThrow( + 'Managed Jest Babel coverage requires nonempty "collectCoverageFrom" to validate instrumentation completeness.' + ); + }); + + it.each([ + { coverageReporters: ['html-spa'] }, + { coverageReporters: ['teamcity'] }, + { coverageReporters: ['none'] }, + { coverageReporters: ['text-lcov'] }, + { coverageReporters: [['json', {}]] }, + { coverageReporters: [['json', { file: '../shared.json' }]] } + ])('rejects unsupported coverage reporters and options even without collection: %j', (config) => { + expect(() => validateManagedJestConfiguration(config)).toThrow( + 'Managed Jest sharding supports only builtin coverage reporters without options or output redirects.' + ); + }); + + it.each<[string, RegExp]>([ + ['{"reporters":"default"}', /supports only the default Heft reporter/], + ['{"coverageReporters":["custom"]}', /builtin coverage reporters without options or output redirects/], + ['{"preset":null}', /does not support "preset"/], + ['{"globalSetup":null}', /does not support "globalSetup"/], + ['{"globalTeardown":null}', /does not support "globalTeardown"/] + ])('rejects unsupported values loaded from JSON: %s', (json, diagnostic) => { + const config: Config.InitialOptions = JSON.parse(json); + expect(() => validateManagedJestConfiguration(config)).toThrow(diagnostic); + }); + + it.each([ + {}, + { reporters: undefined, bail: undefined, coverageThreshold: undefined, coverageReporters: undefined }, + { reporters: [], bail: false }, + { reporters: ['default'], bail: 0 }, + { collectCoverage: false, coverageProvider: 'babel', collectCoverageFrom: [] }, + { collectCoverage: true, collectCoverageFrom: ['src/**/*.ts'] }, + { + collectCoverage: true, + coverageProvider: 'babel', + collectCoverageFrom: ['src/**/*.ts'], + coverageThreshold: { global: { lines: 100 } } + }, + { collectCoverage: true, coverageProvider: 'v8' }, + { + collectCoverage: true, + coverageProvider: 'v8', + collectCoverageFrom: [], + coverageThreshold: { global: { lines: 100 } }, + coverageReporters: [] + } + ])('accepts supported defaults and coverage settings: %j', (config) => { + expect(() => validateManagedJestConfiguration(config)).not.toThrow(); + }); + + it('does not mutate accepted or rejected configuration', () => { + const config: Config.InitialOptions = { + reporters: ['default'], + collectCoverage: true, + coverageProvider: 'babel', + collectCoverageFrom: ['src/**/*.ts'], + coverageThreshold: { global: { lines: 100 } }, + coverageReporters: ['json', 'lcov'] + }; + const original: Config.InitialOptions = JSON.parse(JSON.stringify(config)); + Object.freeze(config.reporters); + Object.freeze(config.collectCoverageFrom); + Object.freeze(config.coverageThreshold!.global); + Object.freeze(config.coverageThreshold); + Object.freeze(config.coverageReporters); + Object.freeze(config); + + expect(() => validateManagedJestConfiguration(config)).not.toThrow(); + expect(config).toEqual(original); + + const rejected: Config.InitialOptions = Object.freeze({ ...config, bail: true }); + expect(() => validateManagedJestConfiguration(rejected)).toThrow(/does not support "bail"/); + expect(rejected).toEqual({ ...original, bail: true }); + }); +}); + +describe('managed coverage reporter policy', () => { + it.each[number]>([ + 'json', + 'json-summary', + 'lcov', + 'lcovonly', + 'html', + 'clover', + 'cobertura', + 'text', + 'text-summary' + ])('accepts the shared builtin policy in preflight: %s', (reporter) => { + expect(() => validateManagedJestConfiguration({ coverageReporters: [reporter] })).not.toThrow(); + }); + + it.each(['custom', '../json', 'JSON', 'html-spa', 'teamcity', 'none', 'text-lcov'])( + 'does not allow unsupported reporter names: %s', + (reporter) => { + expect(isSupportedCoverageReporter(reporter)).toBe(false); + } + ); +}); From 129cad0e94b91798dfcd069b8ed6fa93d88d259a Mon Sep 17 00:00:00 2001 From: yashwanth195 <59129034+yashwanth195@users.noreply.github.com> Date: Tue, 17 Nov 2026 11:26:58 -0800 Subject: [PATCH 2/2] Require managed V8 coverage --- .../jest-managed-config_2026-11-13.json | 2 +- heft-plugins/heft-jest-plugin/README.md | 5 +++-- .../src/JestManagedConfiguration.ts | 10 ++++----- .../src/test/JestManagedConfiguration.test.ts | 22 +++++++++++-------- 4 files changed, 21 insertions(+), 18 deletions(-) diff --git a/common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json b/common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json index 44fdbd34ace..db02ea1e059 100644 --- a/common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json +++ b/common/changes/@rushstack/heft-jest-plugin/jest-managed-config_2026-11-13.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "@rushstack/heft-jest-plugin", - "comment": "Add managed Jest shard configuration preflight and a shared coverage reporter policy without enabling sharded execution.", + "comment": "Add managed Jest shard configuration preflight with V8-only coverage and a shared coverage reporter policy without enabling sharded execution.", "type": "minor" } ], diff --git a/heft-plugins/heft-jest-plugin/README.md b/heft-plugins/heft-jest-plugin/README.md index 8fc3b8542aa..463e248af29 100644 --- a/heft-plugins/heft-jest-plugin/README.md +++ b/heft-plugins/heft-jest-plugin/README.md @@ -3,8 +3,9 @@ This is a Heft plugin for running Jest. `lib/JestManagedConfiguration` provides a pure preflight foundation for managed Jest shards and a shared -coverage reporter policy. It rejects unsupported settings without changing configuration. Runtime integration -is not enabled; ordinary Jest hooks, reporters, and execution are unchanged. +coverage reporter policy. Enabled coverage requires `coverageProvider: "v8"` in the resolved configuration; +an omitted provider uses Jest's unsupported Babel default. Preflight does not change configuration. +Runtime integration is not enabled; ordinary Jest hooks, reporters, and Babel coverage are unchanged. ## Links diff --git a/heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts b/heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts index 937e0d81eb4..dbc447919c2 100644 --- a/heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts +++ b/heft-plugins/heft-jest-plugin/src/JestManagedConfiguration.ts @@ -24,6 +24,7 @@ export function isSupportedCoverageReporter(reporter: string): boolean { /** * Rejects unsupported managed-shard settings without modifying the configuration. + * Pass the resolved configuration; an omitted provider uses Jest's Babel default. * This preflight is not enabled by the Jest plugin until managed shard execution is integrated. */ export function validateManagedJestConfiguration(jestConfig: Config.InitialOptions): void { @@ -64,13 +65,10 @@ export function validateManagedJestConfiguration(jestConfig: Config.InitialOptio 'Managed Jest coverageThreshold requires collectCoverage. "--disable-code-coverage" cannot bypass required thresholds.' ); } - if ( - jestConfig.collectCoverage && - (jestConfig.coverageProvider ?? 'babel') === 'babel' && - !jestConfig.collectCoverageFrom?.length - ) { + if (jestConfig.collectCoverage && jestConfig.coverageProvider !== 'v8') { throw new Error( - 'Managed Jest Babel coverage requires nonempty "collectCoverageFrom" to validate instrumentation completeness.' + 'Managed Jest coverage requires "coverageProvider": "v8". ' + + "Babel coverage, including Jest's default provider, is not supported." ); } if ( diff --git a/heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts b/heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts index f7a3c4fa1a3..f7d2261ab1f 100644 --- a/heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts +++ b/heft-plugins/heft-jest-plugin/src/test/JestManagedConfiguration.test.ts @@ -64,11 +64,14 @@ describe('validateManagedJestConfiguration', () => { it.each([ { collectCoverage: true }, { collectCoverage: true, collectCoverageFrom: [] }, + { collectCoverage: true, collectCoverageFrom: ['src/**/*.ts'] }, { collectCoverage: true, coverageProvider: 'babel' }, - { collectCoverage: true, coverageProvider: 'babel', collectCoverageFrom: [] } - ])('requires collection patterns for default or explicit Babel coverage: %j', (config) => { + { collectCoverage: true, coverageProvider: 'babel', collectCoverageFrom: [] }, + { collectCoverage: true, coverageProvider: 'babel', collectCoverageFrom: ['src/**/*.ts'] } + ])('rejects default or explicit Babel coverage regardless of collection patterns: %j', (config) => { expect(() => validateManagedJestConfiguration(config)).toThrow( - 'Managed Jest Babel coverage requires nonempty "collectCoverageFrom" to validate instrumentation completeness.' + 'Managed Jest coverage requires "coverageProvider": "v8". ' + + "Babel coverage, including Jest's default provider, is not supported." ); }); @@ -101,11 +104,12 @@ describe('validateManagedJestConfiguration', () => { { reporters: undefined, bail: undefined, coverageThreshold: undefined, coverageReporters: undefined }, { reporters: [], bail: false }, { reporters: ['default'], bail: 0 }, + { collectCoverage: false }, + { coverageProvider: 'babel' }, { collectCoverage: false, coverageProvider: 'babel', collectCoverageFrom: [] }, - { collectCoverage: true, collectCoverageFrom: ['src/**/*.ts'] }, { collectCoverage: true, - coverageProvider: 'babel', + coverageProvider: 'v8', collectCoverageFrom: ['src/**/*.ts'], coverageThreshold: { global: { lines: 100 } } }, @@ -125,7 +129,7 @@ describe('validateManagedJestConfiguration', () => { const config: Config.InitialOptions = { reporters: ['default'], collectCoverage: true, - coverageProvider: 'babel', + coverageProvider: 'v8', collectCoverageFrom: ['src/**/*.ts'], coverageThreshold: { global: { lines: 100 } }, coverageReporters: ['json', 'lcov'] @@ -141,9 +145,9 @@ describe('validateManagedJestConfiguration', () => { expect(() => validateManagedJestConfiguration(config)).not.toThrow(); expect(config).toEqual(original); - const rejected: Config.InitialOptions = Object.freeze({ ...config, bail: true }); - expect(() => validateManagedJestConfiguration(rejected)).toThrow(/does not support "bail"/); - expect(rejected).toEqual({ ...original, bail: true }); + const rejected: Config.InitialOptions = Object.freeze({ ...config, coverageProvider: 'babel' }); + expect(() => validateManagedJestConfiguration(rejected)).toThrow(/requires "coverageProvider": "v8"/); + expect(rejected).toEqual({ ...original, coverageProvider: 'babel' }); }); });