mini-starter/packages/e2e-test-utils/src/types.ts

/**
 * 基础配置选项，所有配置对象的基类
 *
 * @description
 * 提供通用的配置选项，所有工具函数的配置对象都应该继承此接口。
 *
 * @example
 * ```ts
 * interface MyOptions extends BaseOptions {
 *   customOption?: string;
 * }
 * ```
 */
export interface BaseOptions {
  /** 超时时间（毫秒）*/
  timeout?: number;
}

/**
 * 错误上下文接口，用于提供结构化的错误信息
 *
 * @description
 * 包含操作失败时所需的完整上下文信息，帮助开发者快速定位问题。
 *
 * @example
 * ```ts
 * const errorContext: ErrorContext = {
 *   operation: 'selectRadixOption',
 *   target: '残疾类型',
 *   expected: '视力残疾',
 *   actual: '未找到选项',
 *   available: ['听力残疾', '言语残疾'],
 *   suggestion: '检查选项值是否正确'
 * };
 * ```
 */
export interface ErrorContext {
  /** 操作类型（如 'selectRadixOption'）*/
  operation: string;
  /** 目标（如下拉框标签）*/
  target: string;
  /** 期望值 */
  expected?: string;
  /** 实际值 */
  actual?: string;
  /** 可用选项列表 */
  available?: string[];
  /** 修复建议 */
  suggestion?: string;
}

/**
 * 异步 Select 选项配置
 *
 * @description
 * 用于异步加载选项的 Radix UI Select 组件。
 *
 * @property {number} timeout - 超时时间（毫秒），默认 5000ms
 * @property {boolean} waitForOption - 是否等待选项加载完成，默认 true
 * @property {boolean} waitForNetworkIdle - 是否等待网络空闲后再操作，默认 true
 *
 * @example
 * ```ts
 * // 默认配置（等待网络空闲和选项加载）
 * await selectRadixOptionAsync(page, '省份', '广东省');
 *
 * // 自定义超时并禁用网络空闲等待
 * await selectRadixOptionAsync(page, '城市', '深圳市', {
 *   timeout: 10000,
 *   waitForNetworkIdle: false
 * });
 * ```
 */
export interface AsyncSelectOptions extends BaseOptions {
  /** 是否等待选项加载完成（默认：true）*/
  waitForOption?: boolean;
  /** 等待网络空闲后再操作（默认：true）*/
  waitForNetworkIdle?: boolean;
}

/**
 * 文件上传选项配置
 *
 * @description
 * 用于文件上传工具函数的配置选项。
 *
 * @property {string} fixturesDir - fixtures 目录路径，默认为 'web/tests/fixtures'
 * @property {boolean} waitForUpload - 是否等待上传完成，默认为 true
 *
 * @example
 * ```ts
 * // 默认配置
 * await uploadFileToField(page, 'photo-upload', 'sample-id-card.jpg');
 *
 * // 自定义 fixtures 目录
 * await uploadFileToField(page, 'photo-upload', 'sample-id-card.jpg', {
 *   fixturesDir: 'custom/fixtures/path'
 * });
 *
 * // 自定义超时
 * await uploadFileToField(page, 'photo-upload', 'sample-id-card.jpg', {
 *   timeout: 10000
 * });
 * ```
 */
export interface FileUploadOptions extends BaseOptions {
  /** fixtures 目录路径，默认为 'tests/fixtures' */
  fixturesDir?: string;
  /** 是否等待上传完成，默认为 true */
  waitForUpload?: boolean;
}

/**
 * 表单步骤配置
 *
 * @description
 * 用于表单填写工具函数的配置选项。
 *
 * @beta 此类型为计划中的功能，对应的工具函数尚未实现。
 *
 * @example
 * ```ts
 * // 计划中的功能
 * await fillFormField(page, selector, 'value', {
 *   timeout: 3000,
 *   scrollToElement: true
 * });
 * ```
 */
export interface FormStepOptions extends BaseOptions {
  /** 是否在填写前滚动到元素（默认：true）*/
  scrollToElement?: boolean;
}

/**
 * 对话框操作配置
 *
 * @description
 * 用于对话框工具函数的配置选项。
 *
 * @beta 此类型为计划中的功能，对应的工具函数尚未实现。
 *
 * @example
 * ```ts
 * // 计划中的功能
 * await closeDialog(page, {
 *   timeout: 2000,
 *   closeWaitTime: 500
 * });
 * ```
 */
export interface DialogOptions extends BaseOptions {
  /** 对话框关闭后的等待时间（毫秒，默认：500）*/
  closeWaitTime?: number;
}

// 重新导出 Playwright 类型以便使用者使用
export type { Page } from '@playwright/test';