AGENT SKILL

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

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

  1. Inspect rendered DOM:

    page.screenshot(path='/tmp/inspect.png', full_page=True)
    content = page.content()
    page.locator('button').all()
    
  2. Identify selectors from inspection results

  3. 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 --help to 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() or page.wait_for_timeout()
  • Helpers that take a selector string pass it to Playwright (page.locator(sel)), never to document.querySelector inside evaluate: Playwright-only syntax (:text-is, :has-text, >>) throws there. To run JS on the element, use page.locator(sel).first.evaluate(fn). The same trap hides in a wait_for_function body that receives the selector as arg — to wait on an element, use page.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 for querySelector( 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: -k matches 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 -1 before 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 -k subset: 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 page
    • static_html_automation.py - Using file:// URLs for local HTML
    • console_logging.py - Capturing console logs during automation
    • mock_claude_runtime.js - Fake of a host-injected runtime (claude.ai artifact db/user), for page.add_init_script
  • references/ - Load when the trigger applies:
    • host-injected-runtime.md - Read before testing a page that depends on window.claude or another object the host injects
    • offline-and-service-worker.md - Read before any test that uses set_offline, waits on a service worker, checks offline UI, or uses page.route on 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

parksangick-lgtm
parksangick-lgtm/-foodbell-site

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. 한국어 요청 예 — '명세서로 정리해줘', '지금까지 얘기한 거 스펙으로 만들어줘'.

★ 0
parksangick-lgtm
parksangick-lgtm/-foodbell-site

teach

Teach the user a new skill or concept, within this workspace. 한국어 요청 예 — "○○ 수업해줘", "여러 날에 걸쳐 가르쳐줘", "수업 만들어줘". 짧은 질문("○○ 가 뭐야?")에는 쓰지 않는다. 수업 파일이 사이트에 올라가므로 c:\galleypark 폴더에서는 쓰지 않는다.

★ 0
parksangick-lgtm
parksangick-lgtm/-foodbell-site

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. 한국어 요청 예 — '맷 포콕 스킬 설정해줘', '맷 포콕 스킬 처음 설정'.

★ 0
parksangick-lgtm
parksangick-lgtm/-foodbell-site

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.

★ 0
parksangick-lgtm
parksangick-lgtm/-foodbell-site

improve-codebase-architecture

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. 한국어 요청 예 — "코드 구조 점검해줘", "코드 구조 개선할 곳 찾아줘".

★ 0
parksangick-lgtm
parksangick-lgtm/-foodbell-site

handoff

Compact the current conversation into a handoff document for another agent to pick up. 한국어 요청 예 — "인수인계해줘", "인수인계 문서 만들어줘", "다른 PC 에서 이어서 하게 정리해줘".

★ 0