A powerful browser automation tool for detecting and interacting with elements on web pages. RabbitBrowser is built on top of Puppeteer and provides a simple API for element detection, highlighting, and interaction.
- 🔍 Automatic Element Detection: Detects clickable elements, form inputs, and text blocks
- 🎨 Visual Highlighting: Highlights elements in the browser for easy identification
- 📝 Form Automation: Fill inputs, select options, click buttons, and submit forms
- 🌐 CDP Support: Connect to existing Chrome instances via Chrome DevTools Protocol
- 📊 Context Extraction: Extract page context, text, and element data for analysis
- ⏱️ Async API: All methods return Promises for better control flow and awaitable responses
// All getter methods are async and return Promises
const elements = await browser.getElements();
const textBlocks = await browser.getTextBlocks();
const url = await browser.getCurrentUrl();
// Find and filter methods are also async
const buttons = await browser.findElementsByTagName('button');
const loginButtons = await browser.findElementsByText('login');npm install rabbit-browserimport { RabbitBrowser } from 'rabbit-browser';
async function example() {
// Create a new instance
const browser = new RabbitBrowser();
try {
// Navigate to a URL
await browser.go('https://example.com');
// Get all the detected elements
const { elements, textBlocks, pageContext } = await browser.getCompleteData();
console.log(`Detected ${elements.length} interactive elements`);
// Find and interact with elements
const loginButtons = await browser.findElementsByText('login');
const loginButton = loginButtons[0];
if (loginButton) {
await browser.clickElement(loginButton);
}
// Close the browser when done
await browser.close();
} catch (error) {
console.error('Error:', error);
}
}
example();// Default options
const browser = new RabbitBrowser();
// With custom options
const browser = new RabbitBrowser({
headless: false, // Show the browser UI
defaultViewport: { width: 1280, height: 800 },
highlightAllText: true, // Highlight text blocks
focusOnConsent: false, // Special focus on consent buttons
waitTime: 3000, // Time to wait for elements to appear
includePageContext: true, // Include page context in results
});// Initialize the browser (called automatically by go())
await browser.init();
// Navigate to a URL
await browser.go('https://example.com');
// Connect to an existing Chrome instance via CDP
await browser.connectCDP({
browserURL: 'http://127.0.0.1:9222'
});// Get all detected elements
const elements = await browser.getElements();
// Get text blocks
const textBlocks = await browser.getTextBlocks();
// Get page context
const pageContext = await browser.getPageContext();
// Get everything at once
const { elements, textBlocks, pageContext } = await browser.getCompleteData();
// Get element count
const count = await browser.getElementCount();
// Get current URL
const url = await browser.getCurrentUrl();// Filter elements with a custom function
const buttons = await browser.filterElements(e => e.tagName === 'button');
// Find elements by text content
const loginElements = await browser.findElementsByText('login');
// Find elements by tag name
const divs = await browser.findElementsByTagName('div');// Click an element (by element data or index)
await browser.clickElement(loginButton);
// Or by index
await browser.clickElement(0);
// Fill an input
await browser.fillInput(emailInput, '[email protected]');
// Submit a form
await browser.submitForm(formElement);
// Select an option in a dropdown
await browser.selectOption(selectElement, 'option-value');
// Take a screenshot
await browser.takeScreenshot('screenshot.png');
// Close the browser
await browser.close();import { RabbitBrowser } from 'rabbit-browser';
async function fillForm() {
const browser = new RabbitBrowser({ headless: false });
try {
await browser.go('https://example.com/form');
// Get all elements
const elements = await browser.getElements();
// Find form elements
const nameInputs = await browser.findElementsByText('name');
const nameInput = nameInputs[0];
const emailInputs = await browser.findElementsByText('email');
const emailInput = emailInputs[0];
const submitButton = elements.find(e => e.type === 'submit');
// Fill form fields
await browser.fillInput(nameInput, 'John Doe');
await browser.fillInput(emailInput, '[email protected]');
// Submit the form
await browser.clickElement(submitButton);
console.log(`Form submitted. Current URL: ${await browser.getCurrentUrl()}`);
} finally {
await browser.close();
}
}import { RabbitBrowser } from 'rabbit-browser';
async function useCDP() {
const browser = new RabbitBrowser({
preserveBrowserViewport: true, // Use the actual browser window size
});
try {
// Connect to an existing Chrome instance via CDP
await browser.connectCDP({
browserURL: 'http://127.0.0.1:9222',
});
// Navigate to a page
await browser.go('https://example.com');
// Get all the data
const { elements, textBlocks, pageContext } = await browser.getCompleteData();
console.log(`Detected Elements: ${elements.length}`);
console.log(`Text Blocks: ${textBlocks.length}`);
} finally {
// Disconnect from CDP (doesn't close Chrome)
await browser.close();
}
}| Option | Type | Default | Description |
|---|---|---|---|
| headless | boolean | true | Run browser in headless mode |
| defaultViewport | object | { width: 1280, height: 800 } | Browser viewport size |
| highlightAllText | boolean | true | Highlight all text blocks |
| focusOnConsent | boolean | false | Focus on detecting consent buttons |
| logDetails | boolean | false | Log detailed operations |
| waitTime | number | 3000 | Time to wait for elements to appear (ms) |
| minElementsRequired | number | 1 | Minimum elements required before early return |
| earlyReturn | boolean | true | Return early if enough elements found |
| includePageContext | boolean | true | Include page context in results |
| includeFormInputs | boolean | true | Include form inputs in results |
| includeTextBlocks | boolean | true | Include text blocks in results |
| preserveBrowserViewport | boolean | false | Use browser's actual viewport size (for CDP) |
The package includes several examples demonstrating different features:
# Simple example with element detection
npm run example:simple
# Consent button detection
npm run example:consent
# Using CDP to connect to existing Chrome
npm run example:cdp
# Interactive element example
npm run example:interactive
# Form filling example
npm run example:formMIT