@epoint-testtech/stage-create 0.0.3-alpha.1

package/templates/glue/src/skeletons/login.skeleton.ts

@@ -0,0 +1,104 @@
+import fs from 'fs';
+import path from 'path';
+import type { BrowserContext, Locator, Page } from '@playwright/test';
+import { StagePath, stageLocator, syncAutoFill } from '@epoint-testtech/stage-core';
+import { getRequiredEnvVar, log } from '@epoint-testtech/stage-core/utils';
+
+type AuthStorageState = {
+  cookies?: Parameters<BrowserContext['addCookies']>[0];
+  origins?: Array<{
+    origin: string;
+    localStorage?: Array<{
+      name: string;
+      value: string;
+    }>;
+  }>;
+};
+
+export class LoginPage {
+  private readonly repoInput账号: Locator;
+  private readonly repoInput密码: Locator;
+  private readonly repoBtn登录: Locator;
+  private readonly repoBtn暂不修改: Locator;
+  private readonly systemUrl = getRequiredEnvVar('LOGIN_SYSTEM_URL');
+
+  /**
+   * 初始化登录页面对象。
+   * @param page Playwright 页面对象
+   */
+  constructor(public readonly page: Page) {
+    this.repoInput账号 = page
+      .locator("//input[contains(@type, 'text') or contains(@class,'user') or contains(@id, 'username') or contains(@placeholder, '用户名') or contains(@placeholder, '账号')]")
+      .filter({ visible: true })
+      .first();
+    this.repoInput密码 = page.locator("//input[@type='password' or contains(@placeholder, '密码')]").filter({ visible: true }).first();
+    this.repoBtn登录 = page.locator(
+      "//*[contains(@class, 'login-btn') or" +
+      " contains(@class,'submit') or " +
+      "contains(@class,'login-form-btn') or " +
+      "contains(@class, 'btn-login')] | //div[@class='second-content']//div[contains(text(), '登')]"
+    ).filter({ visible: true }).first();
+    this.repoBtn暂不修改 = page.getByRole('button', { name: '暂不修改' }).filter({ visible: true });
+  }
+
+  /**
+   * 执行认证复用或账密登录，并在登录后同步 auto-fill。
+   */
+  async login(): Promise<void> {
+    const username = getRequiredEnvVar('LOGIN_USERNAME');
+    const password = getRequiredEnvVar('LOGIN_PASSWORD');
+
+    await this.restoreAuthStateIfPresent();
+    await this.page.goto(this.systemUrl);
+    if (await stageLocator(this.repoBtn登录, '登录按钮').waitForExist({ timeout: 2_000 })) {
+      await this.repoInput账号.fill(username);
+      await this.repoInput密码.pressSequentially(password);
+      await this.repoBtn登录.click();
+      await stageLocator(this.repoBtn暂不修改, '暂不修改').clickIfExist({ timeout: 3_000 });
+      await this.saveAuthState();
+      log.info(`账密登录-->账号: ${username}，认证信息已保存：${StagePath.authFilePath}`);
+    } else {
+      log.info(`已复用认证信息，不再账密登录：${StagePath.authFilePath}`);
+    }
+
+    await syncAutoFill(this.page);
+  }
+
+  /**
+   * 从认证文件中恢复 cookies 和 localStorage。
+   * @returns 存在可读取认证文件并完成恢复时返回 true，否则返回 false。
+   */
+  private async restoreAuthStateIfPresent(): Promise<boolean> {
+    if (!fs.existsSync(StagePath.authFilePath)) {
+      return false;
+    }
+
+    try {
+      const authState = JSON.parse(fs.readFileSync(StagePath.authFilePath, 'utf-8')) as AuthStorageState;
+      if (authState.cookies?.length) {
+        await this.page.context().addCookies(authState.cookies);
+      }
+      if (authState.origins?.length) {
+        await this.page.context().addInitScript((origins: AuthStorageState['origins']) => {
+          const matchedOrigin = origins?.find((item) => item.origin === window.location.origin);
+          for (const item of matchedOrigin?.localStorage ?? []) {
+            window.localStorage.setItem(item.name, item.value);
+          }
+        }, authState.origins);
+      }
+      log.info(`已加载认证信息：${StagePath.authFilePath}`);
+      return true;
+    } catch (error) {
+      log.warn(`认证信息加载失败，将回退账密登录：${StagePath.authFilePath}，原因：${String(error)}`);
+      return false;
+    }
+  }
+
+  /**
+   * 保存当前浏览器上下文认证信息。
+   */
+  private async saveAuthState(): Promise<void> {
+    fs.mkdirSync(path.dirname(StagePath.authFilePath), { recursive: true });
+    await this.page.context().storageState({ path: StagePath.authFilePath });
+  }
+}

package/templates/glue/src/skeletons/menu.skeleton.ts

@@ -0,0 +1,37 @@
+import type { Page } from '@playwright/test';
+import { log } from '@epoint-testtech/stage-core/utils';
+
+export class MenuPage {
+  /**
+   * 初始化菜单页面对象。
+   * @param page Playwright 页面对象
+   */
+  constructor(public readonly page: Page) {
+  }
+
+  /**
+   * 导航到指定的菜单路径。
+   * @param menuNameTree 菜单路径，格式为 "流程服务>动作流>动作流管理" 或模块名称
+   */
+  async navigateToMenu(menuNameTree: string): Promise<void> {
+    let actualSystemMenuRoute = menuNameTree;
+
+    log.info(`菜单导航-->${actualSystemMenuRoute}`);
+    const menuNames = actualSystemMenuRoute.split('>');
+    for (const menuName of menuNames) {
+      const repoBtn菜单 = this.page.locator(`span.menu-name[title="${menuName}"]`);
+      const repoBtn菜单状态 = await repoBtn菜单.locator('..').getAttribute('class');
+      if (repoBtn菜单状态?.includes('hasSub')) {
+        if (repoBtn菜单状态.includes('expanded')) {
+          log.info(`  菜单：${menuName}，状态：已展开，无需点击`);
+        } else {
+          log.info(`  菜单：${menuName}，状态：未展开，点击展开`);
+          await repoBtn菜单.click();
+        }
+      } else {
+        log.info(`  菜单：${menuName}，状态：无子菜单，直接点击`);
+        await repoBtn菜单.click();
+      }
+    }
+  }
+}

package/templates/glue/src/tests/example.spec.ts

@@ -0,0 +1,99 @@
+/**
+ * 真实 CRUD 骨架示例。
+ *
+ * 运行前请先准备 `.env`：
+ * - LOGIN_SYSTEM_URL: 登录页地址
+ * - LOGIN_USERNAME: 登录用户名
+ * - LOGIN_PASSWORD: 登录密码
+ *
+ * 该示例预埋了 zwplace 模块的真实 CRUD 槽位，生成项目后通常只需要
+ * 按目标模块替换菜单路径、iframe 关键字和 locator。
+ */
+import { test, type Page } from '@playwright/test';
+import { CrudPage, LoginPage, MenuPage, type CrudWorkflowData } from '../skeletons';
+
+test.describe('示例 CRUD 测试', () => {
+  const menuRoute = '场所窗口信息管理>场所窗口信息列表';
+  const crudSlots = {
+    moduleId: 'zwplace',
+    searchConditions: [
+      {
+        component: 'input' as const,
+        field: 'placename',
+        label: '场所名称',
+        seedValue: '自动化测试名称',
+        strategy: 'timestamp_prefix' as const,
+        updatePrefix: '修改',
+        addLocator: "xpath=//div[@label='场所名称']//input[@class='mini-textbox-input']",
+        editLocator: "xpath=//div[@label='场所名称']//input[@class='mini-textbox-input']",
+        listLocator: "xpath=//div[@label='场所名称']//input[@class='mini-textbox-input']",
+      },
+    ],
+    frames: {
+      listIframeSrcKeyword: 'gxhzwplacelist.html',
+      addIframeSrcKeyword: 'gxhzwplaceadd',
+      editIframeSrcKeyword: 'gxhzwplaceedit',
+    },
+    locators: {
+      createButton: "xpath=//a[contains(@class,'mini-button')][normalize-space()='新增场所信息管理']",
+      addAutofillTrigger: 'xpath=//*[@title=\'默认填充\']',
+      addSaveButton: "xpath=//a[contains(@class,'mini-button')][normalize-space()='保存并关闭']",
+      listSearchSubmit: "xpath=//span[text()='搜索']",
+      listResultValueLocatorTemplate: "xpath=//*[@id='datagrid']//div[text()='{{value}}']",
+      listEditActionLocatorTemplate: "xpath=//*[@id='datagrid']//tr[.//div[text()='{{value}}']]//i[@data-tooltip='修改']",
+      editSaveButton: "xpath=//a[contains(@class,'mini-button')][normalize-space()='保存并关闭']",
+      listRowSelectLocatorTemplate: "xpath=//*[@id='datagrid']//div[text()='{{value}}']",
+      listDeleteButton: "xpath=//a[contains(@class,'mini-button')][normalize-space()='删除选定']",
+      deleteConfirmButton: 'text=确定',
+    },
+    assertions: {
+      deletePolicy: 'blocked_by_business_rule' as const,
+      blockedDeleteMessage: '在用数据不可删除！',
+    },
+  };
+
+  test.describe.configure({ mode: 'serial' });
+
+  let workflowData: CrudWorkflowData | undefined;
+
+  async function openModule(page: Page): Promise<void> {
+    const loginPage = new LoginPage(page);
+    const menuPage = new MenuPage(page);
+    await loginPage.login();
+    await menuPage.navigateToMenu(menuRoute);
+  }
+
+  test('Create', async ({ page }) => {
+    await openModule(page);
+    const crudPage = new CrudPage(page, crudSlots);
+    workflowData = crudPage.prepareWorkflowData();
+    await crudPage.runCreateWorkflow(workflowData);
+  });
+
+  test('Read', async ({ page }) => {
+    await openModule(page);
+    if (!workflowData) {
+      throw new Error('Read 示例依赖 Create 先生成 workflowData');
+    }
+    const crudPage = new CrudPage(page, crudSlots);
+    await crudPage.runReadWorkflow(workflowData);
+  });
+
+  test('Update', async ({ page }) => {
+    await openModule(page);
+    if (!workflowData) {
+      throw new Error('Update 示例依赖 Create 先生成 workflowData');
+    }
+    const crudPage = new CrudPage(page, crudSlots);
+    await crudPage.runUpdateWorkflow(workflowData);
+  });
+
+  test('Delete', async ({ page }) => {
+    await openModule(page);
+    if (!workflowData) {
+      throw new Error('Delete 示例依赖 Create 先生成 workflowData');
+    }
+    const crudPage = new CrudPage(page, crudSlots);
+    await crudPage.runDeleteWorkflow(workflowData);
+  });
+});

package/templates/glue/src/web/component/anchor-types.ts

@@ -0,0 +1,9 @@
+/**
+ * @Description: 
+ * @Author: taurus
+ * @Date: 2026/06/05 10:02
+ */
+
+import type { Page } from '@playwright/test';
+
+export type LocatorContext = Pick<Page, 'locator'>;

package/templates/glue/src/web/component/dataexport-component.ts

@@ -0,0 +1,143 @@
+/**
+ * @Description: 数据导出组件
+ * @Author: taurus
+ * @Date: 2026/06/08 15:10
+ */
+
+
+import type { Locator } from '@playwright/test';
+import { log } from '@epoint-testtech/stage-core/utils';
+import { LocatorContext } from './anchor-types';
+
+/**
+ * @Description: MiniUI 风格的通用数据导出组件
+ * 适用于包含“导出全部”、“导出当前页”、“从第 X 页导出到第 Y 页”的通用导出弹窗
+ * * ====================================================================================
+ * 📌 【组件库元素变量命名规范 (统一语法糖)】
+ * 格式模板：repo + [元素类型缩写] + [中文业务性质名称]
+ * * 1. 前缀固定为 "repo"：代表 Repository（对象库/定位器仓库）的缩写。
+ * 2. 元素类型缩写（大驼峰）：根据 UI 元素的实际物理类型或组件类型进行精简：
+ * - 输入框 -> Input
+ * - 按钮 -> Btn (Button 缩写)
+ * - 单选框 -> RadioBtn (RadioButton 缩写)
+ * - 容器/锚点 -> Anchor
+ * 3. 中文业务性质名称：直接提取页面元素的 Label 文本，或总结成具体的业务描述中文，极具辨识度。
+ * * 示例：
+ * - repoInput导出开始页码 -> repo(仓库) + Input(输入框) + 导出开始页码(业务名称)
+ * - repoRadioBtn导出全部  -> repo(仓库) + RadioBtn(单选框) + 导出全部(业务名称)
+ * - repoBtn导出          -> repo(仓库) + Btn(按钮) + 导出(业务名称)
+ * ====================================================================================
+ */
+export class DataExportComponent {
+
+    // -- 层1：静态定位器字段（严格遵循统一语法糖命名规范）
+    private readonly repoAnchor: Locator;
+
+    // 单选框定位器
+    private readonly repoRadioBtn导出全部: Locator;
+    private readonly repoRadioBtn导出当前页: Locator;
+    private readonly repoRadioBtn按页码导出: Locator;
+
+    // 输入框定位器
+    private readonly repoInput导出开始页码: Locator;
+    private readonly repoInput导出结束页码: Locator;
+
+    // 动作按钮定位器
+    private readonly repoBtn导出: Locator;
+
+    constructor(
+        private readonly context: LocatorContext,
+        private readonly label: string
+    ) {
+        // 1. 组件大容器锚点
+        this.repoAnchor = context.locator('div.mini-dataexport-popup, div.mini-popup').filter({ visible: true });
+
+        // 2. 单选框选项行定位
+        this.repoRadioBtn导出全部 = this.repoAnchor
+            .locator('div.mini-radiobuttonlist-item')
+            .filter({ hasText: /^导出全部$/ });
+
+        this.repoRadioBtn导出当前页 = this.repoAnchor
+            .locator('div.mini-radiobuttonlist-item')
+            .filter({ hasText: /^导出当前页$/ });
+
+        // 核心：定位到包含页码输入框的这一行单选容器（利用文本锁定行，彻底干掉动态ID）
+        const scopePageRow = this.repoAnchor
+            .locator('div.mini-radiobuttonlist-item')
+            .filter({ hasText: '从第' });
+
+        this.repoRadioBtn按页码导出 = scopePageRow;
+
+        // 3. 输入框定位（在锁定的 scopePageRow 范围内，按顺序抓取输入框）
+        // .first() 匹配第一个 input.mini-export-num (开始页)
+        this.repoInput导出开始页码 = scopePageRow.locator('input.mini-export-num').first();
+        // .last() 匹配第二个 input.mini-export-num (结束页)
+        this.repoInput导出结束页码 = scopePageRow.locator('input.mini-export-num').last();
+
+        /*
+         * 4. 动作按钮定位器多类名设计说明
+         * * 这里利用了 Playwright 的多类名 CSS 定位技巧。在编写组件库时，为了应对不同系统的微小差异，有以下三种定位器的类名处理方式：
+         * * ① “或” 关系（OR）—— 匹配任意一个类
+         * - 写法：用逗号 `,` 分隔。
+         * - 示例：context.locator('.mini-button, .mini-export-btn')
+         * - 原理：它会同时匹配到 <a class="mini-button"> 或者 <button class="mini-export-btn">。
+         * - 场景：组件库中做多系统兼容。比如系统 A 的导出按钮叫 mini-button，系统 B 叫 mini-export-btn，用逗号就能一体化兼容。
+         * * ② “且” 关系（AND）—— 必须同时具备这些类
+         * - 写法：多个类名紧挨着写在一起，中间不要有空格和逗号。
+         * - 示例：context.locator('.mini-button.mini-export-btn')
+         * - 原理：只会匹配同时包含这两个类的元素，如：<a class="mini-button mini-export-btn">...</a>。若仅带有一个类则无法匹配。
+         * - 场景：精准过滤。当页面上有普通按钮 and 导出按钮时，定位出那个“既是普通按钮又是专门负责导出的”目标。
+         * * ③ “包含” 关系（模糊匹配）—— 匹配类名的一部分
+         * - 写法：使用 CSS 的属性选择器 [class*="xxx"]。
+         * - 示例：context.locator('[class*="mini-button"]')
+         * - 原理：只要 class 属性里包含了 mini-button 字符串（如 mini-button-textOnly、mini-button-state-primary）就能被匹配。
+         * - 场景：对付类名非常长、且带有动态后缀的前端框架（如 MiniUI、ElementUI）。
+         * * 💡 结合当前按钮的实际定位应用：
+         * 我们采用“或（OR）”的最高兼容性写法抓取所有具备按钮特征的外壳，再配合 .filter({ hasText: /^导出$/ }) 
+         * 精准过滤出内部包裹着“导出”文本的那一个外壳，从而完美适配各种系统的按钮节点。
+         */
+        this.repoBtn导出 = this.repoAnchor
+            .locator('.mini-button, .mini-export-btn')
+            .filter({ hasText: /^导出$/ })
+            .first();
+    }
+
+    /**
+     * 选择“导出全部”并点击导出
+     */
+    async exportAll() {
+        log.info(`[DataExportComponent] [${this.label}] 准备导出全部数据...`);
+        await this.repoRadioBtn导出全部.click();
+        await this.repoBtn导出.click();
+    }
+
+    /**
+     * 选择“导出当前页”并点击导出
+     */
+    async exportCurrentPage() {
+        log.info(`[DataExportComponent] [${this.label}] 准备导出当前页数据...`);
+        await this.repoRadioBtn导出当前页.click();
+        await this.repoBtn导出.click();
+    }
+
+    /**
+     * 选择“按自定义页码范围”并点击导出
+     * @param startPage 开始页码
+     * @param endPage 结束页码
+     */
+    async exportByPageRange(startPage: number, endPage: number) {
+        log.info(`[DataExportComponent] [${this.label}] 准备按页码范围导出: 第 ${startPage} 页 到 第 ${endPage} 页`);
+
+        // 1. 先点击该行，确保激活“按页码”的单选状态
+        await this.repoRadioBtn按页码导出.click();
+
+        // 2. 填充开始页码与结束页码
+        await this.repoInput导出开始页码.fill(startPage.toString());
+        await this.repoInput导出结束页码.fill(endPage.toString());
+
+        // 3. 点击最终的导出按钮
+        await this.repoBtn导出.click();
+
+        log.info(`[DataExportComponent] [${this.label}] 导出指令已触发`);
+    }
+}

package/templates/glue/src/web/component/index.ts

@@ -0,0 +1,2 @@
+export { ListBoxComponent } from './listbox-component';
+export { DataExportComponent } from './dataexport-component';

package/templates/glue/src/web/component/listbox-component.ts

@@ -0,0 +1,41 @@
+/**
+ * @Description: 
+ * @Author: taurus
+ * @Date: 2026/06/04 17:06
+ */
+
+import type { Locator, Page } from '@playwright/test';
+import { log } from '@epoint-testtech/stage-core/utils';
+import { LocatorContext } from './anchor-types';
+
+/***
+ * @Description: 下拉列表组件
+ */
+export class ListBoxComponent {
+
+    // -- 层1：静态定位器字段（repo* 前缀）
+    private readonly repo打开按钮: Locator;
+    private readonly repo下拉列表容器: Locator;
+
+    constructor(
+        private readonly context: LocatorContext,
+        private readonly label: string
+    ) {
+        this.repo打开按钮 = context.locator(`//div[@label="${label}"]//span[@name="trigger"]`).filter({ visible: true });
+        this.repo下拉列表容器 = context.locator('//table[contains(@class, "mini-listbox-items")]').filter({ visible: true });
+    }
+
+    // --层2：动态定位器工厂（locate* 前缀）
+    private locateOption(itemName: string): Locator {
+        return this.repo下拉列表容器.locator(`xpath=.//td[text()="${itemName}"]`);
+    }
+
+    // -- 层3：公开动作方法（selectItem 等）
+    async selectItem(itemName: string) {
+        await this.repo打开按钮.click();
+        await this.locateOption(itemName).first().waitFor({ state: 'visible' });
+        await this.locateOption(itemName).first().click();
+
+        log.info(`[ListBox] 标签为 "${this.label}" 的组件成功选择项: ${itemName}`);
+    }
+}

package/templates/glue/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}