Babata Browser 🦞 v3.1#

Lightweight browser automation with CloakBrowser anti-detection (C++-level stealth Chromium). Playwright fallback. reCAPTCHA v3: 0.9 | Cloudflare Turnstile: PASS | 30/30 bot tests

---

Backend (v3.1)#

BackendreCAPTCHA v3Cloudflaregov sitesDefaultCloakBrowser0.9✅ PASS✅ Strong✅ autoPlaywright0.1❌ FAIL⚠️ Blockedfallback

• backend='auto' (default) → CloakBrowser if available → Playwright fallback
• backend='cloakbrowser' → force CloakBrowser, error if unavailable
• backend='playwright' → force Playwright

---

When to Use ✅#

Gov policy sites (JS-rendered) / SPA data collection / Form filling / Screenshot evidence / web_fetch returns <500 chars / WeChat articles

When NOT to Use ❌#

Static pages → web_fetch / API queries → fetch() / Text search → web_search (Tavily)

---

Install#

bash

# CloakBrowser (recommended — anti-detection)
pip install cloakbrowser
cd skills/babata-browser && pip install -e .

# Playwright fallback (already installed)
pip install playwright && python -m playwright install chromium

---

Core Principles#

1. Scan First (from smart-browser best practice)#

Never snapshot blindly. Find interactive elements with JS first:

python

browser.execute_js(page, """
  (() => {
    const els = document.querySelectorAll('a[href], button, input, select, textarea, [role=button], [onclick]');
    return [...els]
      .filter(el => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0 && r.top < window.innerHeight; })
      .map((el, i) => ({ i, tag: el.tagName.toLowerCase(), text: (el.innerText || el.value || '').trim().slice(0, 50), id: el.id, href: el.href?.slice(0, 80) }));
  })()
""")

2. Click by Text, Not CSS#

python

browser.click(page, text='Latest Policy')  # ✅ Stable
# ❌ browser.click(page, selector='#content > div:nth-child(3) > a')

3. Smart Wait (Not Fixed Sleep)#

python

browser.execute_js(page, """
  new Promise(resolve => { let tries = 0;
    const t = setInterval(() => {
      if (document.body.innerText.includes('expected text') || ++tries > 30) { clearInterval(t); resolve(tries < 30 ? 'found' : 'timeout'); }
    }, 500);
  })
""")

4. Layered Extraction#

text

Accessibility Snapshot → find target region → get_text(selector=region)
  → still unclear? → screenshot (last resort)

---

Usage#

Quick (Natural Language)#

python

from scripts.babata_browser import execute_task
result = execute_task('Open https://example.com, search policy, extract top 5 titles')

Precise Control#

python

from scripts.babata_browser import BabataBrowser
browser = BabataBrowser(headless=True); browser.start(); page = browser.new_page()
browser.goto(page, 'https://example.com')
browser.click(page, text='Agree')
browser.fill(page, 'input[name="q"]', 'query')
text = browser.get_text(page)
browser.screenshot(page, path='evidence.png')
browser.stop()  # ⚠️ Always close

CLI#

bash

babata-browser 'Open GitHub Trending, extract top projects' --json

---

Capabilities#

ActionDescriptionUse Casegoto(url)NavigateOpen target pageget_text(sel?)Extract text (scoped optional)Page bodyget_links(limit)All linksNavigation, search resultsclick(text=, sel=)Click by text or CSSPagination, submit, navfill(sel, val)Fill inputSearch box, login formscreenshot(path)Full-page screenshotEvidence, visual verifyscroll(n)ScrollLazy-loaded contentexecute_js(code)Run JSElement scan, smart waitextract_table(sel)Table to dict listData tables

---

Errors#

ErrorFixERR_TIMED_OUTIncrease timeout: goto(page, url, timeout=60000)CloudFlare "Just a moment..."Blocked — switch data sourceElement not foundScan first, click by text not CSSpage.click: TimeoutUse smart wait, not fixed sleepOrphaned browser processAlways call stop() in try/finally

Security#

• Never enter real credentials on untrusted sites
• Check content before screenshot (avoid capturing sensitive data)
• Default: headless=True
• Mandatory: stop() after use

---

vs Playwright MCP#

Playwright MCPbabata-browser v3.0DependenciesNode + npx + ChromiumPython + Playwright + ChromiumAI decisionsMCP clientBabata LLM directToken efficiencyMCP protocol overheadCLI, zero protocol costBest forLong-running automationHigh-frequency interaction, sampling

---

Changelog#

VersionDateChangesv2.12026-05-11Smart scan JS, smart wait, layered extraction, error table, security rulesv3.02026-05-11Full English localization, streamlined structure, version bump