webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- webapp-testing
- license
- Complete terms in LICENSE.txt
- description
- Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
02 资源文件 8
- 脚本examples/console_logging.py1.0 KB
- 脚本examples/element_discovery.py1.4 KB
- 脚本examples/mock_claude_runtime.js5.1 KB
- 脚本examples/static_html_automation.py953 B
- 许可证LICENSE.txt11.1 KB
- 参考文档references/host-injected-runtime.md2.7 KB
- 参考文档references/offline-and-service-worker.md3.3 KB
- 脚本scripts/with_server.py3.6 KB
03 SKILL.md 正文
Web Application Testing
To test local web applications, write native Python Playwright scripts.
Helper Scripts Available:
scripts/with_server.py- Manages server lifecycle (supports multiple servers)
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. 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.
Decision Tree: Choosing Your Approach
First: does the page need an object the host injects (e.g. window.claude)?
Yes → Read references/host-injected-runtime.md, then continue below.
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
Example: Using with_server.py
To start a server, run --help first, then use the helper:
Single server:
python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
Multiple servers (e.g., backend + frontend):
python scripts/with_server.py \
--server "cd backend && python server.py" --port 3000 \
--server "cd frontend && npm run dev" --port 5173 \
-- python your_automation.py
To create an automation script, include only Playwright logic (servers are managed automatically):
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
page = browser.new_page()
page.goto('http://localhost:5173') # Server already running and ready
page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
# ... your automation logic
browser.close()
Reconnaissance-Then-Action Pattern
-
Inspect rendered DOM:
page.screenshot(path='/tmp/inspect.png', full_page=True) content = page.content() page.locator('button').all() -
Identify selectors from inspection results
-
Execute actions using discovered selectors
Common Pitfall
❌ Don't inspect the DOM before waiting for networkidle on dynamic apps
✅ Do wait for page.wait_for_load_state('networkidle') before inspection
⚠ When the app sets its own ready signal (a data attribute, a status text), navigate with page.goto(url, wait_until='domcontentloaded') and let the wait for that signal carry the timeout. load and networkidle also wait for third-party scripts and fonts the app does not need, so a slow CDN fails whichever test happens to navigate at that moment.
Best Practices
- Use bundled scripts as black boxes - To accomplish a task, consider whether one of the scripts available in
scripts/can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use--helpto see usage, then invoke directly. - Use
sync_playwright()for synchronous scripts - Always close the browser when done
- Use descriptive selectors:
text=,role=, CSS selectors, or IDs - Add appropriate waits:
page.wait_for_selector()orpage.wait_for_timeout() - Helpers that take a selector string pass it to Playwright (
page.locator(sel)), never todocument.querySelectorinsideevaluate: Playwright-only syntax (:text-is,:has-text,>>) throws there. To run JS on the element, usepage.locator(sel).first.evaluate(fn). The same trap hides in await_for_functionbody that receives the selector asarg— to wait on an element, usepage.locator(sel).wait_for(). A rule like this recurs in shapes its wording does not name, so once it has been broken twice, add a test that greps the test files forquerySelector(fed from a variable. - Narrow a pytest run by file, or by a parameter id that cannot occur in the path (
-k "staff-pay", without brackets —-k "[staff-pay]"selects nothing), never by a word from the folder names:-kmatches substrings of every parent node's name, directories included, so a folder word selects everything and its negation selects nothing. Check the scope with--collect-only -q | tail -1before trusting a pass. Do not run several Playwright suites at once on one machine — a timeout under self-inflicted load is not a finding until it reproduces alone. - After an async operation, a negative DOM assertion waits for that operation's own completion signal (a button label coming back, a status attribute), not for a hook that fires midway:
is_hidden()is false for an element parked off-screen (left:-9999px), because it still has a box. - After changing a helper shared by many page tests, rerun the whole test file, not a
-ksubset: the subset never runs the other callers. - A test that fails only under full-suite load is a timing defect until shown otherwise. Rerun it with a much longer wait: a value that never arrives was lost, not late. Reproduce with CDP
Emulation.setCPUThrottlingRate(rate 6, Chromium) —page.context.new_cdp_session(page).send('Emulation.setCPUThrottlingRate', {'rate': 6})— and keep the throttle in the regression test after the fix.
Reference Files
- examples/ - Examples showing common patterns:
element_discovery.py- Discovering buttons, links, and inputs on a pagestatic_html_automation.py- Using file:// URLs for local HTMLconsole_logging.py- Capturing console logs during automationmock_claude_runtime.js- Fake of a host-injected runtime (claude.ai artifactdb/user), forpage.add_init_script
- references/ - Load when the trigger applies:
host-injected-runtime.md- Read before testing a page that depends onwindow.claudeor another object the host injectsoffline-and-service-worker.md- Read before any test that usesset_offline, waits on a service worker, checks offline UI, or usespage.routeon a site that registers a service worker
Local additions (references/, mock_claude_runtime.js, the first branch of the decision tree; 2026-10-28: the ⚠ ready-signal note under Common Pitfall and the last four Best Practices bullets, from selector strings to timing defects) were added to this copy and are not part of the upstream skill.
04 同仓库更多 Skills
to-spec
Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. 한국어 요청 예 — '명세서로 정리해줘', '지금까지 얘기한 거 스펙으로 만들어줘'.
teach
Teach the user a new skill or concept, within this workspace. 한국어 요청 예 — "○○ 수업해줘", "여러 날에 걸쳐 가르쳐줘", "수업 만들어줘". 짧은 질문("○○ 가 뭐야?")에는 쓰지 않는다. 수업 파일이 사이트에 올라가므로 c:\galleypark 폴더에서는 쓰지 않는다.
setup-matt-pocock-skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills. 한국어 요청 예 — '맷 포콕 스킬 설정해줘', '맷 포콕 스킬 처음 설정'.
redesign-existing-projects
Upgrades existing websites and apps to premium quality. Audits current design, identifies generic AI patterns, and applies high-end design standards without breaking functionality. Works with any CSS framework or vanilla CSS.
improve-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. 한국어 요청 예 — "코드 구조 점검해줘", "코드 구조 개선할 곳 찾아줘".
handoff
Compact the current conversation into a handoff document for another agent to pick up. 한국어 요청 예 — "인수인계해줘", "인수인계 문서 만들어줘", "다른 PC 에서 이어서 하게 정리해줘".