mini-starter/packages/e2e-test-utils/src/cascade-select.ts

/**
 * @license
 * Copyright 2025 多八多云端开发环境
 *
 * 省市区级联选择 E2E 测试工具
 *
 * @description
 * 专门用于省市区三级联动选择的 E2E 测试工具方法。
 * 处理级联选择特有的时序问题：选择省份后等待城市选项加载，选择城市后等待区县选项加载。
 */

import type { Page } from '@playwright/test';
import { selectRadixOptionAsync } from './radix-select.js';

/**
 * 省市区级联选择配置
 */
export interface CascadeSelectOptions {
  /** 省份 */
  province: string;
  /** 城市 */
  city: string;
  /** 区县（可选） */
  district?: string;
  /** 每级选择的超时时间（毫秒），默认 10000 */
  timeout?: number;
  /** 级联间等待时间（毫秒），默认 1500（增加以适应网络请求） */
  cascadeDelay?: number;
}

/**
 * 执行省市区级联选择
 *
 * @description
 * 按顺序选择省份、城市、区县，每级选择后等待一段时间确保下一级选项加载完成。
 *
 * @example
 * ```typescript
 * await selectCascade(page, {
 *   province: '湖北省',
 *   city: '武汉市',
 *   district: '武昌区'
 * });
 * ```
 *
 * @param page - Playwright Page 对象
 * @param options - 级联选择配置
 * @throws {Error} 当任何一级选择失败时
 */
export async function selectCascade(
  page: Page,
  options: CascadeSelectOptions
): Promise<void> {
  const {
    province,
    city,
    district,
    timeout = 10000,
    cascadeDelay = 1500
  } = options;

  console.debug(`[selectCascade] 开始级联选择: ${province} > ${city}${district ? ' > ' + district : ''}`);

  // 1. 选择省份
  console.debug(`[selectCascade] 步骤 1/3: 选择省份 "${province}"`);
  await selectRadixOptionAsync(page, '省份 *', province, { timeout });
  console.debug(`[selectCascade] 省份选择完成`);

  // 2. 等待城市选项加载（关键：省份选择后需要等待网络请求返回）
  console.debug(`[selectCascade] 等待城市选项加载 (${cascadeDelay}ms)`);
  await page.waitForTimeout(cascadeDelay);

  // 3. 选择城市
  console.debug(`[selectCascade] 步骤 2/3: 选择城市 "${city}"`);
  await selectRadixOptionAsync(page, '城市 *', city, { timeout });
  console.debug(`[selectCascade] 城市选择完成`);

  // 4. 如果需要选择区县
  if (district) {
    console.debug(`[selectCascade] 等待区县选项加载 (${cascadeDelay}ms)`);
    await page.waitForTimeout(cascadeDelay);

    console.debug(`[selectCascade] 步骤 3/3: 选择区县 "${district}"`);
    await selectRadixOptionAsync(page, '区县', district, { timeout });
    console.debug(`[selectCascade] 区县选择完成`);
  }

  console.debug(`[selectCascade] 级联选择完成`);
}

/**
 * 执行省市二级级联选择（不含区县）
 *
 * @description
 * 简化版本的级联选择，只选择省份和城市。
 *
 * @example
 * ```typescript
 * await selectProvinceCity(page, '湖北省', '武汉市');
 * ```
 *
 * @param page - Playwright Page 对象
 * @param province - 省份名称
 * @param city - 城市名称
 * @param timeout - 超时时间（毫秒），默认 10000
 */
export async function selectProvinceCity(
  page: Page,
  province: string,
  city: string,
  timeout = 10000
): Promise<void> {
  await selectCascade(page, { province, city, timeout });
}