@autobe/agent/src/orchestrate/test/structures/IAutoBeTestScenarioApplication.ts

AI backend server code generator

import { AutoBeOpenApi } from "@autobe/interface";
import { tags } from "typia";

import { IAutoBePreliminaryGetAnalysisFiles } from "../../common/structures/IAutoBePreliminaryGetAnalysisFiles";
import { IAutoBePreliminaryGetInterfaceOperations } from "../../common/structures/IAutoBePreliminaryGetInterfaceOperations";
import { IAutoBePreliminaryGetInterfaceSchemas } from "../../common/structures/IAutoBePreliminaryGetInterfaceSchemas";

export interface IAutoBeTestScenarioApplication {
  /**
   * Process test scenario generation task or preliminary data requests.
   *
   * Creates comprehensive test scenarios for API endpoints by retrieving
   * necessary interface operations via RAG (Retrieval-Augmented Generation) and
   * generating detailed test drafts with dependencies.
   *
   * @param props Request containing either preliminary data request or complete
   *   task
   */
  process(props: IAutoBeTestScenarioApplication.IProps): void;
}

export namespace IAutoBeTestScenarioApplication {
  export interface IProps {
    /**
     * Think before you act.
     *
     * Before requesting preliminary data or completing your task, reflect on your
     * current state and explain your reasoning:
     *
     * For preliminary requests (getAnalysisFiles, getPrismaSchemas, etc.):
     * - What critical information is missing that you don't already have?
     * - Why do you need it specifically right now?
     * - Be brief - state the gap, don't list everything you have.
     *
     * For completion (complete):
     * - What key assets did you acquire?
     * - What did you accomplish?
     * - Why is it sufficient to complete?
     * - Summarize - don't enumerate every single item.
     *
     * This reflection helps you avoid duplicate requests and premature completion.
     */
    thinking: string;

    /**
     * Type discriminator for the request.
     *
     * Determines which action to perform: preliminary data retrieval
     * (getAnalysisFiles, getInterfaceOperations, getInterfaceSchemas) or
     * final test scenario generation (complete). When preliminary returns
     * empty array, that type is removed from the union, physically
     * preventing repeated calls.
     */
    request:
      | IComplete
      | IAutoBePreliminaryGetAnalysisFiles
      | IAutoBePreliminaryGetInterfaceOperations
      | IAutoBePreliminaryGetInterfaceSchemas;
  }

  /**
   * Request to generate test scenarios for API endpoints.
   *
   * Executes test scenario generation to create comprehensive, implementable
   * test scenarios covering all endpoint behaviors, edge cases, and business
   * logic validations.
   */
  export interface IComplete {
    /**
     * Type discriminator for the request.
     *
     * Determines which action to perform: preliminary data retrieval or actual
     * task execution. Value "complete" indicates this is the final task
     * execution request.
     */
    type: "complete";

    /**
     * Collection of test scenario groups organized by endpoint.
     *
     * Each group contains multiple test scenarios for a single endpoint,
     * covering various user scenarios, edge cases, and business rule
     * validations. Dependencies on other endpoints are explicitly captured to
     * ensure implementable tests.
     */
    scenarioGroups: IAutoBeTestScenarioApplication.IScenarioGroup[];
  }

  export interface IScenarioGroup {
    /**
     * Target API endpoint to test.
     *
     * This must be **unique** across all scenario groups. An endpoint is
     * identified by its `path` and `method` combination.
     *
     * Multiple test scenarios may exist for a single endpoint.
     */
    endpoint: AutoBeOpenApi.IEndpoint;

    /**
     * An array of test scenarios associated with the given endpoint.
     *
     * Each scenario represents a specific test case for the same `path` and
     * `method`.
     *
     * IMPORTANT: Each scenario must be actually implementable. A scenario's
     * implementability is determined by the existence of ALL APIs (endpoints)
     * required to test it. This includes not only the primary endpoint being
     * tested, but also ALL dependency endpoints needed for setup,
     * authentication, and data preparation. If even one required dependency API
     * is missing from the available operations, the scenario cannot be
     * implemented and should not be generated.
     *
     * Example: A "test banned user login" scenario requires both a login API
     * AND a ban user API. If the ban API doesn't exist, this scenario is not
     * implementable regardless of database schema fields.
     */
    scenarios: IScenario[] & tags.MinItems<1>;
  }

  /**
   * Represents a test scenario for a single API operation.
   *
   * This interface defines a structured, user-centric test draft that includes
   * a descriptive function name, a detailed scenario draft, and logical
   * dependencies on other endpoints required for context or setup.
   *
   * CRITICAL: All referenced endpoints MUST exist in the provided API
   * operations. Do NOT create scenarios for non-existent APIs, even if database
   * schema fields suggest their existence. Test scenarios must be implementable
   * with available APIs only.
   */
  export interface IScenario {
    /**
     * A detailed natural language description of how this API endpoint should
     * be tested. This should include both successful and failure scenarios,
     * business rule validations, edge cases, and any sequence of steps
     * necessary to perform the test. A subsequent agent will use this draft to
     * generate multiple concrete test cases.
     */
    draft: string;

    /**
     * Descriptive function name derived from the user scenario.
     *
     * The function name serves as a concise, technical identifier that clearly
     * represents the specific user scenario being described. It should be
     * immediately understandable and directly correspond to the user situation
     * without requiring additional context.
     *
     * ## Naming Convention
     *
     * DO: Use snake_case naming convention.
     *
     * - Must start with `test_api_` prefix (mandatory requirement)
     * - ALWAYS start with business feature, NOT action verbs
     * - Business feature comes first, followed by scenario context
     * - Embed action verbs within the scenario description, not at the beginning
     *
     * ## Content Structure
     *
     * Function names should follow this pattern:
     * `test_api_[core_feature]_[specific_scenario]`
     *
     * Where:
     *
     * - `core_feature`: The main business feature or entity being tested
     *   (customer, seller, cart, push_message, etc.)
     * - `specific_scenario`: The specific operation or scenario context
     *   (join_verification_not_found, login_success,
     *   moderator_assignment_update, discountable_ticket_duplicated,
     *   csv_export, etc.)
     *
     * ## Business Feature-Based Examples
     *
     * - `test_api_customer_join_verification_not_found` - Customer join
     *   verification when verification code not found
     * - `test_api_seller_login` - Seller login operation
     * - `test_api_cart_discountable_ticket_duplicated` - Cart discountable ticket
     *   with duplication scenario
     * - `test_api_push_message_csv` - Push message functionality with CSV format
     * - `test_api_product_review_update` - Product review update operation
     *
     * ## Clarity Guidelines
     *
     * - Prioritize clarity over brevity
     * - Avoid technical jargon or implementation terms
     * - Use terminology that reflects user perspective
     * - Ensure the name alone conveys the user's intent
     * - Make it understandable to non-technical stakeholders
     * - Keep consistent with user scenario description
     *
     * ## Single Endpoint Alignment
     *
     * Function names must reflect scenarios that:
     *
     * - Accomplish user goals through this single endpoint only
     * - Don't imply dependency on other API operations
     * - Represent complete user interactions
     */
    functionName: string;

    /**
     * A list of other API endpoints that this scenario logically depends on.
     *
     * These dependencies represent context or prerequisite conditions, such as
     * authentication, resource creation, or data setup, that are relevant to
     * the test. This list is not a strict execution order — if ordering is
     * important, it must be described explicitly in the `purpose`.
     *
     * WARNING: Every endpoint referenced here MUST exist in the provided API
     * operations. Do NOT reference endpoints that are not explicitly available,
     * even if they seem logically necessary based on database schema or
     * business logic.
     */
    dependencies: IDependencies[];
  }

  export interface IDependencies {
    /**
     * Target API endpoint that this scenario depends on.
     *
     * This endpoint MUST exist in the available API operations list.
     * Non-existent endpoints will cause test implementation failures.
     */
    endpoint: AutoBeOpenApi.IEndpoint;

    /**
     * A concise explanation of why this API call is relevant or required for
     * the main test scenario.
     *
     * This should describe the contextual or setup role of the dependency, such
     * as creating necessary data or establishing user authentication.
     *
     * Example: "Creates a category so that a product can be linked to it during
     * creation."
     */
    purpose: string;
  }
}