weblens

name: weblens description: | Use WebLens to explore, audit, and automate web pages from the CLI. Activate this skill whenever you need to interact with a browser programmatically — scraping interactive elements, running actions/assertions, crawling a site, fuzzing forms, running accessibility audits, or generating Playwright tests.

Trigger for:

• Exploring what interactive elements exist on a page (buttons, inputs, links).
• Executing browser actions: click, fill, navigate, press key, scroll.
• Writing natural-language instructions resolved by an LLM (ai: prefix).
• Mapping site structure recursively (crawl).
• Scanning forms for required fields and input types.
• Running accessibility audits (axe-core).
• Comparing screenshots for visual regression.
• Fuzzing form inputs for crash/XSS vectors.
• Generating Playwright TypeScript tests from recorded sessions.
• Stealth mode to bypass bot-detection (Cloudflare, DataDome, etc.).

DO NOT trigger for: - Backend API testing (use Playwright test directly). - Unit testing JavaScript functions. - CI/CD pipelines or Docker configuration.

WebLens — Agent Skill Guide

WebLens is a CLI-powered browser utility built on Playwright. Run it via:

npm run weblens -- <command> [options]

The project lives at /Users/abhinavsharma/gitRepos/tester-buddy.

Core Rules for Agents

1. Always use --json — Text output is for humans. JSON is for you.
2. Always use --session ./session.json — Persist cookies/localStorage across commands. Without it, every command starts a fresh browser.
3. Always check url in JSON output — Verify navigation succeeded after click/goto actions.
4. Use --monitor-errors — Catch hidden 4xx/5xx or console exceptions after critical form submissions.
5. Execute commands sequentially — State is bridged by the session file.

Command Reference

explore <url> — The Eyes and Hands

Scrape a page and optionally perform actions/assertions.

# Headless element map
npm run weblens -- explore https://example.com/ --json --session ./s.json

# Action chain + assertions
npm run weblens -- explore https://example.com/ \
  --do "fill:#username:admin" \
  --do "fill:#password:secret" \
  --do "click:#login-btn" \
  --expect "url:dashboard" \
  --json --session ./s.json

# Natural-language actions via LLM (requires llm config)
npm run weblens -- explore https://example.com/ \
  --do "ai:log in as admin" \
  --do "ai:click the first Add to Cart button" \
  --json --session ./s.json

# Interactive headed mode for manual QA
npm run weblens -- explore https://example.com/ --interactive

Key options:

Action formats (--do):

Expectation formats (--expect):

crawl <url> — Site Mapping

npm run weblens -- crawl https://example.com/ --depth 2 --json
npm run weblens -- crawl https://example.com/ --visual  # Mermaid diagram

Output includes status codes, link counts, and broken-link detection.

forms <url> — Form Analysis

npm run weblens -- forms https://example.com/checkout --json --session ./s.json

Returns all form groups with input names, types, required flags, and current values.

audit <url> — Accessibility Audit

npm run weblens -- audit https://example.com/ --json

Runs axe-core. Returns violations with impact levels and help URLs.

fuzz <url> — Form Fuzzing

npm run weblens -- fuzz https://example.com/register --json

Injects XSS payloads, boundary integers, SQL strings. Reports crashes and unexpected responses.

visual <url> — Screenshot & Regression

# Capture baseline
npm run weblens -- visual https://example.com/ --out baseline.png

# Compare against baseline
npm run weblens -- visual https://example.com/ --base baseline.png --out diff.png --threshold 0.1

repl <url> — Interactive REPL

npm run weblens -- repl https://example.com/

Live command loop: type explore/click/fill commands in the terminal.

codegen — Generate Playwright Tests

# From session history → raw Playwright TypeScript
npm run weblens -- codegen --session ./s.json --out tests/flow.spec.ts

# LLM-cleaned version with assertions
npm run weblens -- codegen --session ./s.json --out tests/flow.spec.ts --llm

# Print LLM prompt instead of running it
npm run weblens -- codegen --session ./s.json --prompt

Self-Healing Selectors

If a click: or fill: action fails, WebLens automatically:

1. Extracts a keyword from the failed selector (e.g. #btn-submit → submit).
2. Searches the DOM for elements with matching text, aria-label, or placeholder.
3. Re-executes the action with the healed selector and logs the resolution.

This is transparent — no extra flags needed.

Semantic Actions (ai: prefix)

When selectors are unknown or brittle, use natural-language instructions:

--do "ai:log in with standard_user and secret_sauce"
--do "ai:add the backpack to the cart"
--do "ai:go to the checkout page"

How it works:

1. Scrapes visible interactive elements on the current page.
2. Sends them + the instruction to the configured LLM (OpenAI / Anthropic / Ollama).
3. Parses the LLM response into a concrete action string and executes it.
4. If the resolved action fails, self-healing kicks in as a fallback.

LLM configuration — set in weblens.config.json or env vars:

{ "llm": { "openaiKey": "sk-..." } }

Env vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, OLLAMA_MODEL.

Stealth Mode

Passes --disable-blink-features=AutomationControlled to Chromium and injects scripts that:

• Set navigator.webdriver to undefined.
• Mock window.chrome runtime properties.
• Spoof PDF viewer plugins and language headers.
• Override WebGL vendor/renderer to hardware values.

Enable per-command with --stealth, or set globally in weblens.config.json:

{ "stealth": true }

Configuration File (weblens.config.json)

{
  "stealth": false,
  "roles": {
    "admin": {
      "cookies": [{ "name": "session", "value": "abc", "domain": "example.com", "path": "/" }],
      "localStorage": { "user_role": "admin" }
    }
  },
  "mocks": [
    {
      "urlPattern": "**/api/payment",
      "method": "POST",
      "response": { "status": 500, "contentType": "application/json", "body": "{\"error\":\"mocked\"}" }
    }
  ],
  "llm": {
    "openaiKey": "",
    "anthropicKey": "",
    "ollamaModel": "",
    "ollamaUrl": "http://localhost:11434/api/chat"
  }
}

Typical Agent Workflow

# 1. Explore a login page
npm run weblens -- explore https://app.example.com/login --json --session ./s.json

# 2. Log in
npm run weblens -- explore https://app.example.com/login \
  --do "fill:#username:testuser" \
  --do "fill:#password:pass123" \
  --do "click:#login-btn" \
  --expect "url:dashboard" \
  --json --session ./s.json

# 3. Audit the dashboard for accessibility violations
npm run weblens -- audit https://app.example.com/dashboard --json --session ./s.json

# 4. Crawl the site to find broken links
npm run weblens -- crawl https://app.example.com/ --depth 2 --json

# 5. Generate a Playwright test from the recorded session
npm run weblens -- codegen --session ./s.json --out tests/login.spec.ts --llm

Troubleshooting