10-04 · e2e 与六道发布门禁全景

// package.json（L7-38：scripts 全景段）
  "scripts": {
    "dev": "pnpm dev:docs",
    "dev:docs": "pnpm --filter @xiaoye/docs docs:dev",
    "dev:playground": "pnpm --filter @xiaoye/playground dev",
    "check:components": "node scripts/check-components.mjs",
    "check:tokens": "node scripts/check-generated.mjs --name tokens --generate \"node scripts/generate-tokens.mjs\" --path packages/tokens/src",
    "check:llms": "node scripts/check-generated.mjs --name llms --generate \"node scripts/generate-llm-files.mjs\" --path llms-full.txt --ignore \"^> 自动生成于\"",
    "generate:tokens": "node scripts/generate-tokens.mjs",
    "check:pro-components": "node scripts/check-pro-components.mjs",
    "lint": "pnpm check:tokens && pnpm check:llms && pnpm check:components && pnpm check:pro-components && eslint .",
    "typecheck": "pnpm run typecheck:packages && pnpm run typecheck:types",
    "typecheck:packages": "vue-tsc -p tsconfig/packages.json --noEmit && vue-tsc -p tsconfig/apps.json --noEmit",
    "typecheck:types": "vue-tsc -p tests/types/tsconfig.json --noEmit",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:e2e:admin": "playwright test tests/e2e/admin-flow.spec.ts",
    "build": "pnpm run build:lib && pnpm run build:docs && pnpm run build:playground",
    "build:lib": "pnpm run build:primitives && pnpm run build:lib:base && pnpm run build:lib:pro",
    "build:primitives": "vite build -c vite.primitives.config.ts",
    "build:lib:base": "vite build -c vite.config.ts && node scripts/prepare-package.mjs base",
    "build:lib:pro": "vite build -c vite.pro.config.ts && node scripts/prepare-package.mjs pro",
    "build:docs": "pnpm --filter @xiaoye/docs docs:build",
    "build:playground": "pnpm --filter @xiaoye/playground build",
    "preview:docs": "pnpm --filter @xiaoye/docs docs:preview",
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "changeset publish",
    "clean": "rimraf packages/xiaoye-primitives/dist packages/xiaoye-components/dist packages/xiaoye-pro-components/dist apps/docs/.vitepress/dist apps/playground/dist",
    "generate:llm": "node scripts/generate-llm-files.mjs",
    "test:e2e": "playwright test",
    "audit:visual": "node scripts/visual-audit.mjs"
  },

# .github/workflows/ci.yml（L28-41：e2e job 全段）

  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 10.30.3
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm test:e2e

// playwright.config.ts（全文，L1-26）
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests/e2e",
  timeout: 60_000,
  fullyParallel: false,
  retries: process.env.CI ? 1 : 0,
  use: {
    baseURL: "http://127.0.0.1:4174",
    trace: "on-first-retry"
  },
  projects: [
    {
      name: "chromium",
      use: {
        ...devices["Desktop Chrome"]
      }
    }
  ],
  webServer: {
    command: "pnpm --filter @xiaoye/docs exec vitepress dev . --host 127.0.0.1 --port 4174",
    url: "http://127.0.0.1:4174/examples/admin",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000
  }
});

// tests/e2e/admin-flow.spec.ts（全文，L1-42）
import { expect, test } from "@playwright/test";
import { clickInViewCenter } from "./helpers";

test("管理后台闭环示例覆盖筛选、详情、编辑、批量和历史记录", async ({ page }) => {
  await page.goto("/examples/admin");

  await expect(page.getByText("增强层闭环已接通")).toBeVisible();

  await clickInViewCenter(page.getByRole("tab", { name: /账单链路/ }));
  await expect(page.getByText("当前视图：账单链路")).toBeVisible();
  await page.getByPlaceholder("按任务名称、负责人搜索").fill("供应商");
  await clickInViewCenter(page.getByRole("button", { name: "查询" }));

  await expect(page.getByText("供应商账单核对")).toBeVisible();

  // 操作列固定在右侧，可点击的按钮是固定列镜像层里的那份
  const viewButton = page
    .locator(".xy-table__fixed-panel--body.is-right")
    .getByRole("button", { name: "查看" })
    .first();
  await clickInViewCenter(viewButton);
  await expect(page.getByText("事项概览")).toBeVisible();
  await expect(page.getByText("操作记录")).toBeVisible();

  await page.getByRole("button", { name: "编辑当前项" }).click({ force: true });
  await page.getByPlaceholder("请输入事项名称").fill("供应商账单核对-已更新");
  await clickInViewCenter(page.getByRole("button", { name: "保存" }));

  await expect(page.locator(".xy-table").getByText("供应商账单核对-已更新").first()).toBeVisible();

  await page
    .getByRole("checkbox", { name: "选择当前行" })
    .first()
    .evaluate((element) => {
      (element as HTMLInputElement).click();
    });
  await expect(page.getByText("批量完成")).toBeVisible();
  await clickInViewCenter(page.getByRole("button", { name: "批量完成" }));

  await clickInViewCenter(viewButton);
  await expect(page.getByText("批量完成")).toBeVisible();
});

<!-- apps/docs/examples/admin.md（L1-13：头部与脚本引入） -->
---
title: 管理后台闭环示例
description: 用一个页面片段串起 SearchForm、ProTable、OverlayForm、DetailPanel 和 AuditTimeline。
outline: deep
---

<script setup lang="ts">
import AdminFlowDemo from "../.vitepress/theme/components/AdminFlowDemo.vue";
</script>

# 管理后台闭环示例

这页用一个单页后台片段，把筛选、列表、覆盖层编辑、详情查看和历史记录放回同一条真实链路里。

// apps/docs/.vitepress/theme/components/AdminFlowDemo.vue（L294-298）
const tabItems = [
  { key: "members", label: "成员台账" },
  { key: "billing", label: "账单链路" },
  { key: "risk", label: "风控排查" }
] as const;

// tests/e2e/docs-demos.spec.ts（L4-8：demoByHeading）
function demoByHeading(heading: Locator) {
  return heading.locator(
    'xpath=following-sibling::*[contains(@class,"vp-demo-block")][1]/following-sibling::*[contains(@class,"vp-demo")][1]'
  );
}

<!-- apps/docs/.vitepress/theme/components/Demo.vue（L106-115：模板锚点） -->
<template>
  <div class="vp-demo-block" v-html="decodedDescription" />

  <div class="vp-demo" :class="{ 'vp-demo--table': isTableDemo }">
    <div class="vp-demo__showcase">
      <div v-if="needsSandbox" class="xy-doc-sandbox">
        <slot name="source" />
      </div>
      <slot v-else name="source" />
    </div>

// tests/e2e/docs-demos.spec.ts（L10-25：Menu 用例）
test("Menu 文档页的横向溢出示例可以打开更多菜单", async ({ page }) => {
  await page.goto("/components/menu");

  const heading = page.getByRole("heading", { name: "横向溢出与 Popper Offset" });
  await expect(heading).toBeVisible();

  const demo = demoByHeading(heading);
  const moreButton = demo.getByRole("button", { name: "更多菜单" });

  await expect(moreButton).toBeVisible();
  await clickInViewCenter(moreButton);

  const popup = page.locator(".demo-menu-overflow__popup").last();
  await expect(popup).toBeVisible();
  await expect(popup.getByRole("menuitem", { name: "系统设置" }).first()).toBeVisible();
});

<!-- apps/docs/examples/menu/overflow-offset.vue（L26-43：ellipsis 菜单与弹层类名） -->
        <xy-menu
          mode="horizontal"
          ellipsis
          default-active="home"
          popper-class="demo-menu-overflow__popup"
          @select="handleSelect"
        >
          <xy-menu-item index="home">首页</xy-menu-item>
          <xy-sub-menu index="product">
            <template #title>产品中心</template>
            <xy-menu-item index="product-list">产品列表</xy-menu-item>
            <xy-menu-item index="product-add">添加产品</xy-menu-item>
          </xy-sub-menu>
          <xy-menu-item index="order">订单管理</xy-menu-item>
          <xy-menu-item index="finance">财务管理</xy-menu-item>
          <xy-menu-item index="marketing">营销活动</xy-menu-item>
          <xy-menu-item index="settings">系统设置</xy-menu-item>
        </xy-menu>

// tests/e2e/docs-demos.spec.ts（L27-47：Table 用例）
test("Table 文档页的 auto fixed summary 组合示例可以稳定渲染并保留汇总", async ({ page }) => {
  await page.goto("/components/table");

  const heading = page.getByRole("heading", { name: "Auto、固定列与汇总组合" });
  await expect(heading).toBeVisible();

  const demo = demoByHeading(heading);
  await expect(demo.getByText("总览", { exact: true }).first()).toBeVisible();
  await expect(demo.getByText("482,000", { exact: true })).toBeVisible();
  await expect(demo.getByText("36,400", { exact: true })).toBeVisible();
  await expect(demo.getByText("242 万", { exact: true }).last()).toBeVisible();

  const bodyWrapper = demo.locator(".xy-table__body-wrapper").first();
  await bodyWrapper.evaluate((element) => {
    element.scrollLeft = element.scrollWidth;
    element.dispatchEvent(new Event("scroll"));
  });

  await expect(demo.getByText("会员增长季 Campaign A").first()).toBeVisible();
  await expect(demo.getByText("86 万", { exact: true }).last()).toBeVisible();
});

// tests/e2e/docs-demos.spec.ts（L49-68：Watermark 用例）
test("Watermark 文档页的全屏与目标容器示例同时覆盖 target 和 fullscreen", async ({ page }) => {
  await page.goto("/components/watermark");

  const heading = page.getByRole("heading", { name: "全屏与目标容器" });
  await expect(heading).toBeVisible();

  const demo = demoByHeading(heading);
  const targetHost = demo.locator(".xy-doc-watermark-target-host");

  await expect(targetHost.locator(".xy-watermark__layer")).toBeVisible();

  await clickInViewCenter(demo.getByText("开启全屏水印"));

  await page.waitForFunction(() => {
    const layers = Array.from(document.body.querySelectorAll<HTMLElement>(".xy-watermark__layer"));
    return layers.some((layer) => getComputedStyle(layer).position === "fixed");
  });

  await expect(demo.getByText("已覆盖 body")).toBeVisible();
});

<!-- apps/docs/examples/watermark/fullscreen-target.vue（L8-45：target 与全屏双形态） -->
  <div class="xy-doc-watermark-host-grid">
    <div class="xy-doc-watermark-host-grid__cell">
      <xy-watermark
        target=".xy-doc-watermark-target-host"
        content="TARGET HOST"
        :opacity="0.12"
        :repeat="'repeat-y'"
      >
        <section class="xy-doc-watermark-helper">
          <h4 class="xy-doc-watermark-helper__title">Target 模式</h4>
          <p class="xy-doc-watermark-helper__description">
            组件声明在左侧，但水印实际会挂到右侧目标容器。slot 只负责说明，不决定宿主。
          </p>
        </section>
      </xy-watermark>
    </div>

    <section class="xy-doc-watermark-target-host xy-doc-watermark-host-grid__cell">
      <span class="xy-doc-watermark-host-grid__badge">External Host</span>
      <h4 class="xy-doc-watermark-target-host__title">右侧是实际水印宿主</h4>
      <p class="xy-doc-watermark-target-host__description">
        适合对接外部面板、预览区或业务容器，而不必改动组件声明所在的位置。
      </p>
    </section>
  </div>

  <div class="xy-doc-watermark-fullscreen-demo">
    <xy-watermark
      :fullscreen="fullscreen"
      content="FULLSCREEN WATERMARK"
      :opacity="0.1"
      :repeat="'repeat'"
    >
      <section class="xy-doc-watermark-fullscreen-demo__surface">
        <xy-space wrap>
          <xy-switch v-model="fullscreen" active-text="关闭全屏水印" inactive-text="开启全屏水印" />
          <xy-tag status="primary">{{ fullscreen ? "已覆盖 body" : "仅示例区域" }}</xy-tag>
        </xy-space>

// tests/e2e/docs-demos.spec.ts（L70-93：Dialog 用例）
test("Dialog 文档页的基础用法示例点击遮罩可以关闭对话框", async ({ page }) => {
  await page.goto("/components/dialog");

  const heading = page.getByRole("heading", { name: "基础用法" });
  await expect(heading).toBeVisible();

  const demo = demoByHeading(heading);
  const trigger = demo.getByRole("button", { name: "新建成员" });
  await expect(trigger).toBeVisible();
  await clickInViewCenter(trigger);

  const dialog = page.locator(".xy-dialog").last();
  const panel = dialog.locator(".xy-dialog__panel");
  await expect(panel).toBeVisible();
  await expect(panel.getByRole("heading", { name: "新建成员" })).toBeVisible();

  // 遮罩 absolute inset:0 覆盖全视口，面板从 15vh 顶部居中展开，
  // (8, 8) 必落在遮罩上且在面板外；不加 force，验证真实 hit-testing。
  const overlay = dialog.locator(".xy-dialog__overlay");
  await expect(overlay).toBeVisible();
  await overlay.click({ position: { x: 8, y: 8 } });

  await expect(dialog).toBeHidden();
});

// tests/e2e/helpers.ts（全文，L1-13）
import type { Locator } from "@playwright/test";

/**
 * 文档站 demo 区点击存在两类遮挡：吸顶导航（.VPNav）会拦截视口顶部元素；
 * 表格右侧固定列是 DOM 镜像，会拦截主区按钮的 hit-target。
 * 先把目标滚动到视口中央，再 force 点击（与镜像按钮语义等价）。
 */
export async function clickInViewCenter(locator: Locator) {
  await locator.evaluate((element) => {
    element.scrollIntoView({ block: "center", inline: "nearest" });
  });
  await locator.click({ force: true });
}

// scripts/check-components.mjs（L57-81：六个入口的实态收集）
const componentDirs = fs
  .readdirSync(path.join(repoRoot, "packages/components"), { withFileTypes: true })
  .filter((entry) => entry.isDirectory() && entry.name !== "node_modules")
  .map((entry) => entry.name)
  .filter((name) => !["dist", "shared", "src"].includes(name))
  .sort();

const exportedComponentNames = collectByRegex(
  readFile("packages/components/exports.ts"),
  /export \* from "\.\/([^"]+)";/g
).filter((name) => name !== "shared");

const docComponentNames = listBasenames("apps/docs/components", ".md").filter(
  (name) => name !== "overview"
);

const typeFixtureNames = listBasenames("tests/types/fixtures", ".ts").filter((name) =>
  componentNames.includes(name)
);
const unitTestNames = listComponentTestGroups();

const themeImportNames = collectByRegex(
  readFile("packages/theme/index.css"),
  /@import "\.\/src\/components\/([^.]+)\.css";/g
);

// scripts/check-components.mjs（L83-126：六组 mismatch 的双向 diff）
const mismatches = [
  {
    message: "组件目录与 manifest 不一致：",
    values: [
      ...diff(componentNames, componentDirs),
      ...diff(componentDirs, componentNames).map((name) => `${name} (多余目录)`)
    ]
  },
  {
    message: "导出入口与 manifest 不一致：",
    values: [
      ...diff(componentNames, exportedComponentNames),
      ...diff(exportedComponentNames, componentNames).map((name) => `${name} (多余导出)`)
    ]
  },
  {
    message: "组件文档与 manifest 不一致：",
    values: [
      ...diff(componentNames, docComponentNames),
      ...diff(docComponentNames, componentNames).map((name) => `${name} (多余文档)`)
    ]
  },
  {
    message: "类型夹具与 manifest 不一致：",
    values: [
      ...diff(componentNames, typeFixtureNames),
      ...diff(typeFixtureNames, componentNames).map((name) => `${name} (多余夹具)`)
    ]
  },
  {
    message: "组件单测与 manifest 不一致：",
    values: [
      ...diff(componentNames, unitTestNames),
      ...diff(unitTestNames, componentNames).map((name) => `${name} (多余单测目录)`)
    ]
  },
  {
    message: "样式入口与 manifest 不一致：",
    values: [
      ...diff(styleNames, themeImportNames),
      ...diff(themeImportNames, styleNames).map((name) => `${name} (多余样式导入)`)
    ]
  }
];

// scripts/check-pro-components.mjs（L114-139：白名单与实态的逐块比对）
function diffNamedExportMap(expected, actual) {
  const messages = [];
  const expectedKeys = Object.keys(expected).sort();
  const actualKeys = Object.keys(actual).sort();

  diff(expectedKeys, actualKeys).forEach((key) => {
    messages.push(`${key} (缺少导出块)`);
  });

  diff(actualKeys, expectedKeys).forEach((key) => {
    messages.push(`${key} (多余导出块)`);
  });

  expectedKeys.forEach((key) => {
    if (!actual[key]) {
      return;
    }

    const missing = diff(expected[key], actual[key]).map((name) => `${key} -> ${name} (缺少导出)`);
    const extra = diff(actual[key], expected[key]).map((name) => `${key} -> ${name} (多余导出)`);

    messages.push(...missing, ...extra);
  });

  return messages.sort();
}