---
sidebar_position: 1
---
# Debugging Web Applications
A comprehensive guide to debugging web applications using agnt's proxy and frontend diagnostics.
## Overview
This use case covers the complete workflow for debugging frontend issues:
1. Set up the debugging environment
2. Capture and analyze HTTP traffic
3. Identify JavaScript errors
4. Debug layout and styling issues
5. Document and share findings
## Setting Up
### Start Your Development Server
```json
// Detect project and available scripts
detect {path: "."}
→ {type: "node", scripts: ["dev", "build", "test"]}
// Start dev server
run {script_name: "dev"}
→ {process_id: "dev", state: "running"}
// Verify it's ready
proc {action: "output", process_id: "dev", grep: "ready", tail: 5}
→ "Ready on http://localhost:3000"
```
### Create Debugging Proxy
```json
proxy {action: "start", id: "debug", target_url: "http://localhost:3000", port: 8080}
→ {id: "debug", listen_addr: ":8080", status: "running"}
```
Now browse to `http://localhost:8080` instead of port 3000.
## Debugging Workflows
### Investigating a User-Reported Bug
**Scenario:** User reports "the submit button doesn't work on the checkout page."
**Step 1: Navigate to the Problem Page**
Have the user (or navigate yourself) to the checkout page via the proxy.
**Step 2: Check for JavaScript Errors**
```json
proxylog {proxy_id: "debug", types: ["error"]}
→ {
entries: [{
message: "Cannot read property 'submit' of undefined",
source: "/static/js/checkout.js",
line: 234
}]
}
```
**Step 3: Check API Calls**
```json
proxylog {proxy_id: "debug", types: ["http"], url_pattern: "/api/checkout"}
→ {
entries: [{
method: "POST",
url: "/api/checkout",
status: 401,
response_body: "{\"error\": \"Session expired\"}"
}]
}
```
**Step 4: Inspect the Button**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.inspect('#submit-btn')"}
→ {
visibility: {visible: true},
accessibility: {role: "button", accessibleName: "Submit Order"},
// Element exists and is visible
}
```
**Conclusion:** The API returns 401 (session expired), causing the JavaScript error. The button itself is fine.
### Debugging Layout Issues
**Scenario:** Content is getting cut off on mobile.
**Step 1: Find Overflow Issues**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.findOverflows()"}
→ [
{selector: ".product-grid", overflow: "horizontal", excess: 200}
]
```
**Step 2: Get Details**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.getOverflow('.product-grid')"}
→ {
scrollWidth: 520,
clientWidth: 320,
hasHorizontalOverflow: true
}
```
**Step 3: Highlight the Issue**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.highlight('.product-grid', {color: 'rgba(255,0,0,0.3)', duration: 0})"}
```
**Step 4: Take Screenshot**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.screenshot('overflow-issue')"}
```
**Step 5: Examine the CSS**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.getComputed('.product-grid', ['display', 'grid-template-columns', 'gap'])"}
→ {
display: "grid",
"grid-template-columns": "repeat(3, 200px)", // Fixed width - problem!
gap: "16px"
}
```
**Solution:** Change `repeat(3, 200px)` to `repeat(auto-fit, minmax(200px, 1fr))`.
### Debugging Z-Index Problems
**Scenario:** Dropdown menu appears behind a modal.
**Step 1: Find Stacking Contexts**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.findStackingContexts()"}
→ [
{selector: ".modal", zIndex: 1000, reason: "position: fixed"},
{selector: ".dropdown", zIndex: 100, parentContext: ".header"}
]
```
**Step 2: Check Dropdown's Context**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.getStacking('.dropdown')"}
→ {
zIndex: 100,
createsContext: true,
parentContext: ".header", // Constrained by header!
reason: "z-index with position: absolute"
}
```
**Step 3: Check Header's Z-Index**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.getStacking('.header')"}
→ {
zIndex: 50, // Lower than modal's 1000
createsContext: true
}
```
**Problem:** The dropdown's z-index (100) is relative to `.header` (50), which is lower than the modal (1000).
**Solution:** Either increase header's z-index above 1000, or move the dropdown outside the header's stacking context.
### Performance Investigation
**Scenario:** Page loads slowly.
**Step 1: Check Performance Metrics**
```json
proxylog {proxy_id: "debug", types: ["performance"]}
→ {
entries: [{
navigation: {dom_content_loaded: 2500, load_event: 4500},
paint: {first_paint: 1800, first_contentful_paint: 2200}
}]
}
```
**Step 2: Analyze Resources**
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.captureNetwork()"}
→ {
summary: {
totalResources: 45,
totalTransferSize: 2500000,
byType: {
script: {count: 12, size: 1800000} // 1.8MB of JS!
}
},
entries: [
{name: "vendor.js", duration: 2100, size: 1200000}
]
}
```
**Step 3: Check for Slow API Calls**
```json
proxylog {proxy_id: "debug", types: ["http"], url_pattern: "/api"}
→ Find any API calls with high duration_ms
```
**Step 4: Get Page Session Overview**
```json
currentpage {proxy_id: "debug", action: "get", session_id: "page-1"}
→ Full breakdown of resources, errors, and timing
```
## Interactive Debugging
### Let User Show You the Problem
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.selectElement()"}
```
Ask the user to click on the problematic element. The response includes the selector and element details.
### Ask User Questions
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.ask('Does this look correct?', ['Yes', 'No', 'Partially'])"}
```
### Wait for Dynamic Content
```json
proxy {action: "exec", id: "debug", code: "window.__devtool.waitForElement('.results-loaded', 10000)"}
```
## Documentation Workflow
### Capture State for Bug Report
```json
// Screenshot
proxy {action: "exec", id: "debug", code: "window.__devtool.screenshot('bug-state')"}
// DOM snapshot
proxy {action: "exec", id: "debug", code: "window.__devtool.captureDOM()"}
// Element details
proxy {action: "exec", id: "debug", code: "window.__devtool.inspect('.problem-element')"}
// Recent errors
proxylog {proxy_id: "debug", types: ["error"], since: "5m"}
// Recent traffic
proxylog {proxy_id: "debug", types: ["http"], url_pattern: "/api", since: "5m"}
```
### Create Visual Guide
```json
// Highlight relevant elements
proxy {action: "exec", id: "debug", code: "window.__devtool.highlight('.step-1', {label: 'Step 1', duration: 0})"}
proxy {action: "exec", id: "debug", code: "window.__devtool.highlight('.step-2', {label: 'Step 2', duration: 0})"}
// Screenshot with highlights
proxy {action: "exec", id: "debug", code: "window.__devtool.screenshot('annotated-steps')"}
// Clean up
proxy {action: "exec", id: "debug", code: "window.__devtool.clearAllOverlays()"}
```
## Complete Debugging Session Example
```
User: "The product page is broken"
AI: Let me investigate. First, I'll set up debugging.
[run {script_name: "dev"}]
[proxy {action: "start", id: "debug", target_url: "http://localhost:3000"}]
AI: Please navigate to http://localhost:8080/products/123
[User navigates]
AI: Let me check for errors.
[proxylog {proxy_id: "debug", types: ["error"]}]
→ "TypeError: products.map is not a function"
AI: Found a JavaScript error. Let me check the API.
[proxylog {proxy_id: "debug", types: ["http"], url_pattern: "/api/products"}]
→ {status: 200, response_body: "{\"product\": {...}}"}
AI: The API returned a single product object, not an array.
The code expects an array (products.map).
Let me show you exactly where:
[proxy {action: "exec", id: "debug", code: "window.__devtool.highlight('.products-list', {color: 'red'})"}]
AI: The products-list container is highlighted. The component expects
an array but receives a single object.
Fix: Change the API endpoint to return [{...}] or update the
component to handle single products.
```
## Best Practices
1. **Start with errors** - Check `proxylog` for errors first
2. **Check API responses** - Many frontend bugs are caused by unexpected API data
3. **Use page sessions** - `currentpage` gives a unified view
4. **Screenshot liberally** - Visual evidence helps communication
5. **Clean up highlights** - Use `clearAllOverlays()` when done
6. **Document findings** - Capture state for sharing
## See Also
- [Reverse Proxy](/features/reverse-proxy) - Proxy configuration
- [Frontend Diagnostics](/features/frontend-diagnostics) - All available primitives
- [Performance Monitoring](/use-cases/performance-monitoring) - Deep performance analysis
