拆webapp-testing：说明书教你别读代码

概述

本栏目此前盘点测试类 Skills 时，曾感叹这条赛道是间「空屋」——大量测试件无人认领、装了没人用。但空屋的门后其实一直住着一件官方货：Anthropic example-skills 里的 webapp-testing。它是官方全家桶里最不起眼、也最值得拆的一件：全文不到一百行，却有整整两段在阻止模型读代码；它不用一张图、不写一句废话，把「上下文窗口是预算」这件事执行到了字节级。本文基于 2026-09-19 从本机 Claude Code 插件缓存加载的 SKILL.md 当前版本全文，逐段拆到行，最后给出可直接抄走的七条写法。

评测表

加权总分约 4.3 / 5。短板集中在「社区活跃度」——它压根没有自己的社区，它是基础设施。

三条路线对比：它到底替你省了什么

同样的「让 Claude 测网页」，市场上有三条路。先把它们摆在一起，后面拆的每一行设计才有参照物：

MCP 路线的问题是账单：点十个按钮就是十次工具往返，每次往返的页面状态都挤进上下文。Skill 路线反着来——Claude 把十步动作写进一个 Python 文件，一次执行，只把最终结论带回对话。这是「每步一个工具」和「一步一个脚本」的架构分歧，也是这件 Skill 存在的全部理由。

逐段拆解：不到一百行的九个心机

第一行就是命令，没有一句铺垫

全文开篇：

To test local web applications, write native Python Playwright scripts.

翻译过来八个词：测本地 Web 应用，写原生 Python Playwright 脚本。注意三件事：第一，它是祈使句，动词开头，模型读到第一行就知道自己该「做什么动作」；第二，native Python Playwright 三个定语一口气锁死技术栈，不给模型发挥空间——不写 Selenium，不写 requests，不问要不要装 Cypress；第三，全文没有任何「This skill aims to...」式的自我介绍。对比大量社区 SKILL.md 开头两段讲背景讲愿景，这件的第一行已经在干活。省下来的每一行，都是上下文预算。

Helper Scripts 声明 + 全文最狠的一条

紧接着是资源声明和这段罕见的指令：

Always run scripts with --help first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary.

一个大写的 DO NOT。这份说明书用最重的语气告诉读者：别读我附带的代码。理由写在下一句：

These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.

这是整份文件的设计内核：SKILL.md 的作者非常清楚模型有个本能——拿到代码就想读一遍再动手。而这个「附带的 with_server.py」是管服务器生死的长脚本，读一遍几千 token 就没了，读完还未必用得上。于是作者把规矩写死：先跑 --help 看用法，直接当黑盒调；只有跑不通、确认必须魔改时才准打开源码。

顺带一个细节：这句里 abslutely 是拼错的（应为 absolutely）。官方文件、人手写、没过一遍拼写检查——反而说明这不是模板批量生成的货。

ASCII 决策树：图都不画，因为读者是模型

文件的核心段是一棵纯文本决策树：

User task → Is it static HTML?
    ├─ Yes → Read HTML file directly to identify selectors
    │         ├─ Success → Write Playwright script using selectors
    │         └─ Fails/Incomplete → Treat as dynamic (below)
    │
    └─ No (dynamic webapp) → Is the server already running?
        ├─ No → Run: python scripts/with_server.py --help
        │        Then use the helper + write simplified Playwright script
        │
        └─ Yes → Reconnaissance-then-action:
            1. Navigate and wait for networkidle
            2. Take screenshot or inspect DOM
            3. Identify selectors from rendered state
            4. Execute actions with discovered selectors

三个观察。其一，决策树压在正文最前面——先选路，再动手，模型不会顺着惯性一路写到底。其二，它用 ASCII 字符而不用 Mermaid：SKILL.md 的读者是模型，纯文本零渲染损耗，在终端、diff、任何查看器里都不会坏。其三，注意这一版没有「When to Use / When Not to Use」章节——取舍判断没有写成散列的清单，而是全部折叠进了这棵树：静态走读文件，动态走起服务器，已在跑就别重复起。路径即文档。

把这棵树画成流程图，是这样的：

flowchart TD
    A["用户：测一下本地网页"] --> B{"页面是静态 HTML？"}
    B -->|是| C["直接读文件找选择器"]
    C --> D{"能找到？"}
    D -->|能| E["写 Playwright 脚本"]
    D -->|找不到| F["按动态页面处理"]
    B -->|否| G{"服务器已在跑？"}
    F --> G
    G -->|否| H["with_server.py 托管起服"]
    G -->|是| I["先侦察：截图加读 DOM"]
    H --> I
    I --> J["从渲染结果定选择器"]
    J --> K["执行动作出结论"]
    E --> K

with_server.py 示例：命令即文档

python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py

单服务器一行，双服务器就再加一组 --server 加 --port，最后用 -- 分隔符接上真正要跑的自动化脚本。这个设计的聪明处：示例本身就是可执行命令。模型不需要「理解」with_server.py 的接口设计，把示例里的字符串换掉就能跑。文档的终点不是被读懂，而是被复制。

脚本模板里藏着军令状

给出的 Python 模板不长，但注释全是强调级：

browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
page.goto('http://localhost:5173') # Server already running and ready
page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute

三行注释三种力度：Always 是常规军令，Server already running and ready 是解释「为什么你的脚本里不用管起服」，而 CRITICAL 是大写警报。这里有个容易被忽略的机制：模型写自动化脚本时会照抄这个模板，注释会跟着一起被复制进最终产物。也就是说，这三句提示词不会停留在 SKILL.md 里被人读完就忘——它们跟着代码走，直到浏览器真正关上为止。注释即持久化的提示词，这是全文最高级的一处设计。

侦察优先：产物落盘，结论上会话

「Reconnaissance-Then-Action」三步：先 page.screenshot(path='/tmp/inspect.png', full_page=True) 和 content = page.content() 摸清渲染后的 DOM，再从侦察结果里挑选择器，最后才执行动作。注意截图路径写死在 /tmp——侦察的原始产物全部落盘，进上下文的只有「找到了哪个按钮」这个结论。和 MCP 路线每步截图回灌对话一对照，两条路线对上下文的态度高下立判。

坑位只写一个，但用 ❌✅ 写成一对

❌ Don't inspect the DOM before waiting for networkidle on dynamic apps ✅ Do wait for page.wait_for_load_state('networkidle') before inspection

全文唯一的 Common Pitfall，只写了模型最常翻的那个车：动态页面 JS 还没执行完就去读 DOM，拿到一个空壳。没有罗列十条注意事项稀释注意力——坑位清单越长，每条坑越不被当真。一条坑，反例正例各一句，完事。

Best Practices 首条重复黑盒条款

五条最佳实践，第一条又是「Use bundled scripts as black boxes」。开头说过一遍的话，结尾再说一遍——这不是啰嗦，是赌模型读到尾部时已经忘了开头。重要的事写两遍，首尾夹住中间。

尾挂三个参考文件：第三层延迟加载

- examples/element_discovery.py - Discovering buttons, links, and inputs on a page
- examples/static_html_automation.py - Using file:// URLs for local HTML
- examples/console_logging.py - Capturing console logs during automation

每个文件一行名字加一行用途，仅此而已。于是整份 Skill 形成三层渐进披露：SKILL.md 正文（必读）→ examples 示例（按需读）→ scripts 源码（原则上永远别读）。上下文花费逐层可控，这正是 Agent Skills 官方工程博客里「少装元数据、按需加载内容」思想落在一个具体文件上的样子。

把这份文件的解剖结构收进一张图：

mindmap
  root((SKILL.md 解剖))
    首句祈使句
      八词锁死技术栈
    黑盒条款
      先跑 help
      禁读源码
    ASCII决策树
      静态动态先分流
      起服归脚本管
    命令即文档
      换字符串就能跑
    军令状注释
      headless必开
      CRITICAL等networkidle
    单坑成对写
      反例正例各一句
    三层延迟加载
      examples按需读

写法排行榜：七条可抄经验，按可迁移性排序

1. 黑盒条款——凡是 Skill 附带脚本，写明「先 --help、禁读源码、理由是防上下文污染」。任何带脚本资源的 Skill 都该抄。
2. 首句祈使句——第一行就是动词命令，锁死技术栈，零铺垫。
3. 决策树前置——把分流逻辑做成树放在正文最前，先选路再动手；终端场景用 ASCII 树。
4. 军令状注释——把关键约束写进代码模板注释里，让它跟着复制粘贴进入最终产物。
5. 产物落盘——侦察类中间产物写死临时目录，只让结论进上下文。
6. 单坑成对——Pitfall 只写最高频的一个，❌✅ 各一句，不稀释。
7. 无铺垫开头——删掉所有「本 Skill 旨在」，背景介绍是上下文里的 pure cost。

适用与不适用

适合交给它：本地 dev server 的功能流验证；前后端双进程起服再测联调；纯静态 HTML 小工具的选择器定位；复现 bug 后验证修复是否生效；用 console 日志定位前端 JS 报错。

不要交给它：已上线公网站点的长期回归——那是 CI 里正规测试框架的活，Skill 每次现写脚本，不可复用为资产；需要多轮人机交互的探索式调试——会话态场景 MCP 更合适；纯逻辑单元测试——不起浏览器的事别拉浏览器；性能压测——工具定位完全不符。

安装与使用：

# 方式一：官方仓库手动装（目录名以仓库实际为准，clone 后找 webapp-testing）
git clone https://github.com/anthropics/skills.git
cp -r skills/example-skills/webapp-testing ~/.claude/skills/

# 方式二：skills.sh CLI 先搜再装
npx skills find webapp-testing

# 依赖（Skill 本体之外，一次性）
pip install playwright
playwright install chromium

装好后用自然语言触发即可：「帮我测一下 localhost:3000 的登录流程」「这个表单提交后没反应，复现一下」。也可以在本机已有的 example-skills 插件包里直接调用。

结语

webapp-testing 拆到底，只有一件事：它把上下文窗口当预算来花，而且花得极其抠门。首句八词、决策树零渲染、命令即文档、注释即军令、产物落盘、源码拉黑——一百行不到，每一行都在替模型省 token 或者防翻车。测试赛道或许仍是生态里的空屋，但官方在这间空屋里放的，是一件值得所有 Skill 作者抄作业的样板间。

参考来源

1. anthropics/skills 官方 Skills 仓库 — webapp-testing 的上游仓库，位于 example-skills 分类下
2. 本机 Claude Code 插件缓存（anthropic-agent-skills / example-skills 包）内 webapp-testing 的 SKILL.md 全文 — 本文所有原文引用均出自 2026-09-19 加载的当前版本
3. Equipping agents for the real world with Agent Skills — Anthropic Engineering — 渐进披露与元数据设计的官方阐述
4. Playwright for Python 官方文档 — sync_playwright、networkidle 等本文涉及 API 的权威定义

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。