@d-es-ign/stryker-js-api 9.6.0

package/src/report/reporter.ts

@@ -0,0 +1,47 @@
+import { MutationTestMetricsResult } from 'mutation-testing-metrics';
+
+import { MutantResult, schema } from '../core/index.js';
+
+import { DryRunCompletedEvent } from './dry-run-completed-event.js';
+import { MutationTestingPlanReadyEvent } from './mutation-testing-plan-ready-event.js';
+
+/**
+ * Represents a reporter which can report during or after a Stryker run
+ */
+export interface Reporter {
+  /**
+   * An event emitted when the dry run completed successfully.
+   * @param event The dry run completed event
+   */
+  onDryRunCompleted?(event: DryRunCompletedEvent): void;
+
+  /**
+   * An event emitted when the mutant test plan is calculated.
+   * @param event The mutant test plan ready event
+   */
+  onMutationTestingPlanReady?(event: MutationTestingPlanReadyEvent): void;
+
+  /**
+   * Called when a mutant was tested
+   * @param result The immutable result
+   */
+  onMutantTested?(result: Readonly<MutantResult>): void;
+
+  /**
+   * Called when mutation testing is done
+   * @param report the mutation test result that is valid according to the mutation-testing-report-schema (json schema)
+   * @see https://github.com/stryker-mutator/mutation-testing-elements/blob/master/packages/report-schema/src/mutation-testing-report-schema.json
+   */
+  onMutationTestReportReady?(
+    report: Readonly<schema.MutationTestResult>,
+    metrics: Readonly<MutationTestMetricsResult>,
+  ): void;
+
+  /**
+   * Called when stryker wants to quit
+   * Gives a reporter the ability to finish up any async tasks
+   * Stryker will not close until the promise is either resolved or rejected.
+   * @return a promise which will resolve when the reporter is done reporting
+   */
+  wrapUp?(): Promise<void> | void;
+}

package/src/test-runner/dry-run-result.ts

@@ -0,0 +1,45 @@
+import { MutantCoverage } from '../core/index.js';
+
+import { DryRunStatus } from './dry-run-status.js';
+import { TestResult } from './test-result.js';
+
+export type DryRunResult =
+  | CompleteDryRunResult
+  | ErrorDryRunResult
+  | TimeoutDryRunResult;
+
+export interface CompleteDryRunResult {
+  /**
+   * The individual test results.
+   */
+  tests: TestResult[];
+
+  mutantCoverage?: MutantCoverage;
+
+  /**
+   * The status of the run
+   */
+  status: DryRunStatus.Complete;
+}
+export interface TimeoutDryRunResult {
+  /**
+   * The status of the run
+   */
+  status: DryRunStatus.Timeout;
+  /**
+   * An optional reason for the timeout
+   */
+  reason?: string;
+}
+
+export interface ErrorDryRunResult {
+  /**
+   * The status of the run
+   */
+  status: DryRunStatus.Error;
+
+  /**
+   * If `state` is `error`, this collection should contain the error messages
+   */
+  errorMessage: string;
+}

package/src/test-runner/dry-run-status.ts

@@ -0,0 +1,14 @@
+export enum DryRunStatus {
+  /**
+   * Indicates that a test run is completed with failed or succeeded tests
+   */
+  Complete = 'complete',
+  /**
+   * Indicates that a test run cut off early with an error
+   */
+  Error = 'error',
+  /**
+   * Indicates that a test run timed out
+   */
+  Timeout = 'timeout',
+}

package/src/test-runner/index.ts

@@ -0,0 +1,9 @@
+export * from './test-result.js';
+export * from './test-runner.js';
+export * from './test-status.js';
+export * from './dry-run-result.js';
+export * from './run-options.js';
+export * from './mutant-run-result.js';
+export * from './dry-run-status.js';
+export * from './run-result-helpers.js';
+export * from './test-runner-capabilities.js';

package/src/test-runner/mutant-run-result.ts

@@ -0,0 +1,69 @@
+import { TestStatus } from './test-status.js';
+
+export enum MutantRunStatus {
+  Killed = 'killed',
+  Survived = 'survived',
+  Timeout = 'timeout',
+  Error = 'error',
+}
+
+export type MutantRunResult =
+  | ErrorMutantRunResult
+  | KilledMutantRunResult
+  | SurvivedMutantRunResult
+  | TimeoutMutantRunResult;
+
+export interface TimeoutMutantRunResult {
+  status: MutantRunStatus.Timeout;
+  /**
+   * An optional reason for the timeout
+   */
+  reason?: string;
+}
+
+export interface KilledMutantRunResult {
+  status: MutantRunStatus.Killed;
+  /**
+   * An array with the ids of the tests that killed this mutant
+   */
+  killedBy: string[];
+  /**
+   * The failure message that was reported by first the test
+   */
+  failureMessage: string;
+  /**
+   * The number of total tests ran in this test run.
+   */
+  nrOfTests: number;
+
+  /**
+   * Optional per-test timing details for tests executed in this mutant run.
+   */
+  executedTests?: MutantRunExecutedTest[];
+}
+
+export interface SurvivedMutantRunResult {
+  status: MutantRunStatus.Survived;
+  /**
+   * The number of total tests ran in this test run.
+   */
+  nrOfTests: number;
+
+  /**
+   * Optional per-test timing details for tests executed in this mutant run.
+   */
+  executedTests?: MutantRunExecutedTest[];
+}
+
+export interface ErrorMutantRunResult {
+  status: MutantRunStatus.Error;
+  errorMessage: string;
+}
+
+export interface MutantRunExecutedTest {
+  id: string;
+  name: string;
+  status: TestStatus;
+  timeSpentMs: number;
+  fileName?: string;
+}

package/src/test-runner/run-options.ts

@@ -0,0 +1,53 @@
+import { Mutant, CoverageAnalysis } from '../core/index.js';
+
+export interface RunOptions {
+  /**
+   * The amount of time (in milliseconds) the TestRunner has to complete the test run before a timeout occurs.
+   */
+  timeout: number;
+  /**
+   * Filled from disableBail in config
+   */
+  disableBail: boolean;
+}
+
+export interface DryRunOptions extends RunOptions {
+  /**
+   * Indicates whether or not mutant coverage should be collected.
+   */
+  coverageAnalysis: CoverageAnalysis;
+  /**
+   * Files with mutants to run tests for.
+   */
+  files?: string[];
+  /**
+   * If provided, only tests from these files will be executed.
+   */
+  testFiles?: string[];
+}
+
+export type MutantActivation = 'runtime' | 'static';
+
+export interface MutantRunOptions extends RunOptions {
+  testFilter?: string[];
+  hitLimit?: number;
+  activeMutant: Mutant;
+  /**
+   * The name of file inside the sandbox in which the mutant resides
+   */
+  sandboxFileName: string;
+  /**
+   * Determine when to active the mutant.
+   * - 'runtime'. The test environment should first load all tests and sut files before activating the mutant. Mutant is only active during runtime.
+   * - 'static'. The test environment should load _while the mutant is active_. Mutant may be active during the entire lifetime of the process.
+   * See https://github.com/stryker-mutator/stryker-js/issues/3442 for more details
+   */
+  mutantActivation: MutantActivation;
+  /**
+   * Determines whether or not the test environment should be reloaded.
+   * This is necessary when testing static mutants, where the mutant is only executed when the test environment is loaded.
+   * A test runner might be unable to reload the test environment, i.e. when the files were loaded via `import` in nodejs.
+   * In which case the test runner should report `reloadEnvironment: false` in it's capabilities.
+   */
+  reloadEnvironment: boolean;
+}

package/src/test-runner/run-result-helpers.ts

@@ -0,0 +1,90 @@
+import { TestStatus } from './test-status.js';
+import { DryRunResult, TimeoutDryRunResult } from './dry-run-result.js';
+import { MutantRunResult, MutantRunStatus } from './mutant-run-result.js';
+import { DryRunStatus } from './dry-run-status.js';
+import { FailedTestResult } from './test-result.js';
+
+export function determineHitLimitReached(
+  hitCount: number | undefined,
+  hitLimit: number | undefined,
+): TimeoutDryRunResult | undefined {
+  if (hitCount !== undefined && hitLimit !== undefined && hitCount > hitLimit) {
+    return {
+      status: DryRunStatus.Timeout,
+      reason: `Hit limit reached (${hitCount}/${hitLimit})`,
+    };
+  }
+  return;
+}
+
+export function toMutantRunResult(
+  dryRunResult: DryRunResult,
+  reportAllKillers = true,
+  includeExecutedTests = process.env.STRYKER_MUTATION_TEST_TIMINGS === '1',
+): MutantRunResult {
+  switch (dryRunResult.status) {
+    case DryRunStatus.Complete: {
+      const failedTests = dryRunResult.tests.filter<FailedTestResult>(
+        (test): test is FailedTestResult => test.status === TestStatus.Failed,
+      );
+      const nrOfTests = dryRunResult.tests.filter(
+        (test) => test.status !== TestStatus.Skipped,
+      ).length;
+      const executedTests = includeExecutedTests
+        ? dryRunResult.tests
+            .filter((test) => test.status !== TestStatus.Skipped)
+            .map((test) => ({
+              id: test.id,
+              name: test.name,
+              status: test.status,
+              timeSpentMs: test.timeSpentMs,
+              fileName: test.fileName,
+            }))
+        : undefined;
+      const maxExecutedTests = Number.parseInt(
+        process.env.STRYKER_MUTATION_TEST_TIMINGS_MAX_TESTS ?? '',
+        10,
+      );
+      const boundedExecutedTests =
+        executedTests &&
+        Number.isFinite(maxExecutedTests) &&
+        maxExecutedTests > 0
+          ? executedTests.slice(0, maxExecutedTests)
+          : executedTests;
+
+      if (failedTests.length > 0) {
+        const killedResult = {
+          status: MutantRunStatus.Killed as const,
+          failureMessage: failedTests[0].failureMessage,
+          killedBy: reportAllKillers
+            ? failedTests.map<string>((test) => test.id)
+            : [failedTests[0].id],
+          nrOfTests,
+        };
+
+        return boundedExecutedTests
+          ? { ...killedResult, executedTests: boundedExecutedTests }
+          : killedResult;
+      } else {
+        const survivedResult = {
+          status: MutantRunStatus.Survived as const,
+          nrOfTests,
+        };
+
+        return boundedExecutedTests
+          ? { ...survivedResult, executedTests: boundedExecutedTests }
+          : survivedResult;
+      }
+    }
+    case DryRunStatus.Error:
+      return {
+        status: MutantRunStatus.Error,
+        errorMessage: dryRunResult.errorMessage,
+      };
+    case DryRunStatus.Timeout:
+      return {
+        status: MutantRunStatus.Timeout,
+        reason: dryRunResult.reason,
+      };
+  }
+}

package/src/test-runner/test-result.ts

@@ -0,0 +1,49 @@
+import { Position } from '../core/index.js';
+
+import { TestStatus } from './test-status.js';
+
+/**
+ * Indicates the result of a single test
+ */
+export interface BaseTestResult {
+  /**
+   * The id of this test. Can be the name if the test runner doesn't have an 'id'
+   */
+  id: string;
+  /**
+   * The full human readable name of the test
+   */
+  name: string;
+  /**
+   * The time it took to run the test
+   */
+  timeSpentMs: number;
+
+  /**
+   * The file where this test was defined in (if known)
+   */
+  fileName?: string;
+
+  /**
+   * The position of the test (if known)
+   */
+  startPosition?: Position;
+}
+
+export interface FailedTestResult extends BaseTestResult {
+  status: TestStatus.Failed;
+  failureMessage: string;
+}
+
+export interface SkippedTestResult extends BaseTestResult {
+  status: TestStatus.Skipped;
+}
+
+export interface SuccessTestResult extends BaseTestResult {
+  status: TestStatus.Success;
+}
+
+export type TestResult =
+  | FailedTestResult
+  | SkippedTestResult
+  | SuccessTestResult;

package/src/test-runner/test-runner-capabilities.ts

@@ -0,0 +1,11 @@
+/**
+ * Represents the capabilities of a test runner.
+ */
+export interface TestRunnerCapabilities {
+  /**
+   * When true, the test runner is capable of reloading the test environment. Otherwise false.
+   * Reloading means creating a new nodejs process, or reloading the browser.
+   * When true, the test runner should reload the test environment when `reloadEnvironment` is present in the run options.
+   */
+  reloadEnvironment: boolean;
+}

package/src/test-runner/test-runner.ts

@@ -0,0 +1,12 @@
+import { DryRunOptions, MutantRunOptions } from './run-options.js';
+import { DryRunResult } from './dry-run-result.js';
+import { MutantRunResult } from './mutant-run-result.js';
+import { TestRunnerCapabilities } from './test-runner-capabilities.js';
+
+export interface TestRunner {
+  capabilities(): Promise<TestRunnerCapabilities> | TestRunnerCapabilities;
+  init?(): Promise<void>;
+  dryRun(options: DryRunOptions): Promise<DryRunResult>;
+  mutantRun(options: MutantRunOptions): Promise<MutantRunResult>;
+  dispose?(): Promise<void>;
+}

package/src/test-runner/test-status.ts

@@ -0,0 +1,17 @@
+/**
+ * Indicates what the result of a single test was.
+ */
+export enum TestStatus {
+  /**
+   * The test succeeded
+   */
+  Success,
+  /**
+   * The test failed
+   */
+  Failed,
+  /**
+   * The test was skipped (not executed)
+   */
+  Skipped,
+}