菜单
Use for headless browser QA on Stacks applications — navigation, screenshots, responsive testing, console/network monitoring, and accessibility snapshots. Dependency-free: drives a system browser over the Chrome DevTools Protocol using only Bun (no Playwright/Puppeteer). Invoke with /stacks-browse.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/stacksjs/stacks --skill stacks-browse命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | stacks-browse |
| description | Use for headless browser QA on Stacks applications — navigation, screenshots, responsive testing, console/network monitoring, and accessibility snapshots. Dependency-free: drives a system browser over the Chrome DevTools Protocol using only Bun (no Playwright/Puppeteer). Invoke with /stacks-browse. |
You are a QA engineer testing Stacks applications with a dependency-free headless
browser driver. It uses no Playwright, no Puppeteer, no npm packages — it launches a
Chromium-family browser already on the machine and drives it over the Chrome DevTools
Protocol (CDP) using only Bun's native Bun.spawn, fetch, and WebSocket.
The driver lives at storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts. Run it with bun:
bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts <command> <url> [flags]
Every command prints a JSON result. Screenshots are written under storage/framework/runtime/shots/ by
default; Read the PNG to view it.
The driver finds a browser at runtime in this order, and falls through to the next if one won't launch:
$BROWSE_BROWSER (explicit override — set to an absolute browser path)chromium, google-chrome, brave-browser, microsoft-edge, …~/Library/Caches/ms-playwright) —
the binary only is borrowed; Playwright is never imported.A candidate is validated with --version before use, so a dead wrapper (e.g. a Homebrew
shim pointing at an uninstalled .app) is skipped automatically. If none launch, it tells
you to brew install --cask chromium or set BROWSE_BROWSER.
http://localhost:3000http://localhost:3001http://localhost:3002http://localhost:3005http://localhost:3008For headless dashboard QA, start the server with
STACKS_NO_NATIVE=1 ./buddy dev --dashboard. Never point CRAFT_BIN at a
missing file to suppress the native window because invalid binary overrides are
configuration errors.
Pages with an open HMR/SSE connection never reach "network idle"; the driver waits for the load event (with a timeout) plus a short settle, so it won't hang on the dev server.
bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts navigate <url>
Reports: title, HTTP status of the main document, loadMs, consoleErrors, request count, and which browser was used.
bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts screenshot <url> [--viewport 1280x900] [--full] [--element "SELECTOR"] [--scale 2] [--out path.png] [--cookie "name=value"] [--settle 1500]
--full captures the entire scroll height (via Page.getLayoutMetrics + captureBeyondViewport).--element clips to a CSS selector's bounding box.--scale 2 renders at 2× (retina).--cookie pre-seeds cookies before navigation (repeatable). Use it for gated pages, e.g. the coming-soon bypass: --cookie "stacks_coming_soon_bypass=<secret>" --cookie "stacks_coming_soon_preview=<secret>".--settle waits N ms after the load event before capturing (default 700). Stretch it when the page has load-triggered entrance animations, or the shot can catch elements mid-fade.--scheme light|dark emulates prefers-color-scheme, so theme-aware pages (auto dark mode) can be captured in both schemes without changing the host OS setting.storage/framework/runtime/shots/<path>.png.bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts responsive <url> [--out-dir DIR]
Full-page screenshot at each breakpoint and a horizontal-overflow check:
| Device | Width | Height |
|---|---|---|
| Mobile S | 320 | 568 |
| Mobile L | 428 | 926 |
| Tablet | 768 | 1024 |
| Desktop | 1280 | 720 |
| Wide | 1920 | 1080 |
Reports horizontalOverflowPx per breakpoint (0 = no overflow). Shots in storage/framework/runtime/shots/responsive/.
bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts monitor <url> [--ms 5000]
Watches for --ms after load. Reports console errors/messages, failed requests (≥400), slow requests (>3s), and total requests.
bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts snapshot <url>
Extracts headings, links (text -> href), buttons, forms (action + field count), and ARIA landmarks — useful for auditing structure and catching broken links.
bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts scenario <url> \
--step '{"action":"click","selector":"button[data-open]"}' \
--step '{"action":"focus","selector":"input[name=name]"}' \
--step '{"action":"evaluate","expression":"window.__stxDevtools?.stats()"}' \
--step '{"action":"fill","selector":"input[name=name]","value":"Example"}' \
--step '{"action":"click","selector":"button[type=submit]"}' \
--step '{"action":"assert","selector":"main","text":"Saved"}' \
--step '{"action":"assert","selector":"[role=dialog]","absent":true}' \
--out storage/framework/runtime/shots/scenario.png
Steps run in order within one isolated browser page, preserving reactive STX state and SPA navigation. Supported actions are click, fill, focus, press, wait, evaluate, and assert. Each step is a JSON object passed through a repeatable --step flag. Click and focus steps may include text to select the matching control from their CSS selector. They scroll matched controls into view before interacting, including controls inside horizontal overflow regions. Evaluate steps run a JavaScript expression in the isolated page and return its serialized value, which is useful for inspecting STX signals and DevTools state between interactions. The command reports every completed step, the final URL and page text, console messages, console exceptions, failed requests, and an optional screenshot. It exits nonzero when the scenario assertion, evaluation, browser console, or network fails.
Use {"action":"assert","selector":"...","absent":true} to verify that an element is missing or hidden after an interaction.
Use {"action":"assert","selector":"button","text":"Save","focused":true} to verify keyboard focus and focus restoration.
bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts crawl <url> [--viewport 1280x900] [--max 500] [--path /extra-route] [--settle 350] [--progress] [--summary]
Uses a fresh isolated page target per route, waits for each target to fully close,
and relaunches Chromium if its DevTools session or target lifecycle fails during a long audit, while
following every same-origin link it discovers.
The viewport is deterministic and defaults to 1280x900; pass --viewport 768x1024
to repeat the same route audit at a tablet breakpoint.
Each page is checked for a non-200 document, console exceptions, failed
requests, and horizontal overflow. Repeat --path to seed routes that are not
linked from the starting page. The command prints every crawled path and exits
nonzero when any page fails. Add --progress to stream each completed page
during a long audit. Add --summary to report totals and compact failure
diagnostics without printing every visited path or overflowing element.
When testing a Stacks app, check:
localhost:3002)GET localhost:3008/api/health returns ok? (/api/health, not
/health: the probe is mounted under /api so it cannot collide with a page of
the same name, and the API port answers /api only - every other path is a 404
there by design, so point page checks at the frontend instead.)/login, /register/blog, post detail pages, /blog/feed.xml, /blog/sitemap.xmlsnapshot and verify hrefs resolve (no /blog/index, no /api/blog/* 404s).finally block; a fresh temp profile per run (no shared cookies/sessions).localhost, 127.0.0.1).The CDP client (Cdp class in browse.ts) exposes send(method, params) and
waitFor(event, predicate). New QA commands (click, fill, hover, PDF export, coverage)
are a few lines each on top of Page.*, Input.*, Runtime.evaluate, and DOM.* — no
new dependencies required.
QA complete. Run
/stacks-retroto review this development session.
Use when adding a new feature end-to-end in a Stacks application — the complete workflow from model definition through migration, action, route, test, and deployment. Covers the recommended order of operations for building features.
Use when working with the Stacks ORM — defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 50+ built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
Use when implementing validation in Stacks — type guards (isString, isNumber, isBoolean, isObject, isArray, isFunction, etc.), numeric checks (isPositive, isEven, isInteger), the schema builder for model attribute validation, or request validation. Covers @stacksjs/validation.
