Class RealtimeReporter

java.lang.Object
com.shaft.tools.io.internal.RealtimeReporter
public class RealtimeReporter extends Object
Real-time test execution dashboard server for SHAFT_ENGINE.

Hosts a local HTTP server that serves a Kanban-style dashboard reflecting live test execution state. The dashboard is automatically opened in the user's default browser at the start of the test run.

The server is only launched when all of the following conditions are met:

  • The reporting.realtimeReport.enabled property is true.
  • Execution is not inside a CI/CD environment.

Only one instance of the server runs at a time. Starting a new test run tears down the previous server and starts a fresh one.

  • Method Details

    • initialize

      public static void initialize(String runSuiteName)
      Initialises the real-time report for a new test run.

      If the feature is disabled or the execution is in CI, this method is a no-op.

      Parameters:
      runSuiteName - the name to display as the run title on the dashboard

    • onTestsPlanned

      public static void onTestsPlanned(List<RealtimeReporter.TestCard> cards)
      Registers all tests that are planned to run in the current suite. These are placed in the "Todo" swim lane.
      Parameters:
      cards - list of RealtimeReporter.TestCard objects representing planned tests

    • onTestStarted

      public static void onTestStarted(String testId)
      Moves a test from the "Todo" lane to the "In Progress" lane.
      Parameters:
      testId - the unique identifier of the test (see buildTestId(String, String))

    • onTestFinished

      public static void onTestFinished(String testId, RealtimeReporter.TestStatus status, Throwable throwable)
      Moves a test from the "In Progress" lane to the "Done" lane with the given status.
      Parameters:
      testId - the unique identifier of the test
      status - the final status (PASSED / FAILED / BROKEN / SKIPPED)
      throwable - the failure throwable, or null for passing/skipped tests

    • appendConsoleLog

      public static void appendConsoleLog(String testId, String message)
      Appends a console log line to the buffer for the currently active test. The line is forwarded to all SSE clients watching the test details page.
      Parameters:
      testId - the unique identifier of the test (may be null if no test is active)
      message - the log line to append (ANSI codes are stripped before storage)

    • appendStep

      public static void appendStep(String testId, String stepName, String stepStatus)
      Appends a step entry to the test card.
      Parameters:
      testId - the unique identifier of the test
      stepName - the human-readable step description
      stepStatus - the step status string (e.g. "PASSED", "FAILED")

    • appendAttachment

      public static void appendAttachment(String testId, String attachmentType, String attachmentName, String contentType, byte[] content)
      Appends an attachment (screenshot, API response, etc.) to a test card. The raw bytes are stored in memory and served via /api/attachment/<id>.
      Parameters:
      testId - the unique identifier of the test
      attachmentType - type label (e.g. "Screenshot", "API Response Body")
      attachmentName - human-readable file name
      contentType - MIME type (e.g. "image/png", "text/json")
      content - the raw bytes of the attachment

    • onExecutionFinished

      public static void onExecutionFinished()
      Called when the execution finishes. Closes the server if the Allure auto-open flag is enabled; otherwise the server remains running so the user can review the final state.

    • stopServer

      public static void stopServer()
      Forcefully stops the HTTP server and clears all state. Safe to call even if the server is not running.

    • isRunning

      public static boolean isRunning()
      Returns true if the server is currently running and serving requests.

    • shouldLaunch

      public static boolean shouldLaunch()
      Determines whether the real-time report should be launched. The report launches when the flag is enabled, not running in CI, and not executing locally in headless mode.
      Returns:
      true when launch conditions are satisfied

    • setCurrentTestId

      public static void setCurrentTestId(String testId)
      Sets the current test identifier for the active execution thread. This allows framework-agnostic forwarding of logs/steps/attachments.
      Parameters:
      testId - the test id generated via buildTestId(String, String)

    • getCurrentTestId

      public static String getCurrentTestId()
      Returns the current test identifier bound to the active thread.
      Returns:
      current test id or null when none is bound

    • clearCurrentTestId

      public static void clearCurrentTestId()
      Clears the current thread-bound test identifier.

    • isRunningInCI

      public static boolean isRunningInCI()
      Detects common CI/CD environment variables.
      Returns:
      true if any known CI marker is present in the environment

    • buildTestId

      public static String buildTestId(String className, String methodName)
      Builds a stable unique identifier for a test from its fully-qualified class name and method name. Safe to call from both TestNG and JUnit listener hooks.
      Parameters:
      className - fully-qualified class name (e.g. com.example.MyTest)
      methodName - the test method name
      Returns:
      identifier string in the form className#methodName

    • classNameToFilePath

      public static String classNameToFilePath(String qualifiedClassName)
      Converts a fully-qualified class name into a relative source-file path.
      Parameters:
      qualifiedClassName - e.g. com.example.tests.LoginTest
      Returns:
      e.g. src/test/java/com/example/tests/LoginTest.java