gstack browse: QA Testing & Dogfooding

Persistent headless Chromium. First call auto-starts (~3s), then ~100-200ms per command. Auto-shuts down after 30 min idle. State persists between calls (cookies, tabs, sessions).

SETUP (run this check BEFORE any browse command)

BROWSE_OUTPUT=$(browse/bin/find-browse 2>/dev/null || ~/.claude/skills/gstack/browse/bin/find-browse 2>/dev/null)
B=$(echo "$BROWSE_OUTPUT" | head -1)
META=$(echo "$BROWSE_OUTPUT" | grep "^META:" || true)
if [ -n "$B" ]; then
  echo "READY: $B"
  [ -n "$META" ] && echo "$META"
else
  echo "NEEDS_SETUP"
fi

If NEEDS_SETUP:

1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
2. Run: cd <SKILL_DIR> && ./setup
3. If bun is not installed: curl -fsSL https://bun.sh/install | bash

If you see META:UPDATE_AVAILABLE:

1. Parse the JSON payload to get current, latest, and command.
2. Tell the user: "A gstack update is available (current: X, latest: Y). OK to update?"
3. STOP and wait for approval.
4. Run the command from the META payload.
5. Re-run the setup check above to get the updated binary path.

IMPORTANT

• Use the compiled binary via Bash: $B <command>
• NEVER use mcp__claude-in-chrome__* tools. They are slow and unreliable.
• Browser persists between calls — cookies, login sessions, and tabs carry over.
• Dialogs (alert/confirm/prompt) are auto-accepted by default — no browser lockup.

Binary paths

Always resolve the binary through the shim — never hardcode a dist/ path:

Canonical resolve pattern (use in every skill that needs the binary):

B=$(~/.claude/skills/gstack/browse/bin/find-browse 2>/dev/null | head -1)
[ -z "$B" ] && { echo "ERROR: browse not built. Run: cd ~/.claude/skills/gstack && ./setup"; exit 1; }

Platform suffix is auto-resolved by the shim — on Windows it picks find-browse.exe / browse.exe, on macOS/Linux the unsuffixed binaries. See BINARIES.md for the full artifact inventory.

QA Workflows

Test a user flow (login, signup, checkout, etc.)

B=$(~/.claude/skills/gstack/browse/bin/find-browse | head -1)

# 1. Go to the page
$B goto https://app.example.com/login

# 2. See what's interactive
$B snapshot -i

# 3. Fill the form using refs
$B fill @e3 "[email protected]"
$B fill @e4 "password123"
$B click @e5

# 4. Verify it worked
$B snapshot -D              # diff shows what changed after clicking
$B is visible ".dashboard"  # assert the dashboard appeared
$B screenshot /tmp/after-login.png

Verify a deployment / check prod

$B goto https://yourapp.com
$B text                          # read the page — does it load?
$B console                       # any JS errors?
$B network                       # any failed requests?
$B js "document.title"           # correct title?
$B is visible ".hero-section"    # key elements present?
$B screenshot /tmp/prod-check.png

Dogfood a feature end-to-end

# Navigate to the feature
$B goto https://app.example.com/new-feature

# Take annotated screenshot — shows every interactive element with labels
$B snapshot -i -a -o /tmp/feature-annotated.png

# Find ALL clickable things (including divs with cursor:pointer)
$B snapshot -C

# Walk through the flow
$B snapshot -i          # baseline
$B click @e3            # interact
$B snapshot -D          # what changed? (unified diff)

# Check element states
$B is visible ".success-toast"
$B is enabled "#next-step-btn"
$B is checked "#agree-checkbox"

# Check console for errors after interactions
$B console

Test responsive layouts

# Quick: 3 screenshots at mobile/tablet/desktop
$B goto https://yourapp.com
$B responsive /tmp/layout

# Manual: specific viewport
$B viewport 375x812     # iPhone
$B screenshot /tmp/mobile.png
$B viewport 1440x900    # Desktop
$B screenshot /tmp/desktop.png

Test file upload

$B goto https://app.example.com/upload
$B snapshot -i
$B upload @e3 /path/to/test-file.pdf
$B is visible ".upload-success"
$B screenshot /tmp/upload-result.png

Test forms with validation

$B goto https://app.example.com/form
$B snapshot -i

# Submit empty — check validation errors appear
$B click @e10                        # submit button
$B snapshot -D                       # diff shows error messages appeared
$B is visible ".error-message"

# Fill and resubmit
$B fill @e3 "valid input"
$B click @e10
$B snapshot -D                       # diff shows errors gone, success state

Test dialogs (delete confirmations, prompts)

# Set up dialog handling BEFORE triggering
$B dialog-accept              # will auto-accept next alert/confirm
$B click "#delete-button"     # triggers confirmation dialog
$B dialog                     # see what dialog appeared
$B snapshot -D                # verify the item was deleted

# For prompts that need input
$B dialog-accept "my answer"  # accept with text
$B click "#rename-button"     # triggers prompt

Test authenticated pages (import real browser cookies)

# Import cookies from your real browser (opens interactive picker)
$B cookie-import-browser

# Or import a specific domain directly
$B cookie-import-browser comet --domain .github.com

# Now test authenticated pages
$B goto https://github.com/settings/profile
$B snapshot -i
$B screenshot /tmp/github-profile.png

Compare two pages / environments

$B diff https://staging.app.com https://prod.app.com

Multi-step chain (efficient for long flows)

echo '[
  ["goto","https://app.example.com"],
  ["snapshot","-i"],
  ["fill","@e3","[email protected]"],
  ["fill","@e4","password"],
  ["click","@e5"],
  ["snapshot","-D"],
  ["screenshot","/tmp/result.png"]
]' | $B chain

Quick Assertion Patterns

# Element exists and is visible
$B is visible ".modal"

# Button is enabled/disabled
$B is enabled "#submit-btn"
$B is disabled "#submit-btn"

# Checkbox state
$B is checked "#agree"

# Input is editable
$B is editable "#name-field"

# Element has focus
$B is focused "#search-input"

# Page contains text
$B js "document.body.textContent.includes('Success')"

# Element count
$B js "document.querySelectorAll('.list-item').length"

# Specific attribute value
$B attrs "#logo"    # returns all attributes as JSON

# CSS property
$B css ".button" "background-color"

Snapshot System

The snapshot is your primary tool for understanding and interacting with pages.

$B snapshot -i           # Interactive elements only (buttons, links, inputs) with @e refs
$B snapshot -c           # Compact (no empty structural elements)
$B snapshot -d 3         # Limit depth to 3 levels
$B snapshot -s "main"    # Scope to CSS selector
$B snapshot -D           # Diff against previous snapshot (what changed?)
$B snapshot -a           # Annotated screenshot with ref labels
$B snapshot -o /tmp/x.png  # Output path for annotated screenshot
$B snapshot -C           # Cursor-interactive elements (@c refs — divs with pointer, onclick)

Combine flags: $B snapshot -i -a -C -o /tmp/annotated.png

After snapshot, use @refs everywhere:

$B click @e3       $B fill @e4 "value"     $B hover @e1
$B html @e2        $B css @e5 "color"      $B attrs @e6
$B click @c1       # cursor-interactive ref (from -C)

Refs are invalidated on navigation — run snapshot again after goto.

Command Reference

Navigation

Reading

Interaction

Inspection

Visual

Tabs

Server

Tips

1. Navigate once, query many times. goto loads the page; then text, js, screenshot all hit the loaded page instantly.
2. Use `snapshot -i` first. See all interactive elements, then click/fill by ref. No CSS selector guessing.
3. Use `snapshot -D` to verify. Baseline → action → diff. See exactly what changed.
4. Use `is` for assertions. is visible .modal is faster and more reliable than parsing page text.
5. Use `snapshot -a` for evidence. Annotated screenshots are great for bug reports.
6. Use `snapshot -C` for tricky UIs. Finds clickable divs that the accessibility tree misses.
7. Check `console` after actions. Catch JS errors that don't surface visually.
8. Use `chain` for long flows. Single command, no per-step CLI overhead.