import { tags } from "typia";

import { AutoBeEventBase } from "./base/AutoBeEventBase";
import { AutoBeProgressEventBase } from "./base/AutoBeProgressEventBase";

/**
 * Event fired when the Realize agent completes the execution of an individual
 * E2E test function during the comprehensive test suite validation.
 *
 * This event provides real-time visibility into the progress of E2E test
 * execution, capturing the results of each individual test operation as it
 * completes. Each event represents the validation of a specific API endpoint or
 * business scenario through the execution of Test agent-generated E2E test
 * functions against the fully implemented backend application.
 *
 * The operation events enable stakeholders to monitor test execution progress,
 * identify successful validations, and detect any failures or errors that occur
 * during the comprehensive validation process. This granular visibility into
 * test results ensures transparency and enables rapid identification of
 * implementation issues that need attention.
 *
 * @author Samchon
 */
export interface AutoBeRealizeTestOperationEvent
  extends AutoBeEventBase<"realizeTestOperation">, AutoBeProgressEventBase {
  /**
   * Name of the E2E test function that was executed.
   *
   * Specifies the identifier of the test function that completed execution,
   * typically corresponding to the function name generated by the Test agent.
   * This name provides direct traceability between test results and the
   * specific business scenarios or API endpoints being validated.
   *
   * The test function name serves as a unique identifier for correlating test
   * results with the original test scenarios, enabling stakeholders to
   * understand which specific functionality was validated and whether the
   * implementation correctly fulfills the intended business requirements.
   */
  name: string;

  /**
   * File system location of the executed test function.
   *
   * Specifies the relative or absolute path to the test file that contains the
   * executed function. This location information enables direct navigation to
   * the test source code for detailed analysis, debugging, or modification
   * purposes.
   *
   * The file location provides essential context for understanding the test
   * organization and enables developers to quickly locate and examine the
   * specific test implementation when investigating results or making
   * modifications to test scenarios.
   */
  location: string;

  /**
   * Return value or result data from the test function execution.
   *
   * Contains the actual value returned by the test function upon successful
   * completion. This could be test result data, API response objects, or any
   * other value that the test function produces as part of its validation
   * logic. The value provides insight into the test execution outcome and any
   * data generated during the validation process.
   *
   * For successful test executions, this value represents the expected result
   * that demonstrates correct implementation behavior. The return value can be
   * analyzed to verify that API responses match expected formats and that
   * business logic produces correct outcomes under test conditions.
   */
  value: unknown;

  /**
   * Error information if the test function execution failed.
   *
   * Contains detailed error information when the test function encounters
   * exceptions, assertion failures, or other error conditions during execution.
   * When null, it indicates that the test completed successfully without
   * errors. When present, the error provides diagnostic information for
   * understanding implementation issues or test failures.
   *
   * Error information is crucial for identifying implementation defects, API
   * contract violations, or business logic errors that prevent the backend
   * application from meeting its requirements. The error details enable
   * developers to pinpoint specific issues and implement necessary corrections
   * to achieve full compliance with test scenarios.
   */
  error: null | unknown;

  /**
   * Timestamp when this specific test operation completed execution.
   *
   * Records the exact moment when this individual test function finished
   * execution, regardless of whether it succeeded or failed. This timestamp
   * enables performance analysis of individual test operations and provides
   * audit trail information for the overall test execution process.
   *
   * The completion timestamp is valuable for identifying slow-performing test
   * operations, analyzing test execution patterns, and understanding the
   * temporal distribution of test results during the comprehensive validation
   * process.
   */
  completed_at: string & tags.Format<"date-time">;

  /**
   * Iteration number of the requirements analysis this test operation
   * validates.
   *
   * Indicates which version of the requirements analysis this specific test
   * operation is validating. This step number ensures that individual test
   * results are correlated with the correct implementation version and helps
   * track the validation of different development iterations.
   *
   * The step value enables proper synchronization between individual test
   * results and the underlying requirements, ensuring that test outcomes remain
   * relevant to the current project scope and implementation objectives.
   */
  step: number;
}