> ## Documentation Index
> Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Playwright debugging agent

> How Libretto investigates Playwright failures and opens pull requests that fix broken scripts.

When a Playwright automation fails, Libretto's Playwright debugging agent
investigates the failure against the live website and automatically opens a pull
request that fixes the broken script. It turns a broken run into a reviewable
change instead of a pager alert.

You add one call in your script's failure path; Libretto does the rest. For the
API and configuration, see the
[Playwright debugging agent reference](../reference/runtime/playwright-debug).

## Why it inspects the live page

A stack trace and a static DOM snapshot are rarely enough to fix a browser
automation. A selector like `input[name="username"]` might have failed because
the real field is `name="login"`, because the page redirected, or because an
element loads late — and the source code alone cannot tell you which.

The debugging agent does not guess. It runs an agent loop on the
[`libretto-browser-tools`](../reference/runtime/playwright-debug) SDK and
drives the supplied failed page in its existing browser context. Authentication,
storage, open tabs, network routes, and in-memory state remain available while
the agent confirms the cause. Fixes are grounded in what the agent actually
observed on the page.

## The flow

1. **Capture.** On failure, the debugger records the error, stack, URL, title,
   screenshot, and DOM snapshot, and reads the relevant source files from your
   repo at the base branch.
2. **Investigate.** The agent snapshots the failed page's live accessibility
   tree and runs Playwright code in the same browser context (for example,
   checking whether a selector resolves) until it is confident about the root
   cause.
3. **Fix.** It produces a minimal, full-file change for the files that must
   change — or, if the evidence is insufficient, it proposes nothing.
4. **Open a PR.** The change is committed to a new branch and opened as a pull
   request whose description cites the failure and the evidence behind the fix.

## What you need

* **A connected GitHub repository.** Install the Libretto GitHub App and link
  the repo so Libretto can open PRs on it.
* **A `LIBRETTO_API_KEY`.** The agent exchanges it for a short-lived,
  repo-scoped GitHub token — you never manage a raw GitHub token in production.
* **The debugger call in your script.** Add `debugPlaywrightFailure(error, page)`
  in your automation's `catch` block.

The [setup flow](https://libretto.sh/setup) walks through connecting GitHub,
minting the API key, and adding the debugger to an existing script.

## Relationship to error recovery

The Playwright debugging agent fixes the deterministic workflow *after* a
failure by opening a PR. For expected nondeterminism that should be handled
*during* a run, use a narrow runtime recovery action instead — see
[Error recovery](./error-handling-and-recovery).