Debug mabl tests from your AI coding agent
For the full index of agent-friendly pages, see llms.txt.
The mabl CLI supports a debugging skill known as the “mabl debugger”, which you can use in your AI coding agent to investigate, reproduce, and fix failing mabl tests without leaving your editor.
With the mabl debugger, you can:
- Investigate failures: retrieve the step trace, console output, network requests (HAR), DOM snapshot, and screenshot from any failed run. Your agent investigates the failure with the same evidence you would.
- Debug live: open a local Chrome session driven by the agent. The agent executes the test step-by-step, inspects the live page, applies your fix, and re-runs the failing step to confirm it passes.
By retrieving only relevant artifacts and confirming issues in real time, the mabl debugger keeps your sessions lean and minimizes unnecessary token consumption. This article explains how to set up and use the mabl debugger.
Setup
Prerequisites
Before installing the debugger, make sure you have the following set up:
- An AI coding agent that supports MCPs, such as Claude Code, Cursor, VSCode, GitHub Copilot, or any other client that reads an AGENTS.md file.
- The latest version of the mabl CLI
Install the debugger
Run the following install command for your agent of choice:
mabl agent install [client]
Replace [client] with the name of your agent, such as claude, cursor, vscode, copilot, or agents-md for other tools. For example, if you’re installing the debugger in Claude Code, run this command:
mabl agent install claude
The install command adds three tools:
- mabl debug skill - gives your agent the ability to extract data from failing mabl tests to analyze and resolve issues
- mabl MCP - gives your agent access to your mabl workspace and tools for retrieving results, analyzing failures, and more
- chrome-for-mabl MCP - gives your agent the ability to observe a live debug session and interact with your browser, including the ability to collect artifacts
Optional install flags
Use optional install flags to customize your configuration if needed:
| Flag | What it does |
| `–scope user | project` | |
--force |
Overwrite an existing mabl skill and MCP entries |
--skip-mcp |
Install the skill only. Leave the existing MCP configuration untouched. |
--append-snippet |
Append a short “Testing: mabl” section to your agent’s instruction file (e.g. CLAUDE.md, .cursorrules, AGENTS.md) |
Debug tests
Once installed, the mabl debugger teaches your agent a four-step debug loop.
| Phase | What happens | Example command |
| Triage | Inspect the failed step trace and pull artifacts captured at the failing step. | mabl agent debug steps [jr-id] |
| Hypothesize | Match the failure to a piece of code or a recent deploy. | grep -r “[failing selectors]” src/ |
| Reproduce | Launch a real Chrome attached to the agent and step through the test. | mabl agent debug session start --run-id [jr-id] |
| Verify | Re-run the failing step after the fix | mabl agent debug session run-step [sid] [step-id] |
For a complete list of available commands, see the mabl CLI command reference or run mabl agent -h in the terminal.
Investigate failures
To investigate failures, sk your agent for a recent mabl test failure and initiate the debugging process with a prompt:
“Can we debug this test run locally?”
The agent pulls the trace, reads the artifacts, and proposes a hypothesis.
Debug live
To dig deeper, ask your agent to reproduce the failure locally:
“Can we reproduce this locally?”
The agent initiates a local Chrome for Testing session to execute the test step-by-step. Once complete, it provides a summary and suggests specific resolutions, such as test updates or code fixes, so you can finalize the fix without leaving your agent session.