{"id":11372,"library":"mutation-testing-metrics","title":"Mutation Testing Metrics Utilities","description":"The `mutation-testing-metrics` package provides a set of utility functions designed to calculate and aggregate mutation testing metrics from mutation test reports. Currently at version 3.7.3, it is an actively maintained component within the Stryker Mutator ecosystem, with a release cadence that appears to be every few months, addressing bug fixes and minor feature enhancements. Its key differentiators include the ability to programmatically process `MutationTestResult` objects, perform detailed metric calculations, and aggregate multiple module-level reports into a single, consolidated view. This enables developers and CI/CD pipelines to deeply analyze the effectiveness of their test suites, going beyond simple code coverage by evaluating how well tests detect intentionally introduced faults (mutants). It is built with TypeScript, providing strong type guarantees for its API.","status":"active","version":"3.7.3","language":"javascript","source_language":"en","source_url":"https://github.com/stryker-mutator/mutation-testing-elements","tags":["javascript","typescript"],"install":[{"cmd":"npm install mutation-testing-metrics","lang":"bash","label":"npm"},{"cmd":"yarn add mutation-testing-metrics","lang":"bash","label":"yarn"},{"cmd":"pnpm add mutation-testing-metrics","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the required TypeScript types and defines the expected JSON data structure for mutation test reports, which are the primary input for all metric calculations and aggregations.","package":"mutation-testing-report-schema","optional":false}],"imports":[{"note":"ESM named import is the modern approach. For CommonJS, use destructuring from `require()`.","wrong":"const calculateMutationTestMetrics = require('mutation-testing-metrics').calculateMutationTestMetrics;","symbol":"calculateMutationTestMetrics","correct":"import { calculateMutationTestMetrics } from 'mutation-testing-metrics';"},{"note":"Type-only import for the structure returned by metric calculation functions.","symbol":"MetricsResult","correct":"import type { MetricsResult } from 'mutation-testing-metrics';"},{"note":"Available as a named export in both ESM and CJS contexts. The README provides a CJS example using destructuring from `require()` for this function.","wrong":"const aggregateResultsByModule = require('mutation-testing-metrics');\n// or\nconst { default: aggregateResultsByModule } = require('mutation-testing-metrics');","symbol":"aggregateResultsByModule","correct":"import { aggregateResultsByModule } from 'mutation-testing-metrics';"}],"quickstart":{"code":"import { MetricsResult, calculateMutationTestMetrics } from 'mutation-testing-metrics';\nimport type { MutationTestResult } from 'mutation-testing-report-schema';\n\n// In a real scenario, mutationTestReport would be loaded from a file or generated\nconst mutationTestReport: MutationTestResult = {\n  $schema: 'https://raw.githubusercontent.com/stryker-mutator/mutation-testing-elements/master/packages/report-schema/src/mutation-testing-report-schema.json',\n  schemaVersion: '1.4',\n  thresholds: {\n    high: 80,\n    low: 60\n  },\n  files: {\n    'src/calculator.js': {\n      language: 'javascript',\n      mutants: [\n        {\n          id: '1',\n          mutatorName: 'BinaryExpression',\n          replacement: 'a - b',\n          location: { start: { line: 1, column: 15 }, end: { line: 1, column: 20 } },\n          status: 'Survived'\n        },\n        {\n          id: '2',\n          mutatorName: 'BinaryExpression',\n          replacement: 'a / b',\n          location: { start: { line: 1, column: 15 }, end: { line: 1, column: 20 } },\n          status: 'Killed'\n        }\n      ],\n      source: 'const add = (a, b) => a + b;'\n    },\n    'src/subtract.js': {\n      language: 'javascript',\n      mutants: [\n        {\n          id: '3',\n          mutatorName: 'BinaryExpression',\n          replacement: 'a + b',\n          location: { start: { line: 1, column: 18 }, end: { line: 1, column: 23 } },\n          status: 'NoCoverage'\n        }\n      ],\n      source: 'const subtract = (a, b) => a - b;'\n    }\n  }\n};\n\nconst result: MetricsResult = calculateMutationTestMetrics(mutationTestReport);\n\nconsole.log('--- Mutation Test Metrics ---');\nconsole.log('Total mutants:', result.metrics.totalMutants);\nconsole.log('Killed mutants:', result.metrics.killed);\nconsole.log('Survived mutants:', result.metrics.survived);\nconsole.log('No Coverage mutants:', result.metrics.noCoverage);\nconsole.log('Mutation score:', result.metrics.mutationScore.toFixed(2) + '%');","lang":"typescript","description":"This example demonstrates how to use `calculateMutationTestMetrics` to process a `MutationTestResult` object and output key metrics like total mutants, killed, survived, and the overall mutation score."},"warnings":[{"fix":"Update to `mutation-testing-metrics` version 3.7.1 or higher: `npm install mutation-testing-metrics@latest`","message":"Older versions of `mutation-testing-metrics` might encounter compatibility issues with Node.js 20+. A fix for Node 20 compatibility was released in version 3.7.1, so it's recommended to upgrade if using newer Node.js runtimes.","severity":"gotcha","affected_versions":"<3.7.1"},{"fix":"Always ensure your mutation test report JSON adheres strictly to the `mutation-testing-report-schema`. Consult the schema documentation for details.","message":"The package relies heavily on the `mutation-testing-report-schema` for its input data structure. Any deviation from this schema will lead to incorrect metric calculations or runtime errors.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"For best compatibility, it's often advisable to keep `mutation-testing-metrics` aligned with other `stryker-mutator` packages you are using, especially `mutation-testing-elements` and `mutation-testing-report-schema`.","message":"This package is part of the larger `stryker-mutator` monorepo. While it aims for semantic versioning, its major/minor versions are often synchronized with `mutation-testing-elements` and not strictly with the underlying schema, which can sometimes lead to unexpected versioning behavior if only specific sub-packages are updated.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `npm install mutation-testing-metrics` or `yarn add mutation-testing-metrics`. Verify the import path is exactly `mutation-testing-metrics`.","cause":"The package is not installed, or the import path is incorrect, or TypeScript cannot find the type definitions.","error":"Cannot find module 'mutation-testing-metrics' or its corresponding type declarations."},{"fix":"For CommonJS, use destructuring: `const { calculateMutationTestMetrics } = require('mutation-testing-metrics');`","cause":"This typically occurs in a CommonJS environment when trying to access a named export without destructuring it from the `require()` call.","error":"TypeError: calculateMutationTestMetrics is not a function"},{"fix":"Review the `MutationTestResult` schema and ensure your input object conforms to it, including all required properties like `schemaVersion`, `thresholds`, and `files` with their correct internal structures.","cause":"The input object provided to functions like `calculateMutationTestMetrics` does not match the expected structure defined by `mutation-testing-report-schema`.","error":"Argument of type '{ ... }' is not assignable to parameter of type 'MutationTestResult'."}],"ecosystem":"npm"}