testResultsFormatter.ts

/*
 * Copyright 2026, Salesforce, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import os from 'node:os';
import { StandardColors } from '@salesforce/sf-plugins-core/StandardColors';
import { Ux } from '@salesforce/sf-plugins-core/Ux';
import ansis from 'ansis';
import {
  CodeCoverage,
  CodeCoverageWarnings,
  DeployResult,
  Failures,
  MetadataApiDeployStatus,
  RunTestResult,
  Successes,
} from '@salesforce/source-deploy-retrieve';
import { ensureArray } from '@salesforce/kit';
import { TestLevel, Verbosity } from '../utils/types.js';
import { tableHeader, error, success, check } from '../utils/output.js';
import { coverageOutput } from '../utils/coverage.js';
import { isCI } from '../utils/deployStages.js';

const ux = new Ux();

export class TestResultsFormatter {
  public skipVerboseTestReportOnCI: boolean;
  public testLevel: TestLevel | undefined;
  public verbosity: Verbosity;

  public constructor(
    protected result: DeployResult,
    protected flags: Partial<{
      'test-level': TestLevel;
      verbose: boolean;
    }>,
    skipVerboseTestReportOnCI = true
  ) {
    this.skipVerboseTestReportOnCI = skipVerboseTestReportOnCI;
    this.testLevel = flags['test-level'];
    this.verbosity = this.determineVerbosity();
  }

  public displayTestResults(): void {
    if (this.testLevel === TestLevel.NoTestRun || !this.result.response.runTestsEnabled) {
      ux.log();
      return;
    }

    // some commands like `project deploy start` will report these failures as they happen via MSO:
    // https://github.com/salesforcecli/plugin-deploy-retrieve/pull/1215
    //
    // commands can enable/disable `skipVerboseTestReportOnCI` when instantiating the formatter to skip these
    const skipVerboseTestReport = isCI() && this.skipVerboseTestReportOnCI;

    if (!skipVerboseTestReport) {
      displayVerboseTestFailures(this.result.response);
    }

    if (this.verbosity === 'verbose') {
      displayVerboseTestSuccesses(this.result.response.details.runTestResult?.successes);
      displayVerboseTestCoverage(this.result.response.details.runTestResult?.codeCoverage);
    }

    ux.log();
    ux.log(tableHeader('Test Results Summary'));
    ux.log(`Passing: ${this.result.response.numberTestsCompleted ?? 0}`);
    ux.log(`Failing: ${this.result.response.numberTestErrors ?? 0}`);
    ux.log(`Total: ${this.result.response.numberTestsTotal ?? 0}`);
    const time = this.result.response.details.runTestResult?.totalTime ?? 0;
    if (time) ux.log(`Time: ${time}`);
    // I think the type might be wrong in SDR
    ensureArray(this.result.response.details.runTestResult?.codeCoverageWarnings).map(
      (warning: CodeCoverageWarnings & { name?: string }) =>
        ux.warn(`${warning.name ? `${warning.name} - ` : ''}${warning.message}`)
    );
  }

  public determineVerbosity(): Verbosity {
    if (this.flags.verbose) return 'verbose';
    return 'normal';
  }
}

const displayVerboseTestSuccesses = (resultSuccesses: RunTestResult['successes']): void => {
  const successes = ensureArray(resultSuccesses).sort(testResultSort);
  if (successes.length > 0) {
    ux.log();
    ux.log(success(`Test Success [${successes.length}]`));
    for (const test of successes) {
      const testName = ansis.underline(`${test.name}.${test.methodName} (${test.time}ms)`);
      ux.log(`${check} ${testName}`);
    }
  }
};

/** display the Test failures if there are any testErrors in the mdapi deploy response */
const displayVerboseTestFailures = (response: MetadataApiDeployStatus): void => {
  if (!response.numberTestErrors) return;
  const failures = ensureArray(response.details.runTestResult?.failures).sort(testResultSort);
  const failureCount = response.details.runTestResult?.numFailures;
  ux.log();
  ux.log(error(`Test Failures [${failureCount ?? 0}]`));
  for (const test of failures) {
    const testName = ansis.underline(`${test.name}.${test.methodName}`);
    ux.log(`• ${testName}`);
    ux.log(`  ${StandardColors.info('message')}: ${test.message}`);
    if (test.stackTrace) {
      const stackTrace = test.stackTrace.replace(/\n/g, `${os.EOL}    `);
      ux.log(`  ${StandardColors.info('stacktrace')}: ${os.EOL}    ${stackTrace}`);
    }
    ux.log();
  }
};

/**
 * Display the table if there is at least one coverage item in the result
 */
const displayVerboseTestCoverage = (coverage?: CodeCoverage | CodeCoverage[]): void => {
  const codeCoverage = ensureArray(coverage);
  if (codeCoverage.length) {
    ux.log();
    ux.table({
      data: codeCoverage.sort(coverageSort).map(coverageOutput),
      columns: [
        'name',
        { key: 'coveragePercent', name: '% Covered' },
        { key: 'linesNotCovered', name: 'Uncovered Lines' },
      ],
      title: tableHeader('Apex Code Coverage'),
    });
  }
};

export const testResultSort = <T extends Successes | Failures>(a: T, b: T): number =>
  a.methodName === b.methodName ? a.name.localeCompare(b.name) : a.methodName.localeCompare(b.methodName);

const coverageSort = (a: CodeCoverage, b: CodeCoverage): number =>
  a.name.toUpperCase() > b.name.toUpperCase() ? 1 : -1;