Skip to content

Commit 1e3491b

Browse files
aaronlabaaronlab
committed
docs: add Playwright LLM debugging page
1 parent 1a9413d commit 1e3491b

8 files changed

Lines changed: 290 additions & 1 deletion

‎docs/index.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,7 @@
198198
<a href="./browser-use-debugging.html">Browser Use</a>
199199
<a href="./stagehand-debugging.html">Stagehand</a>
200200
<a href="./skyvern-debugging.html">Skyvern</a>
201+
<a href="./playwright-llm-debugging.html">Playwright + LLM</a>
201202
<a href="./launch/">Launch kit</a>
202203
<a href="./llms.txt">llms.txt</a>
203204
</nav>
@@ -225,6 +226,7 @@ <h1 id="title">Replay an AI browser-agent failure</h1>
225226
<a class="button" href="./browser-use-debugging.html">Browser Use guide</a>
226227
<a class="button" href="./stagehand-debugging.html">Stagehand guide</a>
227228
<a class="button" href="./skyvern-debugging.html">Skyvern guide</a>
229+
<a class="button" href="./playwright-llm-debugging.html">Playwright + LLM guide</a>
228230
</div>
229231
</section>
230232

‎docs/integrations.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,7 @@
204204
<a href="./browser-use-debugging.html">Browser Use</a>
205205
<a href="./stagehand-debugging.html">Stagehand</a>
206206
<a href="./skyvern-debugging.html">Skyvern</a>
207+
<a href="./playwright-llm-debugging.html">Playwright + LLM</a>
207208
<a href="./launch/">Launch kit</a>
208209
<a href="https://github.com/aaronlab/browsertrace">GitHub</a>
209210
</nav>
@@ -285,6 +286,7 @@ <h2 id="skyvern">Skyvern</h2>
285286
<section class="band" aria-labelledby="playwright">
286287
<h2 id="playwright">Playwright + LLM</h2>
287288
<p class="section-copy">Use snapshots around the points where your LLM chooses the next browser action.</p>
289+
<p class="section-copy"><a href="./playwright-llm-debugging.html">Open the Playwright + LLM debugging guide</a> for a focused trace workflow and public-safe export commands.</p>
288290
<pre><code>from browsertrace import Tracer
289291

290292
tracer = Tracer()

‎docs/launch/day-3-targeted-communities-packet.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,14 @@ Short reply for relevant threads:
169169
If the missing piece is the LLM decision context rather than Playwright's browser
170170
trace itself, I'm building a small local tool for that case:
171171
172-
https://aaronlab.github.io/browsertrace/debug-browser-agent-failure.html
172+
Playwright + LLM guide:
173+
https://aaronlab.github.io/browsertrace/playwright-llm-debugging.html
174+
175+
Live exported trace:
176+
https://aaronlab.github.io/browsertrace/trace.html
177+
178+
Repo:
179+
https://github.com/aaronlab/browsertrace
173180
174181
It records screenshot, URL, action label, model input/output, and failed-step
175182
error into a local timeline. It is not a replacement for Playwright Trace Viewer;

‎docs/launch/metrics-log.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,4 @@ uv run --python 3.11 python scripts/launch_metrics.py --json
5656
| 2026-05-09T10:39:45+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after Browser Use adapter feedback issue: https://github.com/aaronlab/browsertrace/issues/11 |
5757
| 2026-05-09T10:41:48+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after Stagehand debugging landing page added |
5858
| 2026-05-09T10:45:31+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after Skyvern debugging landing page added |
59+
| 2026-05-09T10:47:56+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after Playwright LLM debugging landing page added |

‎docs/launch/outreach-targets.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ real reply or question to reference.
9595
3. Playwright community
9696
- Best angle: "This is for Playwright scripts that include LLM decisions, not
9797
a replacement for Playwright trace viewer."
98+
- Link order: Playwright + LLM guide first, live trace second, repo third.
9899
- Use Discord or LinkedIn only when the topic is LLM-guided automation.
99100
Share only the debugging write-up unless people ask for the repo.
100101
4. Skyvern Discussions

‎docs/llms.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ to explain why a browser run failed.
1717
- Browser Use guide: https://aaronlab.github.io/browsertrace/browser-use-debugging.html
1818
- Stagehand guide: https://aaronlab.github.io/browsertrace/stagehand-debugging.html
1919
- Skyvern guide: https://aaronlab.github.io/browsertrace/skyvern-debugging.html
20+
- Playwright + LLM guide: https://aaronlab.github.io/browsertrace/playwright-llm-debugging.html
2021
- Integrations: https://aaronlab.github.io/browsertrace/integrations.html
2122
- Examples: https://github.com/aaronlab/browsertrace/tree/main/examples
2223
- Launch kit: https://aaronlab.github.io/browsertrace/launch/

‎docs/playwright-llm-debugging.html‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<meta name="description" content="Debug Playwright scripts that use LLM decisions with local screenshots, URLs, model I/O, errors, and shareable BrowserTrace exports.">
7+
<meta property="og:title" content="Debug Playwright + LLM browser-agent failures with BrowserTrace">
8+
<meta property="og:description" content="Record Playwright screenshots and LLM decisions in one local timeline.">
9+
<meta property="og:image" content="https://aaronlab.github.io/browsertrace/social-preview.png">
10+
<meta property="og:type" content="article">
11+
<meta name="twitter:card" content="summary_large_image">
12+
<link rel="canonical" href="https://aaronlab.github.io/browsertrace/playwright-llm-debugging.html">
13+
<title>Debug Playwright + LLM Browser-Agent Failures with BrowserTrace</title>
14+
<style>
15+
:root {
16+
color-scheme: light;
17+
--ink: #172026;
18+
--muted: #5f6b76;
19+
--line: #d9e1e7;
20+
--paper: #f7f9fb;
21+
--panel: #ffffff;
22+
--accent: #0f766e;
23+
--code: #102026;
24+
}
25+
26+
* {
27+
box-sizing: border-box;
28+
}
29+
30+
body {
31+
margin: 0;
32+
background: var(--paper);
33+
color: var(--ink);
34+
font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
35+
}
36+
37+
a {
38+
color: #0369a1;
39+
text-decoration-thickness: 1px;
40+
text-underline-offset: 3px;
41+
}
42+
43+
header {
44+
background: var(--panel);
45+
border-bottom: 1px solid var(--line);
46+
}
47+
48+
.topbar,
49+
main,
50+
footer {
51+
width: min(960px, calc(100% - 32px));
52+
margin: 0 auto;
53+
}
54+
55+
.topbar {
56+
display: flex;
57+
align-items: center;
58+
justify-content: space-between;
59+
gap: 16px;
60+
flex-wrap: wrap;
61+
padding: 14px 0;
62+
}
63+
64+
.brand {
65+
font-weight: 700;
66+
letter-spacing: 0;
67+
}
68+
69+
nav {
70+
display: flex;
71+
gap: 14px;
72+
flex-wrap: wrap;
73+
font-size: 14px;
74+
}
75+
76+
main {
77+
padding: 36px 0 54px;
78+
}
79+
80+
h1 {
81+
margin: 0;
82+
max-width: 840px;
83+
font-size: clamp(34px, 5vw, 58px);
84+
line-height: 1.04;
85+
letter-spacing: 0;
86+
}
87+
88+
.dek {
89+
max-width: 780px;
90+
margin: 18px 0 24px;
91+
color: var(--muted);
92+
font-size: 20px;
93+
line-height: 1.45;
94+
}
95+
96+
.actions {
97+
display: flex;
98+
gap: 10px;
99+
flex-wrap: wrap;
100+
margin: 22px 0 6px;
101+
}
102+
103+
.button {
104+
display: inline-flex;
105+
align-items: center;
106+
justify-content: center;
107+
min-height: 40px;
108+
padding: 0 14px;
109+
border: 1px solid var(--line);
110+
border-radius: 8px;
111+
background: var(--panel);
112+
color: var(--ink);
113+
font-weight: 600;
114+
text-decoration: none;
115+
white-space: nowrap;
116+
}
117+
118+
.button.primary {
119+
border-color: var(--accent);
120+
background: var(--accent);
121+
color: #ffffff;
122+
}
123+
124+
section {
125+
border-top: 1px solid var(--line);
126+
padding-top: 28px;
127+
margin-top: 30px;
128+
}
129+
130+
h2 {
131+
margin: 0 0 10px;
132+
font-size: 24px;
133+
line-height: 1.2;
134+
letter-spacing: 0;
135+
}
136+
137+
p,
138+
li {
139+
max-width: 780px;
140+
}
141+
142+
ul,
143+
ol {
144+
padding-left: 24px;
145+
}
146+
147+
pre {
148+
max-width: 880px;
149+
margin: 14px 0 0;
150+
padding: 16px;
151+
overflow: auto;
152+
border-radius: 8px;
153+
background: var(--code);
154+
color: #eef7f6;
155+
font: 13px/1.55 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
156+
white-space: pre-wrap;
157+
}
158+
159+
code {
160+
background: #eef3f6;
161+
border-radius: 4px;
162+
padding: 2px 5px;
163+
font-size: 0.92em;
164+
}
165+
166+
pre code {
167+
padding: 0;
168+
background: transparent;
169+
}
170+
171+
.note {
172+
max-width: 820px;
173+
border-left: 4px solid var(--accent);
174+
background: var(--panel);
175+
border-radius: 0 8px 8px 0;
176+
padding: 14px 16px;
177+
}
178+
179+
footer {
180+
border-top: 1px solid var(--line);
181+
padding: 18px 0 34px;
182+
color: var(--muted);
183+
}
184+
</style>
185+
</head>
186+
<body>
187+
<header>
188+
<div class="topbar">
189+
<div class="brand">BrowserTrace</div>
190+
<nav aria-label="Primary">
191+
<a href="./">Live demo</a>
192+
<a href="./integrations.html">Integrations</a>
193+
<a href="./debug-browser-agent-failure.html">Walkthrough</a>
194+
<a href="https://github.com/aaronlab/browsertrace">GitHub</a>
195+
</nav>
196+
</div>
197+
</header>
198+
199+
<main>
200+
<h1>Debug Playwright scripts where an LLM chooses the next browser action</h1>
201+
<p class="dek">Playwright Trace Viewer is strong for browser automation. BrowserTrace is for the extra failure context in LLM-guided browser runs: the prompt, model output, action label, screenshot, URL, status, and first error in one local timeline.</p>
202+
<div class="actions" aria-label="Primary actions">
203+
<a class="button primary" href="https://github.com/aaronlab/browsertrace">View repo</a>
204+
<a class="button" href="./trace.html">Open exported trace</a>
205+
<a class="button" href="./integrations.html#playwright">Integration snippet</a>
206+
</div>
207+
208+
<section>
209+
<h2>Try the local demo first</h2>
210+
<pre><code>pip install "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.6"
211+
browsertrace demo
212+
browsertrace</code></pre>
213+
<p>Open <code>http://127.0.0.1:3000</code> and inspect the failed checkout-agent run before adding BrowserTrace to your own Playwright script.</p>
214+
</section>
215+
216+
<section>
217+
<h2>Capture the LLM decision points</h2>
218+
<pre><code>from browsertrace import Tracer
219+
220+
tracer = Tracer()
221+
222+
async with tracer.run("playwright llm agent") as run:
223+
await page.goto("https://example.com")
224+
await run.snapshot(page, action="opened example.com")
225+
226+
prompt = "Choose the selector for the checkout button"
227+
decision = await llm_choose_next_action(prompt, page)
228+
229+
await page.click(decision["selector"])
230+
await run.snapshot(
231+
page,
232+
action="clicked model-selected element",
233+
model_input=prompt,
234+
model_output=decision,
235+
)</code></pre>
236+
<p>Snapshots pull the current Playwright URL and screenshot, then attach the model input and model output you pass in.</p>
237+
</section>
238+
239+
<section>
240+
<h2>What this adds to Playwright traces</h2>
241+
<ul>
242+
<li>The LLM prompt or messages that caused the browser action.</li>
243+
<li>The model response, selected selector, or structured action plan.</li>
244+
<li>The screenshot and URL at the moment the decision was made.</li>
245+
<li>A browser-agent-first timeline that marks the first failed step.</li>
246+
<li>A standalone HTML export for issues, pull requests, and team review.</li>
247+
</ul>
248+
</section>
249+
250+
<section>
251+
<h2>Share only what is safe</h2>
252+
<pre><code>browsertrace list
253+
browsertrace export &lt;run_id&gt; -o full.html
254+
browsertrace export &lt;run_id&gt; --redact -o public.html</code></pre>
255+
<p>Use <code>--redact</code> before attaching a real trace to a public issue or community thread.</p>
256+
</section>
257+
258+
<section>
259+
<div class="note">
260+
BrowserTrace is not a replacement for Playwright Trace Viewer. It is a local layer for Playwright scripts where LLM decisions are part of the bug.
261+
</div>
262+
</section>
263+
</main>
264+
265+
<footer>
266+
<p>Repo: <a href="https://github.com/aaronlab/browsertrace">github.com/aaronlab/browsertrace</a></p>
267+
</footer>
268+
</body>
269+
</html>

‎docs/sitemap.xml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,12 @@
3636
<changefreq>monthly</changefreq>
3737
<priority>0.9</priority>
3838
</url>
39+
<url>
40+
<loc>https://aaronlab.github.io/browsertrace/playwright-llm-debugging.html</loc>
41+
<lastmod>2026-05-09</lastmod>
42+
<changefreq>monthly</changefreq>
43+
<priority>0.9</priority>
44+
</url>
3945
<url>
4046
<loc>https://aaronlab.github.io/browsertrace/trace.html</loc>
4147
<lastmod>2026-05-09</lastmod>

0 commit comments

Comments
 (0)