# How SnagBadger works

SnagBadger separates instructions, observations, and the report produced from them. That makes an unfinished attempt useful without claiming that a reproduction or regression test has been verified.

## Plan the behavior

A Markdown test definition describes prerequisites, steps, and expected outcomes. Directories and `section.md` files group definitions and supply inherited guidance, settings, and hooks. The catalog module validates that resolved contract before execution. [Learn about plans and sections](docs/concepts/test-plans-and-sections.md).

## Run through your environment

The execution module coordinates a fresh agent and, for browser tests, a new isolated browser context per attempt. A host-provided runtime performs the actual work. The supplied filesystem bridge exposes requests for a coordinating agent to service; it is not an unattended browser runner or embedded MCP client.

Lifecycle hooks establish and clean up fixtures. Recorded interactions and evidence describe the actual journey, including detours and early failures. [Start a first run](docs/getting-started/first-test-run.md) only after verifying your runtime capabilities.

## Review the result

A test run retains individual results and every attempt. Retrying does not erase a failure. Comments can describe problems, optimizations, suggestions, or context independently of the test outcome. The HTML run viewer exposes expectations, attempts, observations, and evidence. [Understand runs and attempts](docs/concepts/runs-results-and-attempts.md).

## Create and export a bug report

Select an observed failed attempt or incidental problem comment. Promotion preserves its source snapshot and actual interactions in the same portable bug-report model used for manual reports. Review and sanitize narrative and attachment bytes before export or delivery. [Create a portable report](docs/getting-started/first-bug-report.md) without a browser or tracker.

## Establish a regression check

A reproduction script describes how to encounter the problem. A regression test checks an established expectation. The current readiness helper assesses supplied validation against buggy and fixed states; it does not generate or execute the test for you. [Current capabilities and boundaries](project-status.md) identifies the remaining work.

Try this chain with the [sample profile scenario](examples/sample-site.md) and its [authored test catalog](examples/test-plan.md).