browser-dog 0.1.0

A stealthy Chrome automation toolkit driven by cookies, with anti-detection and smooth scrolling.

Browser Dog

A stealthy Chrome automation toolkit driven by cookies, with anti-detection and smooth scrolling.

Features

• Anti-Detection: Random User-Agent, CDP injection, webdriver property hiding
• Robust Cookie Loading: Expiry filtering, sameSite compatibility, redundant field cleanup
• Smooth Scrolling: Human-like progressive scrolling simulation
• Captcha Detection: Automatic detection of blocks and captchas with screenshot debugging
• Context Manager: Automatic resource cleanup to prevent zombie processes
• Retry Mechanism: Built-in retry decorator for resilient operations

Installation

pip install browser_dog

Quick Start

Basic Usage

from browser_dog import BrowserDog

# Initialize with cookies and base URL
dog = BrowserDog('cookies.json', 'https://example.com', headless=False)
driver = dog.get_driver()

# Navigate and interact
driver.get("https://example.com/page")
dog.medium_wait()

# Get page content
html = driver.page_source
print(html)

# Clean up
dog.close()

Using Context Manager (Recommended)

from browser_dog import BrowserDog

with BrowserDog('cookies.json', 'https://example.com') as dog:
    driver = dog.get_driver()
    driver.get("https://example.com/page")
    
    # Scroll smoothly
    dog.scroll_to_bottom()
    dog.scroll_to_top()
    
    # Check for blocks
    if dog.detect_block_or_captcha():
        print("Blocked!")

Using Retry Decorator

from browser_dog import BrowserDog, retry

dog = BrowserDog('cookies.json', 'https://example.com')

@retry(max_retries=3, delay=2)
def fetch_data():
    driver = dog.get_driver()
    driver.get("https://example.com/api")
    return driver.page_source

data = fetch_data()

Headless Mode

from browser_dog import BrowserDog

dog = BrowserDog('cookies.json', 'https://example.com', headless=True)
driver = dog.get_driver()

Preparing Cookies

1. Install the Chrome extension EditThisCookie
2. Navigate to your target website and login
3. Export cookies to a JSON file (e.g., cookies.json)

Project Structure

browser_dog-0.1.0/
├── browser_dog/
│   ├── __init__.py          # Package exports (BrowserDog, retry)
│   └── browser.py           # Core BrowserDog class implementation
├── LICENSE                  # MIT License
├── README.md                # This file
└── pyproject.toml           # Package configuration (PEP 621)

API Reference

BrowserDog

Constructor

BrowserDog(cookies_json: str, base_url: str, headless: bool = False)

• cookies_json: Path to cookies JSON file
• base_url: Base URL to initialize the browser
• headless: Enable headless mode (default: False)

Methods

Method	Description
get_driver()	Returns the Selenium WebDriver instance
close()	Safely closes the browser
scroll_to_bottom()	Smooth scroll to page bottom
scroll_to_top()	Smooth scroll to page top
scroll_to_middle()	Instant scroll to page middle
scroll_to_random()	Instant scroll to random position
detect_block_or_captcha()	Detect captcha or block (returns bool)
take_screenshot(name)	Save screenshot for debugging
short_wait()	Wait 1-3 seconds
medium_wait()	Wait 3-5 seconds
long_wait()	Wait 5-10 seconds

retry Decorator

@retry(max_retries: int = 3, delay: int = 2)

Automatically retries failed operations with exponential backoff.

Disclaimer

This tool is provided for educational, research, and legitimate automation testing purposes only. By using Browser Dog, you agree to the following:

1. Lawful Use Only: You must not use this tool for any illegal activities, including but not limited to malicious web scraping, unauthorized data collection, bypassing security measures, or violating the terms of service of any website or platform.

2. Compliance with Laws and Policies: You are solely responsible for ensuring that your use of this tool complies with all applicable local, national, and international laws, regulations, and the terms of service of the websites you interact with.

3. No Warranty: This software is provided "as is" without warranty of any kind. The authors and contributors assume no liability for any claims, damages, or losses arising from the use of this tool.

4. User Responsibility: You assume full responsibility for any risks associated with using this tool, including but not limited to account suspension, legal action, or reputational damage resulting from misuse or unauthorized use.

5. Ethical Use: Respect website policies, rate limits, and privacy rights. Do not use this tool to harvest personal data, conduct unauthorized surveillance, or engage in any activity that infringes on the rights of others.

The authors of this project expressly disclaim any responsibility for misuse, abuse, or any unlawful activities conducted using this software. If you are uncertain whether your intended use complies with applicable laws or policies, consult with a legal professional before proceeding.

License

MIT License - see LICENSE file for details.