---
name: dogfood
description: Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports
version: 1.0.0
metadata:
  hermes:
    tags: [qa, testing, browser, web, dogfood]
    related_skills: []
---

# Dogfood: Systematic Web Application QA Testing

## Overview

This skill guides you through systematic exploratory QA testing of web applications using the browser toolset. You will navigate the application, interact with elements, capture evidence of issues, and produce a structured bug report.

## Prerequisites

- Browser toolset must be available (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_vision`, `browser_console`, `browser_scroll`, `browser_back`, `browser_press`)
- A target URL and testing scope from the user
- If the browser cannot launch before any page-level QA begins, treat it as a harness-readiness issue and fix/verify the browser runtime before drawing conclusions about the app.

## Inputs

The user provides:
1. **Target URL** — the entry point for testing
2. **Scope** — what areas/features to focus on (or "full site" for comprehensive testing)
3. **Output directory** (optional) — where to save screenshots and the report (default: `./dogfood-output`)

## Workflow

Follow this 5-phase systematic workflow:

### Phase 1: Plan

1. Create the output directory structure:
   ```
   {output_dir}/
   ├── screenshots/       # Evidence screenshots
   └── report.md          # Final report (generated in Phase 5)
   ```
2. Identify the testing scope based on user input.
3. Build a rough sitemap by planning which pages and features to test:
   - Landing/home page
   - Navigation links (header, footer, sidebar)
   - Key user flows (sign up, login, search, checkout, etc.)
   - Forms and interactive elements
   - Edge cases (empty states, error pages, 404s)

### Phase 2: Explore

For each page or feature in your plan:

1. **Navigate** to the page:
   ```
   browser_navigate(url="https://example.com/page")
   ```

2. **Take a snapshot** to understand the DOM structure:
   ```
   browser_snapshot()
   ```

3. **Check the console** for JavaScript errors:
   ```
   browser_console(clear=true)
   ```
   Do this after every navigation and after every significant interaction. Silent JS errors are high-value findings.

4. **Take an annotated screenshot** to visually assess the page and identify interactive elements:
   ```
   browser_vision(question="Describe the page layout, identify any visual issues, broken elements, or accessibility concerns", annotate=true)
   ```
   The `annotate=true` flag overlays numbered `[N]` labels on interactive elements. Each `[N]` maps to ref `@eN` for subsequent browser commands.

5. **Test interactive elements** systematically:
   - Click buttons and links: `browser_click(ref="@eN")`
   - Fill forms: `browser_type(ref="@eN", text="test input")`
   - Test keyboard navigation: `browser_press(key="Tab")`, `browser_press(key="Enter")`
   - Scroll through content: `browser_scroll(direction="down")`
   - Test form validation with invalid inputs
   - Test empty submissions

6. **After each interaction**, check for:
   - Console errors: `browser_console()`
   - Visual changes: `browser_vision(question="What changed after the interaction?")`
   - Expected vs actual behavior

### Phase 3: Collect Evidence

For every issue found:

1. **Take a screenshot** showing the issue:
   ```
   browser_vision(question="Capture and describe the issue visible on this page", annotate=false)
   ```
   Save the `screenshot_path` from the response — you will reference it in the report.

2. **Record the details**:
   - URL where the issue occurs
   - Steps to reproduce
   - Expected behavior
   - Actual behavior
   - Console errors (if any)
   - Screenshot path

3. **Classify the issue** using the issue taxonomy (see `references/issue-taxonomy.md`):
   - Severity: Critical / High / Medium / Low
   - Category: Functional / Visual / Accessibility / Console / UX / Content

### Phase 4: Categorize

1. Review all collected issues.
2. De-duplicate — merge issues that are the same bug manifesting in different places.
3. Assign final severity and category to each issue.
4. Sort by severity (Critical first, then High, Medium, Low).
5. Count issues by severity and category for the executive summary.

### Phase 5: Report

Generate the final report using the template at `templates/dogfood-report-template.md`.

The report must include:
1. **Executive summary** with total issue count, breakdown by severity, and testing scope
2. **Per-issue sections** with:
   - Issue number and title
   - Severity and category badges
   - URL where observed
   - Description of the issue
   - Steps to reproduce
   - Expected vs actual behavior
   - Screenshot references (use `MEDIA:<screenshot_path>` for inline images)
   - Console errors if relevant
3. **Summary table** of all issues
4. **Testing notes** — what was tested, what was not, any blockers

Save the report to `{output_dir}/report.md`.

## Browser Harness Readiness

If browser QA fails before navigation, do not report the product as untestable and do not skip visual QA. First isolate whether Chromium/Playwright can start at all.

Recommended sequence:

1. Run a minimal browser navigation to a known simple URL.
2. If the browser process cannot start, inspect missing shared libraries or executable-wrapper issues in the host environment.
3. Install or expose only the minimum runtime libraries needed for Chromium; avoid broad unrelated package changes.
4. If the host uses a custom Chromium wrapper or local library directory, verify the wrapper executes the real browser with the intended `LD_LIBRARY_PATH`.
5. Re-run a simple navigation, then re-run the actual app QA.
6. In the final report, separate “browser harness fixed” from “app verified.”

This captures the fix pattern, not a permanent claim that browser tools are broken: runtime dependencies and host images change.

## Tools Reference

| Tool | Purpose |
|------|---------|
| `browser_navigate` | Go to a URL |
| `browser_snapshot` | Get DOM text snapshot (accessibility tree) |
| `browser_click` | Click an element by ref (`@eN`) or text |
| `browser_type` | Type into an input field |
| `browser_scroll` | Scroll up/down on the page |
| `browser_back` | Go back in browser history |
| `browser_press` | Press a keyboard key |
| `browser_vision` | Screenshot + AI analysis; use `annotate=true` for element labels |
| `browser_console` | Get JS console output and errors |

## Gstack-Assisted QA Option

When the user asks to run `gstack`/agentic QA against a web app, use it as a first-pass reviewer, then verify findings yourself before implementing anything.

1. Prepare safely:
   - Check repo state first: `git status --short`, branch, recent commits.
   - Disable/avoid telemetry, team, auto, memory, cookie, or credential features unless explicitly requested.
   - Add `.gstack/` to `.gitignore` if gstack creates local artifacts in the repo.
   - Never let the QA agent read `.env`/secrets or push/deploy.
2. Run report-only first:
   - Give gstack/Claude Code a narrow target URL, repo path, and scope.
   - Instruct it not to edit files on the first pass.
   - Ask for issues with reproduction steps, evidence, and severity.
3. Expect permission/tooling friction:
   - Claude/gstack may fail on overly narrow `allowedTools`; retry with a safer broader set plus explicit `disallowedTools` for secrets and destructive commands.
   - If a run partially completes, resume and ask it to return the report from work already completed rather than restarting blindly.
4. Verify before changing code:
   - Use browser tools directly to reproduce the highest-confidence issues.
   - Check console errors after each navigation/interaction.
   - Use visual QA for layout/scroll/header issues; DOM snapshots often miss visual clipping.
5. Implement only safe, high-confidence fixes:
   - Prefer small UI state/copy/layout fixes with regression tests.
   - Delegate implementation to Claude Code only with tight scope, no push/deploy, no secrets, and test/build verification.
   - Re-run `npm test` and `npm run build` or the project’s equivalent.
6. Report clearly:
   - Separate “gstack found” from “I verified” from “I implemented.”
   - Include changed files, test/build results, and any artifacts ignored or left local.

## Tips

- **Always check `browser_console()` after navigating and after significant interactions.** Silent JS errors are among the most valuable findings.
- **Use `annotate=true` with `browser_vision`** when you need to reason about interactive element positions or when the snapshot refs are unclear.
- **Test with both valid and invalid inputs** — form validation bugs are common.
- **Scroll through long pages** — content below the fold may have rendering issues.
- **Test navigation flows** — click through multi-step processes end-to-end.
- **Check responsive behavior** by noting any layout issues visible in screenshots.
- **Don't forget edge cases**: empty states, very long text, special characters, rapid clicking.
- When reporting screenshots to the user, include `MEDIA:<screenshot_path>` so they can see the evidence inline.