fix（修复）

Fix Automation Skill

Guide Claude through debugging and fixing failing browser automations.

When to Use

Use this skill when:

• A Browserbase Function is failing in production
• An automation stopped working (site changed)
• User reports errors from their automation
• CI/CD pipeline failures related to browser functions

Prerequisites

Requires the browse CLI and Chrome/Chromium:

browse --version  # Check if installed
bash scripts/setup-browse.sh  # Install if needed

Install manually: pnpm add -g @browserbasehq/browse-cli

Context Sources

Before debugging, gather context from:

1. Error messages - What the user reported or CI logs show
2. Function code - The automation script itself
3. Recent changes - Did the site update recently?
4. Last success - When did it last work?

Debugging Workflow

1. Reproduce the Issue

Start a Browserbase session to see what's happening:

browse session create
browse session live  # Open in browser to watch

Navigate to the target URL:

browse goto <target-url>

2. Compare Expected vs Actual State

Take a snapshot of the current page:

browse snapshot

Compare with what the automation expects:

• Are the expected elements present?
• Have selectors changed?
• Is there a login wall or CAPTCHA?
• Has the page structure changed?

3. Common Failure Patterns

Selector Changes

The site updated their HTML:

browse snapshot
# Look for similar elements with new selectors
browse eval "document.querySelector('.new-class')?.textContent"

Fix: Update selectors in the function code.

Timing Issues

Elements load slower than expected:

browse network on
browse goto <url>
browse network list
# Check if resources are slow to load

Fix: Add explicit waits or increase timeouts.

Authentication Expired

Session cookies no longer valid:

browse snapshot
# Look for login prompts

Fix: Re-authenticate or update auth flow. See /auth skill.

Rate Limiting / Bot Detection

Site is blocking automated access:

browse network list
# Look for 403, 429 status codes
browse screenshot -o blocked.png

Fix: Add delays, use proxies, or contact site owner.

Site Redesign

Major structural changes:

browse snapshot
browse screenshot -o current.png

Fix: Rewrite affected portions of the automation.

4. Test the Fix

Make changes to the function code, then test locally.

For Browserbase Functions (using bb CLI):

cd my-function
pnpm bb dev index.ts  # Start local dev server

# Test with curl
curl -X POST http://127.0.0.1:14113/v1/functions/my-function/invoke \
  -H "Content-Type: application/json" \
  -d '{"params": {}}'

For local scripts:

node my-script.js

5. Deploy the Fix

For Browserbase Functions:

pnpm bb publish index.ts

6. Verify Fix is Complete

After fixing:

1. Run the function multiple times to ensure stability
2. Check that all expected data is returned
3. Verify edge cases still work

Diagnostic Commands Reference

Example Debug Session

User: My price-monitor function stopped working yesterday

Claude: Let me investigate. First, let me start a debug session:

> browse session create
> browse session live
> browse goto https://example.com/product/123

Opening in browser so you can watch. Let me check the page structure:

> browse snapshot

I can see the price element now uses a different class `.product-price` instead of `.price`. The site appears to have been redesigned.

Let me verify:
> browse eval "document.querySelector('.product-price')?.textContent"

Yes, that returns "$29.99". I'll update the selector in your function:

[edits price-monitor/index.ts to use '.product-price']

Testing locally:
> cd price-monitor
> pnpm bb dev index.ts

[In another terminal]
> curl -X POST http://127.0.0.1:14113/v1/functions/price-monitor/invoke \
    -H "Content-Type: application/json" \
    -d '{"params": {"productUrl": "https://example.com/product/123"}}'

Works! Deploying fix:
> pnpm bb publish index.ts

The function should work now. Would you like me to commit this fix?

Commit and Deploy

Once fixed, use git to commit changes:

git add <function-file>
git commit -m "fix(<function-name>): <description of fix>"
git push

If this is a PR workflow:

gh pr create --title "Fix <function-name>" --body "..."