Features

Capture testing context

A Chrome extension (Manifest V3, vanilla TypeScript) captures testing context right from the browser session where an issue shows up: right-click any element to grab the URL, page title, a DOM snippet, a screenshot, the selected element and candidate locators, console errors, network events, and free-text notes. From the capture overlay, that context can either create a Jira ticket directly or open a prefilled job in the dashboard.

Job creation and the jobs pipeline

A job form in the web dashboard collects the target repository, branch, feature area, goal, acceptance criteria, and priority — either filled in by hand or prefilled from the extension's captured context. Version 1 supports a single job type, ADD_PLAYWRIGHT_TEST.

• Event-sourced state — the job lifecycle is recorded as JobEvent rows, with Run rows tracking individual execution attempts separately from the job request itself.
• Queue and claim — the ferret-runner worker registers itself with heartbeats and atomically claims the oldest, highest-priority queued job using row locking. The queue can be paused and resumed from the dashboard.
• Local checkout validation — the runner doesn't clone; a repository has to point at an existing local Git work tree with a matching origin, a clean tree, and the target branch available, or the job is marked blocked.
• Work branch — the runner checks out the target branch and creates a local-only flawferret/job-<short-id> branch, refusing to overwrite one that already exists.
• Codex approval gate — the job stops and waits for an explicit manual approval before Codex runs at all. With Codex execution disabled by default, an approved job only records the invocation plan instead of running it.
• Validation — after Codex runs, validation resolves a command in order: a global override, then a command Codex itself suggests, then the repository's own configured validation command; with none configured it just checks that files changed.
• PR approval gate — the job stops again and waits for a second, separate manual approval before any branch is pushed or PR opened. With PR creation disabled by default, nothing is pushed even after approval.
• PR check auto-heal — if a PR check fails, the runner can re-queue the job for a bounded number of automatic retries.
• Local checkout cleanup — the runner restores the checkout to its base branch afterward and records whether cleanup succeeded.
• Readiness view — a dashboard page summarizes queue state, runner health, blocked jobs, pending approvals, and a single suggested next action.

Framework Builder

Scaffolds a new Playwright + Cucumber/BDD test framework repository from a template: it previews the file set, then creates it either in a local directory or as a brand-new GitHub repository. Optional follow-up steps — installing dependencies and running a smoke test (on by default for local builds), initializing a Git repository, registering the result as a FlawFerret2 repository, and opening the folder — are tracked with a build history.

Discover Tests

Given a page URL, tester notes, and a repository's existing Cucumber coverage, this produces AI-generated test-scenario recommendations with impact ratings, tags, and acceptance criteria. Keep/hide decisions on those recommendations are saved, and any selected scenario titles can be queued directly as jobs.

Feature catalog and local test runs

Browses the Cucumber features and scenarios already in a registered checkout, explains a scenario in plain language with AI, and can run a single feature or scenario locally — capturing stdout/stderr and pass-rate stats for that run.

Tracker (Jira) integrations

Jira credentials are stored as reusable integration records and attached to repositories, so a Jira ticket can be created as part of the job pipeline. The browser extension can also create a Jira ticket directly from a capture, without going through a job at all.

AI coding agent implements the change

OpenAI Codex, an AI coding agent, implements the change against the target repository once the Codex approval gate above has been cleared.

Playwright validation

Playwright validates the AI-generated change before any human reviewer sees it.

Draft pull request for human review

Once approved, a draft GitHub pull request is opened for human review. Humans approve every AI-driven step in this pipeline — Codex execution and PR creation both require their own explicit sign-off.

Documented API

The Fastify API is documented with Swagger / OpenAPI, generated straight from the same Zod route schemas Fastify validates requests against, so the docs can't drift out of sync with actual API behavior. I used the interactive Swagger UI to exercise and validate endpoints during development. Published API docs →

Builds on FlawFerret

FlawFerret2 builds on an earlier tool I built, FlawFerret — a browser-based defect logging tool for streamlining issue capture during testing sessions.