Package com.arc_e_tect.gradle.mirage.report

Class MirageApiReportWriter

java.lang.Object
com.arc_e_tect.gradle.mirage.report.MirageApiReportWriter
public class MirageApiReportWriter extends Object
Writes the AsciiDoc mirage API report: every OpenAPI operation that has no matching @RestController implementation.

Every report opens with a preamble explaining what a mirage API is, loaded from the "mirage-api-preamble.adoc" classpath resource so that explanatory text can be revised without touching this class. When scanMocks was true for the run, a second preamble - "mirage-api-stub-scanning-preamble.adoc" - explaining what the stub scan can and cannot match, shadow stubs, and multiple stub files covering one endpoint, is written right after it, since every Stubbed figure the rest of the report shows depends on understanding those limits. Whenever contractHistory is non-empty - i.e. whenever the == Progress Over Time section itself is written - a third preamble, "mirage-api-removed-preamble.adoc", explains why an endpoint becomes removed (postponed, obsolete, or replaced after an error in its original definition), right before that section.

  • Constructor Summary

    Constructors
    Constructor
    Description
    MirageApiReportWriter()
    Creates a new MirageApiReportWriter.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, String systemUnderTestVersion)
    Writes the report to outputFile, creating its parent directory if necessary.
    void
    write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, String systemUnderTestVersion, List<String> warnings, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory)
    Writes the report to outputFile, creating its parent directory if necessary.
    void
    write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, String systemUnderTestVersion, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory)
    Writes the report to outputFile, creating its parent directory if necessary.
    void
    write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, List<ExcludedMirage> excludedMirages, String systemUnderTestVersion, List<String> warnings, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory)
    Writes the report to outputFile, creating its parent directory if necessary.
    void
    write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, List<ExcludedMirage> excludedMirages, String systemUnderTestVersion, List<String> warnings, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory, boolean scanMocks)
    Writes the report to outputFile, creating its parent directory if necessary.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • MirageApiReportWriter

      public MirageApiReportWriter()
      Creates a new MirageApiReportWriter.

  • Method Details

    • write

      public void write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, String systemUnderTestVersion) throws IOException
      Writes the report to outputFile, creating its parent directory if necessary. Equivalent to calling write(File, int, List, String, List, Map) with no warnings and an empty contract history.
      Parameters:
      outputFile - target AsciiDoc file
      totalDescribedCount - total number of endpoints described by the OpenAPI documentation
      mirages - the described endpoints not implemented by any controller
      systemUnderTestVersion - version of the system under test that was scanned
      Throws:
      IOException - if the output file cannot be written

    • write

      public void write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, String systemUnderTestVersion, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory) throws IOException
      Writes the report to outputFile, creating its parent directory if necessary. Equivalent to calling write(File, int, List, String, List, Map) with no warnings.
      Parameters:
      outputFile - target AsciiDoc file
      totalDescribedCount - total number of endpoints described by the OpenAPI documentation
      mirages - the described endpoints with no matching @RestController implementation
      systemUnderTestVersion - version of the system under test that was scanned
      contractHistory - contract progress history to render as a == Progress Over Time section, keyed by fingerprint; when empty, no such section is written
      Throws:
      IOException - if the output file cannot be written

    • write

      public void write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, String systemUnderTestVersion, List<String> warnings, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory) throws IOException
      Writes the report to outputFile, creating its parent directory if necessary. Equivalent to calling write(File, int, List, List, String, List, Map) with an empty excluded-mirages list.
      Parameters:
      outputFile - target AsciiDoc file
      totalDescribedCount - total number of endpoints described by the OpenAPI documentation
      mirages - the described endpoints with no matching @RestController implementation
      systemUnderTestVersion - version of the system under test that was scanned
      warnings - non-fatal configuration gaps to render as a WARNING admonition right after the report header - e.g. a configured rootDocument or controllerDirs entry that doesn't exist yet; when empty, no such admonition is written
      contractHistory - contract progress history to render as a == Progress Over Time section, keyed by fingerprint; when empty, no such section is written
      Throws:
      IOException - if the output file cannot be written

    • write

      public void write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, List<ExcludedMirage> excludedMirages, String systemUnderTestVersion, List<String> warnings, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory) throws IOException
      Writes the report to outputFile, creating its parent directory if necessary.
      Parameters:
      outputFile - target AsciiDoc file
      totalDescribedCount - total number of endpoints described by the OpenAPI documentation
      mirages - the described endpoints with no matching @RestController implementation, excluding any matched by a configured exclusion rule - these are the endpoints that can fail failOnMirage
      excludedMirages - described-but-unimplemented endpoints matched by a configured exclusion rule, paired with their current-run WireMock stub status; rendered under == Excluded Mirage APIs instead of == Mirage APIs, never fails the build, and never appears in contract history - when empty, no such section is written
      systemUnderTestVersion - version of the system under test that was scanned
      warnings - non-fatal configuration gaps to render as a WARNING admonition right after the report header - e.g. a configured rootDocument or controllerDirs entry that doesn't exist yet; when empty, no such admonition is written
      contractHistory - contract progress history to render as a == Progress Over Time section, keyed by fingerprint; when empty, no such section is written
      Throws:
      IOException - if the output file cannot be written

    • write

      public void write(File outputFile, int totalDescribedCount, List<com.arc_e_tect.gradle.detector.core.openapi.DescribedEndpoint> mirages, List<ExcludedMirage> excludedMirages, String systemUnderTestVersion, List<String> warnings, Map<String,com.arc_e_tect.gradle.detector.core.progress.ContractProgressRecord> contractHistory, boolean scanMocks) throws IOException
      Writes the report to outputFile, creating its parent directory if necessary.
      Parameters:
      outputFile - target AsciiDoc file
      totalDescribedCount - total number of endpoints described by the OpenAPI documentation
      mirages - the described endpoints with no matching @RestController implementation, excluding any matched by a configured exclusion rule - these are the endpoints that can fail failOnMirage
      excludedMirages - described-but-unimplemented endpoints matched by a configured exclusion rule, paired with their current-run WireMock stub status; rendered under == Excluded Mirage APIs instead of == Mirage APIs, never fails the build, and never appears in contract history - when empty, no such section is written
      systemUnderTestVersion - version of the system under test that was scanned
      warnings - non-fatal configuration gaps to render as a WARNING admonition right after the report header - e.g. a configured rootDocument or controllerDirs entry that doesn't exist yet; when empty, no such admonition is written
      contractHistory - contract progress history to render as a == Progress Over Time section, keyed by fingerprint; when empty, no such section is written
      scanMocks - whether stub mapping/Java DSL scanning was enabled for this run - when true, an additional preamble explaining what the stub scan can and cannot match, shadow stubs, and multiple stub files covering one endpoint is written right after the main preamble
      Throws:
      IOException - if the output file cannot be written