Interface TestResultFormatter

All Known Implementing Classes:
HumanTestFormatter, JsonTestFormatter, JUnitXmlFormatter, TerseTestFormatter
interface TestResultFormatter
Interface for formatting test results in different output formats.

Implementations handle terse, human-readable, JSON, and JUnit XML formats. Each format is optimized for a different audience:

  • Terse: Scripting and CI pass/fail checks
  • Human: Terminal output with visual hierarchy
  • JSON: AI/LLM and programmatic access
  • JUnit XML: CI/CD tools (Jenkins, GitHub Actions, GitLab)

All formatters must clearly communicate the test type (assert-based, simple blackbox, parameterized) to help users understand how tests are validated.

  • Method Details

    • reportDiscovery

      void reportDiscovery(List<DiscoveredTest> tests, PrintStream out)
      Report the discovery of tests before execution begins.

      The discovery report should include:

      • Test type breakdown (assert-based vs blackbox vs parameterized)
      • Total test case count (including parameterized cases)
      • Group information if applicable
      Parameters:
      tests - The discovered tests with metadata
      out - The output stream

    • reportExecutionStart

      void reportExecutionStart(int testCount, PrintStream out)
      Report that test execution is starting. Some formatters may output a progress message here.
      Parameters:
      testCount - The number of tests to execute
      out - The output stream

    • reportResults

      void reportResults(List<TestResult> results, PrintStream out)
      Report all test results after execution completes.
      Parameters:
      results - The test results
      out - The output stream

    • reportTestList

      void reportTestList(List<DiscoveredTest> tests, PrintStream out)
      Report list of discovered tests for list-only mode (-tL).

      Unlike reportDiscovery(List, PrintStream), this is the final output when using -tL. It should include complete test information without expecting execution to follow.

      Parameters:
      tests - The discovered tests with metadata
      out - The output stream

    • writeResultsToFile

      default void writeResultsToFile(List<TestResult> results, Path outputFile)
      Write test results to a file instead of stdout.

      This is used when -tC is combined with machine formats (-t2 or -t3) to produce valid, separate output files for test results and coverage data.

      Only JSON and JUnit XML formatters support file output. Human-readable formats throw UnsupportedOperationException.

      Parameters:
      results - The test results to write
      outputFile - The file path to write to
      Throws:
      UnsupportedOperationException - if the formatter doesn't support file output

    • create

      static TestResultFormatter create(TestOutputFormat format, boolean verbose)
      Create a formatter for the specified output format.
      Parameters:
      format - The output format
      verbose - Whether verbose output is enabled
      Returns:
      The appropriate formatter