dsh-gate-agent 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +284 -2
- package/cordis.patch.yml +144 -0
- package/icon.svg +4 -0
- package/launchers/verify-notes.mjs +20 -0
- package/launchers/verify-notes.yml +34 -0
- package/lib/index.js +2199 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +32 -4
- package/skills/gate-code-review/SKILL.md +115 -0
- package/skills/gate-code-review/assets/worker-briefs/gate-implement-review.md +19 -0
- package/skills/gate-diagnosing-bugs/SKILL.md +143 -0
- package/skills/gate-diagnosing-bugs/scripts/hitl-loop.template.sh +44 -0
- package/skills/gate-domain-modeling/CONTEXT-FORMAT.md +64 -0
- package/skills/gate-domain-modeling/GLOSSARY-FORMAT.md +64 -0
- package/skills/gate-domain-modeling/SKILL.md +47 -0
- package/skills/gate-fix-bug/SKILL.md +99 -0
- package/skills/gate-fix-bug/assets/worker-briefs/fix-bug-review.md +23 -0
- package/skills/gate-fix-bug/assets/worker-briefs/gate-fix-bug.md +33 -0
- package/skills/gate-handoff/SKILL.md +20 -0
- package/skills/gate-implement/SKILL.md +82 -0
- package/skills/gate-implement/assets/worker-briefs/gate-enter-implement.md +24 -0
- package/skills/gate-implement/tickets.md +114 -0
- package/skills/gate-plan-review/SKILL.md +87 -0
- package/skills/gate-plan-review/assets/worker-briefs/plan-review.md +19 -0
- package/skills/gate-planning/SKILL.md +96 -0
- package/skills/gate-planning/assets/worker-briefs/gate-enter-plan.md +24 -0
- package/skills/gate-planning/proposal.md +51 -0
- package/skills/gate-planning/rfc.md +73 -0
- package/skills/gate-playwright-e2e/SKILL.md +178 -0
- package/skills/gate-playwright-e2e/reference/config.md +129 -0
- package/skills/gate-playwright-e2e/reference/patterns.md +83 -0
- package/skills/gate-prd/SKILL.md +42 -0
- package/skills/gate-research/SKILL.md +17 -0
- package/skills/gate-tdd/SKILL.md +39 -0
- package/skills/gate-tdd/mocking.md +61 -0
- package/skills/gate-tdd/tests.md +79 -0
- package/skills/gate-user-verify/DIAGNOSE.md +75 -0
- package/skills/gate-user-verify/SKILL.md +185 -0
- package/skills/gate-user-verify/assets/worker-briefs/gate-code-verify.md +32 -0
- package/skills/gate-verify/SKILL.md +73 -0
- package/skills/gate-verify/assets/worker-briefs/gate-verify.md +21 -0
- package/skills/gate-write-agent-notes/SKILL.md +199 -0
- package/skills/gate-write-agent-notes/assets/agent-notes-board.html +1779 -0
- package/skills/gate-write-agent-notes/references/archiving.md +113 -0
- package/skills/gate-write-agent-notes/references/classification.md +34 -0
- package/skills/gate-write-agent-notes/references/note-format.md +72 -0
- package/skills/gate-write-agent-notes/references/prose-checklist.md +52 -0
- package/skills/gate-write-agent-notes/references/quality-gate.md +60 -0
- package/skills/gate-write-agent-notes/references/simplification-checklist.md +27 -0
- package/skills/gate-write-agent-notes/references/verification.md +47 -0
- package/skills/gate-write-agent-notes/references/when-to-write.md +86 -0
- package/skills/gate-write-agent-notes/scripts/agent-note-tree.ts +85 -0
- package/skills/gate-write-agent-notes/scripts/archive-agent-note.ts +218 -0
- package/skills/gate-write-agent-notes/scripts/build-board.ts +240 -0
- package/skills/gate-write-agent-notes/scripts/check-note-anchors.ts +105 -0
- package/skills/gate-write-agent-notes/scripts/verify-agent-note-format.ts +158 -0
- package/skills/gate-write-agent-notes/scripts/verify-agent-note-lifecycle.ts +74 -0
- package/skills/gate-write-agent-notes/scripts/verify-agent-note-tree.ts +56 -0
- package/skills/gate-write-agent-notes/scripts/verify-archived-agent-notes.ts +127 -0
- package/skills/gate-write-agent-notes/templates/implemented.md +35 -0
- package/skills/gate-write-agent-notes/templates/proposed.md +41 -0
- package/skills/gate-write-agent-notes/templates/rejected.md +30 -0
- package/skills/gate-writing-for-agents/SKILL-MECHANICS.md +24 -0
- package/skills/gate-writing-for-agents/SKILL.md +85 -0
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gate-playwright-e2e
|
|
3
|
+
description: 为一个项目配置 Playwright E2E——装依赖、写 config、把「验证只走 playwright test」落进 AGENTS.md、写出第一个 spec。
|
|
4
|
+
argument-hint: "项目路径,或要覆盖的功能 / bug"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Playwright E2E 配置
|
|
8
|
+
|
|
9
|
+
分工是固定的:**Agent 写 spec,Playwright runner 跑 spec。** 提需求的这一轮里,Agent 不打开浏览器一格格点页面——那是它最贵、最慢、最不可回归的用法;它只写 Node.js + Playwright 脚本,然后跑命令。脚本一旦落盘,「这个功能对不对」就从一轮轮截图变成一条几秒钟、几乎不花 token、随时可重跑的断言。
|
|
10
|
+
|
|
11
|
+
这个 skill 一次跑完,产出三样**落盘**的东西:可跑的 `playwright.config.ts`、项目里长期生效的测试规则、覆盖目标行为的 spec。之后日常由项目里的规则接管,换项目、换技术栈、或规则要改的时候再调它。
|
|
12
|
+
|
|
13
|
+
## 闸门:这件事归 Playwright 吗
|
|
14
|
+
|
|
15
|
+
进来先分一次工,别把整个项目铺成 spec。判据一句话:**这个改动的正确性,是否只有通过真实浏览器才观测得到?** 答「是」的才写 spec;答「不是」的走下面右列那一层,更快也更准。
|
|
16
|
+
|
|
17
|
+
| 要验的东西 | 归谁 |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| UI 行为:路由守卫、表单校验与联动、弹窗抽屉、分页筛选、状态回填 | spec |
|
|
20
|
+
| 全栈串联:登录 → 下单 → 后台看到订单;不同权限看到不同菜单 | spec |
|
|
21
|
+
| 只有浏览器里才成立的:cookie / session / localStorage、CORS、重定向链、OAuth 回调落地、SSE / WebSocket 的界面表现 | spec |
|
|
22
|
+
| 浏览器专属能力:上传下载、拖拽、剪贴板、iframe、多标签页 | spec |
|
|
23
|
+
| 构建产物级 bug:只有 `build` 后才有的水合失败、静态资源 404 | spec(服务用 `command: 'pnpm build && pnpm preview'`) |
|
|
24
|
+
| 回归护栏:重构后功能仍在——它最值钱的一类 | spec,只覆盖关键路径 |
|
|
25
|
+
| 纯函数、算法、数据转换、后端业务逻辑 | 单元测试(vitest / jest / pytest) |
|
|
26
|
+
| 接口契约、状态码、鉴权规则 | 直接打 HTTP 的集成测试(supertest / pytest) |
|
|
27
|
+
| CLI、SDK、库 | 各自的单元 / 集成测试 |
|
|
28
|
+
| 原生移动端 App | Appium / Maestro |
|
|
29
|
+
| 性能压测、Lighthouse 审计 | k6 / Lighthouse |
|
|
30
|
+
| 好不好看、间距对不对 | 人眼:列成清单加 Todo 交给人验 |
|
|
31
|
+
|
|
32
|
+
三个边界要当场说清,否则后面会一直红或白配一套:
|
|
33
|
+
|
|
34
|
+
- 项目里根本没有浏览器可达的界面(纯 CLI、纯库、纯后端):本技能到此为止,直接告诉用户该走哪一层。
|
|
35
|
+
- Electron 和浏览器扩展 Playwright 也支持,但配置形状不同(`_electron.launch()` / `--load-extension`),不是这份 config 的形状;要测就单独配。
|
|
36
|
+
- 第三方登录、验证码、短信、支付:不是不归它,是**先得有测试环境的后门或桩**(见 [reference/patterns.md](reference/patterns.md) 的网络桩),否则脚本永远红。
|
|
37
|
+
|
|
38
|
+
**完成判据**:这次要验的每一条都能说出归哪一层;判给 spec 的那些列出来,作为第 4 步的输入。
|
|
39
|
+
|
|
40
|
+
## 0. 从项目里读事实
|
|
41
|
+
|
|
42
|
+
先确定四件事,全部来自文件,不许凭印象填:
|
|
43
|
+
|
|
44
|
+
| 事实 | 从哪读 |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| 包管理器 | 锁文件:`pnpm-lock.yaml` / `yarn.lock` / `package-lock.json` / `bun.lockb` |
|
|
47
|
+
| 起开发服务的命令和端口 | `package.json` 的 `scripts`、`.env`、框架约定的默认端口 |
|
|
48
|
+
| 是否已有 Playwright | 依赖里的 `@playwright/test`、`playwright.config.*`、`tests/`、`e2e/` |
|
|
49
|
+
| 目标行为是否要登录态 | 路由和中间件、现有 spec 里的 `storageState` |
|
|
50
|
+
|
|
51
|
+
**完成判据**:四件事都能指到具体文件;下面每一步的命令都直接用这些事实拼出来,不再回头问用户。
|
|
52
|
+
|
|
53
|
+
## 1. 装 Playwright 与浏览器
|
|
54
|
+
|
|
55
|
+
Playwright **不用系统浏览器**:它按自己的版本号下载专用构建到系统缓存(Windows `%USERPROFILE%\AppData\Local\ms-playwright`,macOS `~/Library/Caches/ms-playwright`,Linux `~/.cache/ms-playwright`)。**Playwright 版本和浏览器构建是绑定的**,升级 `@playwright/test` 之后要重跑 `install`;机器上装没装 Chrome 与它无关。
|
|
56
|
+
|
|
57
|
+
**装在哪**:`@playwright/test` 装进项目的 `devDependencies`——它决定浏览器版本,必须和 CI 一致,所以不要全局装(本地没装时 `npx` 会去下载一份临时版本,静默换掉版本)。浏览器相反:只有一份,装在机器级缓存里被所有项目共享,不必也无法按项目隔离,更不要为了「干净」重下一次。
|
|
58
|
+
|
|
59
|
+
依赖里没有 `@playwright/test` 才装(已有就跳过),并装上这次要用的浏览器:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pnpm create playwright # 或 npm init playwright@latest
|
|
63
|
+
npx playwright install chromium
|
|
64
|
+
npx playwright install --dry-run # 只打印:装到哪、从哪个 URL 下载,不下载
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`install` 幂等,已经有了会直接跳过,所以通常「直接装」比「先检测再装」更省事;要确认现状就用 `--dry-run` 和 `--list`。按情况选:
|
|
68
|
+
|
|
69
|
+
| 情况 | 命令 |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| 本地只跑无头 | `npx playwright install chromium --only-shell`(不装完整 Chromium:win64 上 205MB → 120MB) |
|
|
72
|
+
| CI | `npx playwright install --with-deps chromium`(`--with-deps` 一并装 Linux 系统依赖) |
|
|
73
|
+
| 要跨浏览器 | `npx playwright install chromium firefox webkit` |
|
|
74
|
+
| 国内下载慢 | `PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright`(已验证同步 cft 新路径,与官方同一份文件);仍慢再加 `PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000` |
|
|
75
|
+
| 走公司代理 / 内网镜像 | `HTTPS_PROXY=...`、`PLAYWRIGHT_DOWNLOAD_HOST=<内网地址>`;证书报错加 `NODE_EXTRA_CA_CERTS` |
|
|
76
|
+
| 缓存位置要固定(容器、多版本共存) | `PLAYWRIGHT_BROWSERS_PATH=/path`;设成 `0` 则装进 `node_modules`,做 hermetic 安装 |
|
|
77
|
+
|
|
78
|
+
两个下载源互相独立,别搞混:`pnpm add -D @playwright/test` 走 npm registry(慢就换 `registry.npmmirror.com`),浏览器二进制走微软 CDN(要设 `PLAYWRIGHT_DOWNLOAD_HOST`)。配了一个不影响另一个。
|
|
79
|
+
|
|
80
|
+
**要不要改用机器上的 Chrome / Edge**:默认不要。需要对着用户实际在用的浏览器做回归、或涉及媒体编解码器差异时,给 project 加 `channel: 'chrome'` / `channel: 'msedge'`,运行时用的就是系统里装的品牌浏览器(注意 `npx playwright install msedge` 会装到操作系统的全局默认位置并覆盖现有安装)。Firefox 和 WebKit 没有这条路——Playwright 用的是自己打过补丁的构建,品牌版 Firefox / Safari 跑不了。
|
|
81
|
+
|
|
82
|
+
**完成判据**:`npx playwright install --list` 里能看到这次要用的浏览器,且 `npx playwright --version` 有输出。
|
|
83
|
+
|
|
84
|
+
## 2. 写 `playwright.config.ts`
|
|
85
|
+
|
|
86
|
+
配置的任务只有一个:**一条命令自己把服务拉起来、跑完、留下产物**。骨架(命令和端口换成第 0 步读到的事实):
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { defineConfig, devices } from '@playwright/test'
|
|
90
|
+
|
|
91
|
+
export default defineConfig({
|
|
92
|
+
testDir: './tests',
|
|
93
|
+
use: {
|
|
94
|
+
baseURL: 'http://localhost:3000',
|
|
95
|
+
trace: 'on-first-retry',
|
|
96
|
+
screenshot: 'only-on-failure',
|
|
97
|
+
},
|
|
98
|
+
projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
|
|
99
|
+
webServer: {
|
|
100
|
+
command: 'pnpm dev',
|
|
101
|
+
url: 'http://localhost:3000',
|
|
102
|
+
reuseExistingServer: !process.env.CI,
|
|
103
|
+
},
|
|
104
|
+
})
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
服务已经在别处跑、monorepo 多服务、跨 spec 复用登录态、CI 的 retries / 分片 / 报告、GitHub Actions workflow——按分支读 [reference/config.md](reference/config.md)。
|
|
108
|
+
|
|
109
|
+
**完成判据**:`npx playwright test --list` 找得到测试目录,且不用人手先开一个终端——`webServer` 能自己把服务起起来。
|
|
110
|
+
|
|
111
|
+
## 3. 把规则落盘进项目
|
|
112
|
+
|
|
113
|
+
写进项目**已经在用**的那个 agent 指令文件(`AGENTS.md` 优先,其次 `CLAUDE.md`、`.cursorrules`);都没有就新建 `AGENTS.md`。整块贴进去:
|
|
114
|
+
|
|
115
|
+
```md
|
|
116
|
+
## E2E 测试规则
|
|
117
|
+
|
|
118
|
+
1. UI 行为的验证一律跑 `npx playwright test`;只跑一个文件就 `npx playwright test tests/xxx.spec.ts`。
|
|
119
|
+
2. 每个新功能或 bugfix 都要带一个能复现它的 spec(`tests/**/*.spec.ts`),和业务代码一起提交。
|
|
120
|
+
3. 脚本失败时按这个顺序走:先让脚本稳定复现问题(红)→ 给关键请求、状态、时序加日志,把步骤拆小 → 改业务代码 → 重跑同一条脚本,直到绿。
|
|
121
|
+
4. 选择器用 `getByRole` / `getByLabel` / `getByTestId`;缺稳定锚点就在组件上补 `data-testid`,不用脆弱的 CSS 层级。
|
|
122
|
+
5. 不写 UI 单元测试(按钮渲染、className、快照);UI 行为由 spec 覆盖。
|
|
123
|
+
6. 浏览器工具和 MCP 用来看产物——`npx playwright show-trace`、失败截图、`npx playwright show-report`;驱动页面的事务归 Playwright runner。
|
|
124
|
+
7. 需要人眼判断的视觉细节,列成清单加 Todo 交给人验,不假装脚本能替人判断好不好看。
|
|
125
|
+
8. 业务逻辑、纯函数、接口契约仍然由各自的单元 / 集成测试覆盖;spec 只负责只有浏览器能观测到的那部分。
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**完成判据**:规则块出现在项目实际使用的那个文件里,`git diff` 里看得见。
|
|
129
|
+
|
|
130
|
+
## 4. 写第一个 spec
|
|
131
|
+
|
|
132
|
+
覆盖用户这次点名的功能或 bug。脚本里全是确定步骤,没有「试试看」:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
import { test, expect } from '@playwright/test'
|
|
136
|
+
|
|
137
|
+
test('用户可以登录并进入工作台', async ({ page }) => {
|
|
138
|
+
await page.goto('/login')
|
|
139
|
+
|
|
140
|
+
await page.getByLabel('邮箱').fill('demo@example.com')
|
|
141
|
+
await page.getByLabel('密码').fill('password123')
|
|
142
|
+
await page.getByRole('button', { name: '登录' }).click()
|
|
143
|
+
|
|
144
|
+
await expect(page).toHaveURL(/\/dashboard/)
|
|
145
|
+
await expect(page.getByRole('heading', { name: '工作台' })).toBeVisible()
|
|
146
|
+
})
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
需要登录态、网络桩、文件上传、拆步骤、调试开关时读 [reference/patterns.md](reference/patterns.md)。
|
|
150
|
+
|
|
151
|
+
修 bug 时顺序是**先红后绿**:spec 先跑成失败,确认它复现的正是用户报的那个问题,再动业务代码。
|
|
152
|
+
|
|
153
|
+
**完成判据**:spec 覆盖闸门判给它的每一条行为;第一次运行的结果是绿,或是因为真实缺陷而红——没有因为「选择器还没定」而 `test.skip` 的用例。
|
|
154
|
+
|
|
155
|
+
## 5. 跑,红就修,直到连续两次绿
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
npx playwright test tests/xxx.spec.ts
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
红的处理顺序固定:
|
|
162
|
+
|
|
163
|
+
1. 读产物:`npx playwright show-trace test-results/<...>/trace.zip`、失败截图、`npx playwright show-report`。
|
|
164
|
+
2. 给关键请求、状态、时序加日志,或把大测试拆成更小步骤。
|
|
165
|
+
3. 改业务代码。
|
|
166
|
+
4. 重跑**同一条命令**。
|
|
167
|
+
|
|
168
|
+
**完成判据**:同一条命令连跑两次都绿,不靠 retries 兜底。
|
|
169
|
+
|
|
170
|
+
## 6. 接进 CI(项目有 CI 才做)
|
|
171
|
+
|
|
172
|
+
把 `npx playwright install --with-deps`、`npx playwright test`、`playwright-report/` 产物上传写进现有 workflow;失败重试、分片、报告配置见 [reference/config.md](reference/config.md)。
|
|
173
|
+
|
|
174
|
+
**完成判据**:`CI=1 npx playwright test` 在本地通过(PowerShell 用 `$env:CI=1; npx playwright test`),且 workflow 文件落盘。
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# Playwright 配置参考
|
|
2
|
+
|
|
3
|
+
按项目形状读对应分支。骨架在 [SKILL.md](../SKILL.md) 第 2 步。
|
|
4
|
+
|
|
5
|
+
## 先判断服务怎么起
|
|
6
|
+
|
|
7
|
+
| 项目形状 | config 怎么写 |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| 一条命令能起服务(`pnpm dev` / `npm run dev`) | `webServer.command` 交给 Playwright 自己拉起来 |
|
|
10
|
+
| 开发机上服务已经常驻 | `reuseExistingServer: true`,`url` 指过去;CI 上仍写成能自己起 |
|
|
11
|
+
| 服务由 docker compose 起 | `command: 'docker compose up web'`,`timeout: 120_000`,`url` 用容器映射出的宿主端口 |
|
|
12
|
+
| 前后端两个服务 | `webServer` 写数组,每个服务一项 |
|
|
13
|
+
| 只测构建产物 | `command: 'pnpm build && pnpm preview'` |
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
webServer: {
|
|
17
|
+
command: 'pnpm dev',
|
|
18
|
+
cwd: '.', // monorepo 里指到子包
|
|
19
|
+
url: 'http://localhost:3000', // 比 port 准:等到真的能响应
|
|
20
|
+
timeout: 120_000, // 冷启动慢的框架给足
|
|
21
|
+
reuseExistingServer: !process.env.CI,
|
|
22
|
+
stdout: 'pipe', // 服务起不来时能看到它的日志
|
|
23
|
+
env: { NODE_ENV: 'test' },
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
端口从项目里读(`package.json`、`.env`、框架默认值),不要照抄示例的 3000。
|
|
28
|
+
|
|
29
|
+
## 完整 config 模板
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
import { defineConfig, devices } from '@playwright/test'
|
|
33
|
+
|
|
34
|
+
export default defineConfig({
|
|
35
|
+
testDir: './tests',
|
|
36
|
+
outputDir: './test-results', // trace / 截图 / 视频落盘处,加进 .gitignore
|
|
37
|
+
fullyParallel: true,
|
|
38
|
+
forbidOnly: !!process.env.CI, // CI 上留着 test.only 直接失败
|
|
39
|
+
retries: process.env.CI ? 2 : 0,
|
|
40
|
+
workers: process.env.CI ? 1 : undefined, // CI 官方建议串行换稳定;要并行就上分片
|
|
41
|
+
reporter: process.env.CI
|
|
42
|
+
? [['blob'], ['github']] // blob 供分片后 merge-reports
|
|
43
|
+
: [['list'], ['html', { open: 'never' }]],
|
|
44
|
+
|
|
45
|
+
timeout: 30_000,
|
|
46
|
+
expect: { timeout: 5_000 }, // 断言级超时,比到处 sleep 靠谱
|
|
47
|
+
globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
|
|
48
|
+
// CI 上必须有上限:否则挂死的 run 被 runner 杀掉,连报告都留不下
|
|
49
|
+
|
|
50
|
+
use: {
|
|
51
|
+
baseURL: process.env.E2E_BASE_URL ?? 'http://localhost:3000',
|
|
52
|
+
trace: 'on-first-retry',
|
|
53
|
+
screenshot: 'only-on-failure',
|
|
54
|
+
video: 'retain-on-failure',
|
|
55
|
+
locale: 'zh-CN',
|
|
56
|
+
timezoneId: 'Asia/Shanghai',
|
|
57
|
+
},
|
|
58
|
+
|
|
59
|
+
projects: [
|
|
60
|
+
{ name: 'setup', testMatch: /auth\.setup\.ts/ },
|
|
61
|
+
{
|
|
62
|
+
name: 'chromium',
|
|
63
|
+
use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/user.json' },
|
|
64
|
+
dependencies: ['setup'],
|
|
65
|
+
},
|
|
66
|
+
// 需要移动端 / 多浏览器时再加:
|
|
67
|
+
// { name: 'mobile', use: { ...devices['Pixel 7'] } },
|
|
68
|
+
],
|
|
69
|
+
|
|
70
|
+
webServer: {
|
|
71
|
+
command: 'pnpm dev',
|
|
72
|
+
url: 'http://localhost:3000',
|
|
73
|
+
reuseExistingServer: !process.env.CI,
|
|
74
|
+
timeout: 120_000,
|
|
75
|
+
},
|
|
76
|
+
})
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
用不到的项删掉——一份没人读得完的 config 会在第一次报错时耽误时间。Playwright 不自动读 `.env`,需要就 `pnpm add -D dotenv` 并在 config 顶部 `import 'dotenv/config'`。
|
|
80
|
+
|
|
81
|
+
## 跨 spec 复用登录态
|
|
82
|
+
|
|
83
|
+
`tests/auth.setup.ts`:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import { test as setup, expect } from '@playwright/test'
|
|
87
|
+
|
|
88
|
+
setup('登录并保存 storageState', async ({ page }) => {
|
|
89
|
+
await page.goto('/login')
|
|
90
|
+
await page.getByLabel('邮箱').fill(process.env.E2E_USER!)
|
|
91
|
+
await page.getByLabel('密码').fill(process.env.E2E_PASSWORD!)
|
|
92
|
+
await page.getByRole('button', { name: '登录' }).click()
|
|
93
|
+
await expect(page).toHaveURL(/\/dashboard/)
|
|
94
|
+
await page.context().storageState({ path: 'playwright/.auth/user.json' })
|
|
95
|
+
})
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`playwright/.auth/` 加进 `.gitignore`;凭据走环境变量,不写进 spec。
|
|
99
|
+
|
|
100
|
+
## CI
|
|
101
|
+
|
|
102
|
+
GitHub Actions:
|
|
103
|
+
|
|
104
|
+
```yaml
|
|
105
|
+
jobs:
|
|
106
|
+
e2e:
|
|
107
|
+
runs-on: ubuntu-latest
|
|
108
|
+
steps:
|
|
109
|
+
- uses: actions/checkout@v6
|
|
110
|
+
- uses: actions/setup-node@v6
|
|
111
|
+
with: { node-version: 22, cache: pnpm }
|
|
112
|
+
- run: pnpm install --frozen-lockfile
|
|
113
|
+
- run: npx playwright install --with-deps chromium
|
|
114
|
+
- run: pnpm exec playwright test
|
|
115
|
+
- uses: actions/upload-artifact@v5
|
|
116
|
+
if: ${{ !cancelled() }}
|
|
117
|
+
with:
|
|
118
|
+
name: playwright-report
|
|
119
|
+
path: playwright-report/
|
|
120
|
+
retention-days: 7
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
- 分片:`npx playwright test --shard=${{ matrix.shard }}/4`,矩阵开 4 份 job,各上传 `blob-report/`,最后一份 job 里 `npx playwright merge-reports --reporter=html ./all-blob-reports`。
|
|
124
|
+
- 本地预演 CI:`CI=1 npx playwright test`(PowerShell:`$env:CI=1; npx playwright test`),重点看 retries 关掉后还绿不绿。
|
|
125
|
+
- 只在该跑的时候跑:用 `paths` 过滤,或给 spec 打 tag,PR 上 `--grep @smoke`,合并后再跑全量。
|
|
126
|
+
- 不要缓存浏览器二进制:官方明确不推荐——还原缓存的时间和重新下载差不多,而且 Linux 的系统依赖本来就缓存不了。真要缓存,key 里必须带 Playwright 版本号。
|
|
127
|
+
- 不要给 workflow 设比 `globalTimeout` 更短的 `timeout-minutes`:要让 Playwright 自己先停,报告才留得下来。
|
|
128
|
+
|
|
129
|
+
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# spec 写法参考
|
|
2
|
+
|
|
3
|
+
目标只有一个:**同一条命令每次跑都走到同一个结果**。不确定的地方用断言等它确定,不用 sleep 赌它。
|
|
4
|
+
|
|
5
|
+
## 选择器
|
|
6
|
+
|
|
7
|
+
优先级从高到低:
|
|
8
|
+
|
|
9
|
+
1. `getByRole('button', { name: '提交订单' })` —— 顺带验证了可访问性
|
|
10
|
+
2. `getByLabel('邮箱')` —— 表单字段
|
|
11
|
+
3. `getByTestId('checkout-submit')` —— 上面两条都不稳时的稳定锚点,组件上补 `data-testid="checkout-submit"`
|
|
12
|
+
4. `getByText('...', { exact: true })` —— 文案断言;文案变了测试就该跟着改
|
|
13
|
+
|
|
14
|
+
`locator('div.card > button:nth-child(2)')` 这类只在没有别的办法时用,它会在下次改样式时红。
|
|
15
|
+
|
|
16
|
+
## 等待与断言
|
|
17
|
+
|
|
18
|
+
用 web-first 断言,Playwright 自己重试到超时:
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
await expect(page.getByRole('heading', { name: '工作台' })).toBeVisible()
|
|
22
|
+
await expect(page.getByTestId('total')).toHaveText('¥128.00')
|
|
23
|
+
await expect(page.getByRole('button', { name: '保存' })).toBeEnabled()
|
|
24
|
+
await expect(page).toHaveURL(/\/dashboard/)
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`await page.waitForTimeout(2000)` 不出现在提交的代码里;替代品是断言、`expect.poll`、或 `await page.waitForResponse(...)`:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
await expect.poll(async () => {
|
|
31
|
+
const res = await page.request.get('/api/jobs/1')
|
|
32
|
+
return (await res.json()).status
|
|
33
|
+
}, { timeout: 15_000 }).toBe('done')
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## 网络
|
|
37
|
+
|
|
38
|
+
把不确定的外部依赖变成确定的:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
await page.route('**/api/recommend', (route) =>
|
|
42
|
+
route.fulfill({ status: 200, json: { items: [] } }))
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- 只桩真正的外部、慢、不稳定的接口;自己的后端尽量跑真的,桩太多就测不到集成问题。
|
|
46
|
+
- 要断言请求确实发出去了:`const [req] = await Promise.all([page.waitForRequest('**/api/orders'), page.getByRole('button', { name: '提交' }).click()])`。
|
|
47
|
+
- 整段网络录制回放:`await context.routeFromHAR('fixtures/api.har', { update: !process.env.CI })`。
|
|
48
|
+
|
|
49
|
+
## 拆步骤
|
|
50
|
+
|
|
51
|
+
一个巨大的 test 红一次要看半小时;拆成并列的小 test,`test.step` 只用来在同一个用例里划分可读阶段:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
test('结算流程', async ({ page }) => {
|
|
55
|
+
await test.step('加入购物车', async () => { /* ... */ })
|
|
56
|
+
await test.step('提交订单', async () => { /* ... */ })
|
|
57
|
+
})
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
每个 test 自建自己需要的数据,互不依赖执行顺序。
|
|
61
|
+
|
|
62
|
+
## 红的时候先看什么
|
|
63
|
+
|
|
64
|
+
| 症状 | 先查 |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| 元素找不到 | `--headed` 跑一次看是否根本没渲染;是不是 strict mode 命中多个选择器(用 `getByRole(..., { name })` 收窄) |
|
|
67
|
+
| 一会儿红一会儿绿 | 有没有裸 `waitForTimeout`;有没有未桩的网络;几个 test 是否抢同一份数据 |
|
|
68
|
+
| 卡在登录 | `storageState` 文件是否存在、setup project 是否真的跑了 |
|
|
69
|
+
| 本地绿 CI 红 | 时区 / 语言 / 字体、`CI=1` 下的 retries、`--with-deps` 装的浏览器是否对得上 |
|
|
70
|
+
| 失败时信息太少 | 临时 `trace: 'on'` 或 `--trace on`,再 `npx playwright show-trace test-results/**/trace.zip` |
|
|
71
|
+
|
|
72
|
+
## 调试开关
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npx playwright test tests/x.spec.ts --headed --debug # 单步
|
|
76
|
+
npx playwright test tests/x.spec.ts --trace on # 每次都留 trace
|
|
77
|
+
npx playwright show-report # HTML 报告
|
|
78
|
+
npx playwright test --ui # 本地交互式跑
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
浏览器工具 / MCP 到这里为止:用来看 trace 和报告;驱动页面仍然交给 `npx playwright test`。
|
|
82
|
+
|
|
83
|
+
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gate-prd
|
|
3
|
+
description: 按用户要求创建或更新 PRD,明确用户问题、产品目标、价值、目标人群与产品级边界。
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# PRD
|
|
8
|
+
|
|
9
|
+
仅在用户显式调用本技能时创建或更新 PRD。PRD 用来澄清“为什么做、为谁做、解决什么问题”,不自动进入工程 Planning,也不构成批准或执行授权。
|
|
10
|
+
|
|
11
|
+
## 位置与复用
|
|
12
|
+
|
|
13
|
+
遵循项目文档分层和既有 PRD 格式。优先更新同一产品主题已有的 PRD;没有已配置的存放位置时,先在对话中起草并请用户决定位置,不自行发布到外部系统。
|
|
14
|
+
|
|
15
|
+
## 内容
|
|
16
|
+
|
|
17
|
+
按产品问题需要写清:
|
|
18
|
+
|
|
19
|
+
- 用户或业务问题;
|
|
20
|
+
- 目标人群与使用情境;
|
|
21
|
+
- 产品目标、价值和成功信号;
|
|
22
|
+
- 产品级范围与非目标;
|
|
23
|
+
- 重要约束、风险与未解决问题;
|
|
24
|
+
- 与已有产品能力的关系。
|
|
25
|
+
|
|
26
|
+
保持产品层表达,不写模块划分、数据库结构、内部接口或实现方案。
|
|
27
|
+
|
|
28
|
+
## 与工程工件的关系
|
|
29
|
+
|
|
30
|
+
PRD 可以作为 Proposal 与 Spec 的背景输入,但不能代替某项工程工作的明确产品合同。
|
|
31
|
+
|
|
32
|
+
进入工程 Planning 后:
|
|
33
|
+
|
|
34
|
+
- Proposal 或既有工作项选择本次交付范围,写清产品行为与验收并维护状态;
|
|
35
|
+
- 跨工作项持续生效的行为合同按需由独立 Spec 就地写清范围、非目标和验收;
|
|
36
|
+
- Agent Note 承接产品合同,负责长期技术设计与决定。
|
|
37
|
+
|
|
38
|
+
不要为了形成完整链条而自动创建 Proposal、Spec 或设计记录。用户只要求 PRD 时,交付 PRD 后结束。
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gate-research
|
|
3
|
+
description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Spin up a **background agent** to do the research, so you keep working while it reads.
|
|
8
|
+
|
|
9
|
+
Its job:
|
|
10
|
+
|
|
11
|
+
1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
|
|
12
|
+
2. Write the findings to a single Markdown file, citing each claim's source.
|
|
13
|
+
3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gate-tdd
|
|
3
|
+
description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Test-Driven Development
|
|
8
|
+
|
|
9
|
+
TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
|
|
10
|
+
|
|
11
|
+
Use the domain glossary identified by project instructions for test names and interface vocabulary. Derive test expectations from the work item's acceptance contract and applicable constraints. Report missing or conflicting required inputs and the affected behavior before encoding its expected result.
|
|
12
|
+
|
|
13
|
+
## What a good test is
|
|
14
|
+
|
|
15
|
+
Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
|
|
16
|
+
|
|
17
|
+
See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
|
|
18
|
+
|
|
19
|
+
## Seams — where tests go
|
|
20
|
+
|
|
21
|
+
A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
|
|
22
|
+
|
|
23
|
+
Use seams already approved in the spec/ticket without asking again. During authorized implementation, if none is specified, reuse existing public interfaces and test patterns and record the choice. Ask only when selecting a seam requires a new or changed interface, acceptance contract, or scope decision. This does not grant implementation authority or override a project's explicit approval requirements.
|
|
24
|
+
|
|
25
|
+
When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — call the Skill tool with "codebase-design" for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
|
|
26
|
+
|
|
27
|
+
## Anti-patterns
|
|
28
|
+
|
|
29
|
+
- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
|
|
30
|
+
- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
|
|
31
|
+
- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
|
|
32
|
+
|
|
33
|
+
## Rules of the loop
|
|
34
|
+
|
|
35
|
+
- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
|
|
36
|
+
- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
|
|
37
|
+
- **Refactoring is not part of the loop.** It belongs to the review stage (see the `gate-code-review` skill), not the red → green implementation cycle.
|
|
38
|
+
|
|
39
|
+
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# When to Mock
|
|
2
|
+
|
|
3
|
+
Mock at **system boundaries** only:
|
|
4
|
+
|
|
5
|
+
- External APIs (payment, email, etc.)
|
|
6
|
+
- Databases (sometimes - prefer test DB)
|
|
7
|
+
- Time/randomness
|
|
8
|
+
- File system (sometimes)
|
|
9
|
+
|
|
10
|
+
Don't mock:
|
|
11
|
+
|
|
12
|
+
- Your own classes/modules
|
|
13
|
+
- Internal collaborators
|
|
14
|
+
- Anything you control
|
|
15
|
+
|
|
16
|
+
## Designing for Mockability
|
|
17
|
+
|
|
18
|
+
At system boundaries, design interfaces that are easy to mock:
|
|
19
|
+
|
|
20
|
+
**1. Use dependency injection**
|
|
21
|
+
|
|
22
|
+
Pass external dependencies in rather than creating them internally:
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
// Easy to mock
|
|
26
|
+
function processPayment(order, paymentClient) {
|
|
27
|
+
return paymentClient.charge(order.total);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
// Hard to mock
|
|
31
|
+
function processPayment(order) {
|
|
32
|
+
const client = new StripeClient(process.env.STRIPE_KEY);
|
|
33
|
+
return client.charge(order.total);
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**2. Prefer SDK-style interfaces over generic fetchers**
|
|
38
|
+
|
|
39
|
+
Create specific functions for each external operation instead of one generic function with conditional logic:
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
// GOOD: Each function is independently mockable
|
|
43
|
+
const api = {
|
|
44
|
+
getUser: (id) => fetch(`/users/${id}`),
|
|
45
|
+
getOrders: (userId) => fetch(`/users/${userId}/orders`),
|
|
46
|
+
createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
// BAD: Mocking requires conditional logic inside the mock
|
|
50
|
+
const api = {
|
|
51
|
+
fetch: (endpoint, options) => fetch(endpoint, options),
|
|
52
|
+
};
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The SDK approach means:
|
|
56
|
+
- Each mock returns one specific shape
|
|
57
|
+
- No conditional logic in test setup
|
|
58
|
+
- Easier to see which endpoints a test exercises
|
|
59
|
+
- Type safety per endpoint
|
|
60
|
+
|
|
61
|
+
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Good and Bad Tests
|
|
2
|
+
|
|
3
|
+
## Good Tests
|
|
4
|
+
|
|
5
|
+
**Integration-style**: Test through real interfaces, not mocks of internal parts.
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
// GOOD: Tests observable behavior
|
|
9
|
+
test("user can checkout with valid cart", async () => {
|
|
10
|
+
const cart = createCart();
|
|
11
|
+
cart.add(product);
|
|
12
|
+
const result = await checkout(cart, paymentMethod);
|
|
13
|
+
expect(result.status).toBe("confirmed");
|
|
14
|
+
});
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Characteristics:
|
|
18
|
+
|
|
19
|
+
- Tests behavior users/callers care about
|
|
20
|
+
- Uses public API only
|
|
21
|
+
- Survives internal refactors
|
|
22
|
+
- Describes WHAT, not HOW
|
|
23
|
+
- One logical assertion per test
|
|
24
|
+
|
|
25
|
+
## Bad Tests
|
|
26
|
+
|
|
27
|
+
**Implementation-detail tests**: Coupled to internal structure.
|
|
28
|
+
|
|
29
|
+
```typescript
|
|
30
|
+
// BAD: Tests implementation details
|
|
31
|
+
test("checkout calls paymentService.process", async () => {
|
|
32
|
+
const mockPayment = jest.mock(paymentService);
|
|
33
|
+
await checkout(cart, payment);
|
|
34
|
+
expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Red flags:
|
|
39
|
+
|
|
40
|
+
- Mocking internal collaborators
|
|
41
|
+
- Testing private methods
|
|
42
|
+
- Asserting on call counts/order
|
|
43
|
+
- Test breaks when refactoring without behavior change
|
|
44
|
+
- Test name describes HOW not WHAT
|
|
45
|
+
- Verifying through external means instead of interface
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
// BAD: Bypasses interface to verify
|
|
49
|
+
test("createUser saves to database", async () => {
|
|
50
|
+
await createUser({ name: "Alice" });
|
|
51
|
+
const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
|
|
52
|
+
expect(row).toBeDefined();
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
// GOOD: Verifies through interface
|
|
56
|
+
test("createUser makes user retrievable", async () => {
|
|
57
|
+
const user = await createUser({ name: "Alice" });
|
|
58
|
+
const retrieved = await getUser(user.id);
|
|
59
|
+
expect(retrieved.name).toBe("Alice");
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
// BAD: Expected value is recomputed the way the code computes it
|
|
67
|
+
test("calculateTotal sums line items", () => {
|
|
68
|
+
const items = [{ price: 10 }, { price: 5 }];
|
|
69
|
+
const expected = items.reduce((sum, i) => sum + i.price, 0);
|
|
70
|
+
expect(calculateTotal(items)).toBe(expected);
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
// GOOD: Expected value is an independent, known literal
|
|
74
|
+
test("calculateTotal sums line items", () => {
|
|
75
|
+
expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
|
|
76
|
+
});
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
|