From ced001ade28587f8541822a66a409c1de07aa8f6 Mon Sep 17 00:00:00 2001
From: Your Name <your.email@example.com>
Date: Wed, 27 May 2026 12:21:09 +0800
Subject: [PATCH] test: add lightweight helper regression gate

---
 README.md                    |  1 +
 docs/operations.md           | 11 ++++++++++-
 docs/release-readiness.md    |  2 +-
 package.json                 |  3 ++-
 playwright.helpers.config.ts | 15 +++++++++++++++
 5 files changed, 29 insertions(+), 3 deletions(-)
 create mode 100644 playwright.helpers.config.ts

diff --git a/README.md b/README.md
index 850cdfb2e..9dc171b0f 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,7 @@ pnpm check:ci
 pnpm check:env
 pnpm check:secrets
 pnpm check:metadata
+pnpm test:helpers
 pnpm check:artifacts
 pnpm check:quality
 pnpm clean:artifacts
diff --git a/docs/operations.md b/docs/operations.md
index 1b88fd00e..1b188323f 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -12,6 +12,7 @@ pnpm check:ci
 pnpm check:env
 pnpm check:secrets
 pnpm check:metadata
+pnpm test:helpers
 pnpm exec tsc --noEmit --pretty false
 git diff --check
 pnpm check:artifacts
@@ -30,7 +31,7 @@ pnpm check:quality
 
 ## CI
 
-`.github/workflows/lint.yml` 是基础质量门禁，运行 `pnpm check:quality`，负责 lint、日志治理、公开交付面品牌治理、CI hygiene、环境变量示例卫生、secret hygiene、package metadata、类型检查、diff hygiene 和 tracked 污染物检查。
+`.github/workflows/lint.yml` 是基础质量门禁，运行 `pnpm check:quality`，负责 lint、日志治理、公开交付面品牌治理、CI hygiene、环境变量示例卫生、secret hygiene、package metadata、轻量 helper 回归测试、类型检查、diff hygiene 和 tracked 污染物检查。
 
 CI 和本地提交前检查复用同一个入口，避免规则漂移。
 
@@ -94,6 +95,14 @@ pnpm check:metadata
 
 `pnpm check:metadata` 会检查 `package.json` 的项目名、描述、许可证、Node/pnpm 版本和 package manager 声明是否符合当前交付基线。`repository/homepage/bugs` 会等 canonical remote 仓库完成重命名并验证后再添加，避免对外链接撒谎。
 
+## 轻量 Helper 回归
+
+```bash
+pnpm test:helpers
+```
+
+`pnpm test:helpers` 使用 `playwright.helpers.config.ts` 运行不需要浏览器和 Next dev server 的纯 helper 测试，当前覆盖 Canvas chat/detail/upload helper 的关键行为。它已纳入 `pnpm check:quality`，和完整 Playwright e2e 分开，避免基础门禁被数据库、浏览器和登录态拖慢。
+
 ## 首页性能烟测
 
 ```bash
diff --git a/docs/release-readiness.md b/docs/release-readiness.md
index db9aa8393..f47d2dd05 100644
--- a/docs/release-readiness.md
+++ b/docs/release-readiness.md
@@ -13,7 +13,7 @@ SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes
 
 预期：
 
-- `pnpm check:quality` 通过 lint、日志脱敏门禁、公开交付面品牌治理、CI hygiene、环境变量示例卫生、secret hygiene、package metadata、类型检查、diff hygiene 和 tracked 污染物检查。
+- `pnpm check:quality` 通过 lint、日志脱敏门禁、公开交付面品牌治理、CI hygiene、环境变量示例卫生、secret hygiene、package metadata、轻量 helper 回归测试、类型检查、diff hygiene 和 tracked 污染物检查。
 - `pnpm smoke:routes` 验证 `/` 返回 200。
 - `/classic` 和 `/chat/test-id` 重定向到 `/`。
 - `/settings` 未登录重定向到 `/login?callbackUrl=%2Fsettings`。
diff --git a/package.json b/package.json
index c1f57b4a1..bc64e7918 100644
--- a/package.json
+++ b/package.json
@@ -23,7 +23,8 @@
     "check:env": "node scripts/check-env-example.mjs",
     "check:secrets": "node scripts/check-secrets.mjs",
     "check:metadata": "node scripts/check-package-metadata.mjs",
-    "check:quality": "pnpm lint && pnpm check:logs && pnpm check:brand && pnpm check:ci && pnpm check:env && pnpm check:secrets && pnpm check:metadata && pnpm exec tsc --noEmit --pretty false && git diff --check && pnpm check:artifacts",
+    "test:helpers": "PLAYWRIGHT=True pnpm exec playwright test --config=playwright.helpers.config.ts",
+    "check:quality": "pnpm lint && pnpm check:logs && pnpm check:brand && pnpm check:ci && pnpm check:env && pnpm check:secrets && pnpm check:metadata && pnpm test:helpers && pnpm exec tsc --noEmit --pretty false && git diff --check && pnpm check:artifacts",
     "clean:artifacts": "node scripts/clean-local-artifacts.mjs",
     "smoke:routes": "node scripts/smoke-routes.mjs",
     "format": "pnpm exec ultracite fix",
diff --git a/playwright.helpers.config.ts b/playwright.helpers.config.ts
new file mode 100644
index 000000000..c83a955a5
--- /dev/null
+++ b/playwright.helpers.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  testMatch: /routes\/canvas-chat-helpers\.test\.ts/,
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: 0,
+  workers: process.env.CI ? 2 : 4,
+  reporter: process.env.CI ? "github" : "list",
+  timeout: 60 * 1000,
+  expect: {
+    timeout: 10 * 1000,
+  },
+});