🚀 Quick Browser Framework

Cross-platform Browser Automation Framework for Windows & Linux - 64-bit optimized

A simple yet powerful Python framework for browser automation based on Selenium. Designed for cross-platform compatibility with focus on simplicity, reliability, and zero-configuration setup.

✨ Features

• 🔧 Simple API - Minimal setup code for maximum productivity
• 🌍 Cross-Platform - Seamless operation on Windows (x64) and Linux (x64, ARM64)
• ⚡ Performance Optimized - Fast startup times and efficient resource usage
• 📦 Zero-Setup - Automatic Chromium and ChromeDriver management
• 🛡️ Robust - Built-in error handling and retry mechanisms
• 🔒 Type-Safe - Complete type hints and robust error handling
• 🔄 Auto-Update - Automatic WebDriver compatibility management
• 📸 Screenshot Support - Built-in screenshot functionality
• 🎯 Context Manager Support - Clean resource management with automatic cleanup
• 🏗️ Modular Architecture - Use components independently or as complete framework

📦 Quick Installation

From PyPI (Recommended)

pip install quick-browser

From Gitea Registry (Development)

# From Gitea Registry
pip install --index-url https://git.noircoding.de/api/packages/NoirPi/pypi/simple/ quick-browser

# Or with requirements.txt
echo "--extra-index-url https://git.noircoding.de/api/packages/NoirPi/pypi/simple/" >> requirements.txt
echo "quick-browser>=1.1.0" >> requirements.txt
pip install -r requirements.txt

Test Installation

quick-browser-test

🚀 Quick Start

Basic Usage (Recommended - Context Manager)

from quick_browser import BrowserFramework, BrowserConfig

# Simple configuration
config = BrowserConfig(
    headless=False,        # Show browser window
    kiosk=False,          # Windowed mode
    show_console=True     # Show download progress
)

# Context manager automatically handles setup and cleanup
with BrowserFramework(config) as browser:
    # Navigate to a website
    browser.navigate("https://www.google.com")
    
    # Find and interact with elements
    search_box = browser.send_keys_by_name("q", "Python automation")
    search_box.submit()
    
    # Take screenshot
    browser.driver.save_screenshot("result.png")
    
    # Direct Selenium WebDriver access
    results = browser.driver.find_elements("css selector", "h3")
    print(f"Found {len(results)} search results")

Legacy API (Backward Compatibility)

from browser_framework import BrowserManager

# Browser starten
browser_manager = BrowserManager()
driver = browser_manager.get_driver()

# Webseite öffnen
driver.get("https://www.google.com")

# Element finden und interagieren
search_box = driver.find_element("name", "q")
search_box.send_keys("Python automation")
search_box.submit()

# Screenshot erstellen
driver.save_screenshot("result.png")

# Cleanup
browser_manager.cleanup()

Platform-Optimized Configuration

from quick_browser import PlatformConfigFactory

# Automatically optimized for current platform
config = PlatformConfigFactory.create_auto_config(
    headless=False,
    element_timeout=15
)

with BrowserFramework(config) as browser:
    browser.navigate("https://example.com")
    # Framework automatically handles platform differences

Advanced Configuration

from quick_browser import BrowserConfig

config = BrowserConfig(
    chromium_version="120.0.6099.109",  # Specific Chromium version
    driver_version="120.0.6099.109",    # Specific ChromeDriver version
    headless=True,                      # Headless mode
    element_timeout=30,                 # Custom timeouts
    page_load_timeout=45,
    performance_flags=[                 # Custom Chrome flags
        "--disable-extensions",
        "--disable-gpu",
        "--no-sandbox"
    ],
    browser_prefs={                     # Browser preferences
        "download.default_directory": "./downloads",
        "profile.default_content_settings.popups": 0
    }
)

📚 Examples

The examples/ directory contains complete examples:

• basic_example.py - Cross-platform browser automation with diagnostics
• advanced_scraping_example.py - Advanced scraping techniques with performance monitoring

Running Examples

# Basic example
python examples/basic_example.py

# Advanced examples
python examples/advanced_scraping_example.py

🛠️ Advanced Features

Element Interactions

from quick_browser import ElementWaiter

with BrowserFramework(config) as browser:
    browser.navigate("https://example.com")
    
    # Advanced element waiting
    waiter = ElementWaiter(browser.driver, default_timeout=10)
    element = waiter.wait_for_element_clickable("id", "submit-button")
    
    # Safe clicking with timeout
    success = browser.safe_click("css selector", ".important-button")
    
    # Multiple element interactions
    browser.send_keys_by_name("username", "testuser")
    browser.send_keys_by_name("password", "testpass")
    browser.click_by_id("login-button")

Performance Monitoring

from quick_browser import PerformanceMonitor

with BrowserFramework(config) as browser:
    browser.navigate("https://example.com")
    
    # Monitor page performance
    monitor = PerformanceMonitor(browser.driver)
    load_time = monitor.get_page_load_time()
    memory_usage = monitor.get_memory_usage()
    
    print(f"Page loaded in {load_time:.2f}s")
    print(f"Memory usage: {memory_usage['used_heap'] / 1024 / 1024:.1f}MB")

Cross-Platform Utilities

from quick_browser import CrossPlatformUtils

with BrowserFramework(config) as browser:
    browser.navigate("https://example.com")
    
    utils = CrossPlatformUtils()
    
    # Full page screenshot
    utils.take_full_page_screenshot(browser.driver, "fullpage.png")
    
    # Clear browser data
    utils.clear_browser_data(browser.driver)
    
    # Get comprehensive page info
    page_info = utils.get_page_info(browser.driver)
    print(f"Page title: {page_info['title']}")

Manual Resource Management

# Manual management for complex scenarios
browser = BrowserFramework(config)
try:
    browser.setup()  # Explicit setup
    browser.navigate("https://example.com")
    # ... your automation code ...
finally:
    browser.quit()   # Explicit cleanup

🏗️ Architecture

The framework is built with a modular architecture:

quick_browser/
├── core/              # Core framework orchestration
├── chromium/          # Chromium download and management
├── config/            # Configuration classes
├── utils/             # Utility components
├── exceptions/        # Custom exceptions
└── types/             # Type definitions

Key Components

• BrowserFramework: Main orchestrator class (new API)
• BrowserManager: Legacy compatibility class
• ChromiumManager: Handles Chromium download and setup
• DriverManager: Manages ChromeDriver compatibility
• ElementWaiter: Advanced element waiting utilities
• PerformanceMonitor: Browser performance tracking
• CrossPlatformUtils: Platform-agnostic utilities

🖥️ Platform Support

Windows

• Architecture: x64
• Features: Full feature support including console management
• Chrome Flags: Windows-optimized performance flags
• Dependencies: Includes pywin32 for Windows-specific features

Linux

• Architecture: x64, ARM64
• Features: Full feature support with X11 compatibility
• Chrome Flags: Linux-optimized flags including --no-sandbox
• Dependencies: No platform-specific requirements

📋 Requirements

• Python: 3.8 or higher
• Operating System: Windows 10+ or Linux (most distributions)
• Architecture: 64-bit (x64, ARM64 on Linux)
• RAM: Minimum 4GB recommended

Python Dependencies

selenium>=4.15.0
webdriver-manager>=4.0.0
requests>=2.31.0
tqdm>=4.66.0
pywin32>=306  # Windows only

🔧 CLI Tools

The framework includes practical CLI tools:

# Test framework installation
quick-browser-test

# Show help
quick-browser-test --help

📖 API Reference

📚 Complete API documentation is available in our Gitea Wiki

Quick Reference

BrowserFramework (New API)

Main orchestrator class for cross-platform browser automation.

from quick_browser import BrowserFramework, BrowserConfig

config = BrowserConfig(...)

# Context manager (recommended)
with BrowserFramework(config) as browser:
    browser.navigate("https://example.com")
    browser.send_keys_by_name("q", "search term")

Key Methods:

• navigate(url) - Navigate with automatic optimizations
• safe_click(by, value, timeout) - Safe element clicking
• send_keys_by_name(name, keys, timeout) - Type-safe text input

📖 Full BrowserFramework API →

BrowserManager (Legacy API)

Backward-compatible browser management class.

from browser_framework import BrowserManager

browser_manager = BrowserManager()
driver = browser_manager.get_driver()
# ... automation code ...
browser_manager.cleanup()

📖 Full BrowserManager API →

Configuration

from quick_browser import BrowserConfig, PlatformConfigFactory

# Manual configuration
config = BrowserConfig(headless=False, element_timeout=20)

# Platform-optimized configuration
config = PlatformConfigFactory.create_auto_config()

📖 Configuration Guide →

Utility Components

from quick_browser import ElementWaiter, PerformanceMonitor, CrossPlatformUtils

# Advanced element operations
waiter = ElementWaiter(driver)
element = waiter.wait_for_element_clickable("id", "button")

# Performance monitoring  
monitor = PerformanceMonitor(driver)
load_time = monitor.get_page_load_time()

📖 Utilities Reference →

## 🐛 Troubleshooting

### Common Issues

**Browser doesn't start on Linux:**
```bash
# Install required dependencies
sudo apt-get update
sudo apt-get install -y chromium-browser xvfb

Permission errors on Linux:

# Make sure Chrome binary is executable
chmod +x /path/to/chrome

WebDriver crashes:

• Update to latest framework version
• Check Chrome/ChromeDriver compatibility
• Enable verbose logging with log_system_info=True

Debug Mode

config = BrowserConfig(
    log_system_info=True,    # Enable detailed logging
    show_console=True        # Show browser console
)

📊 Performance

Benchmarks

• Cold Start (first run): ~45-150 seconds (includes Chromium download)
• Warm Start (cached): ~4-7 seconds
• Navigation: ~1-3 seconds per page
• Element Finding: ~100-500ms with waits
• Memory Usage: ~200-400MB per browser instance
• Context Manager Overhead: <50ms vs manual management

Download Sizes

• Chromium: ~50-200MB (platform dependent)
• ChromeDriver: ~5-15MB
• Total Cache: ~60-220MB

Optimization Tips

• Use headless=True for CI/CD pipelines
• Enable profile_cleanup=False for faster repeated runs
• Use specific versions to avoid download overhead
• Implement element waiting instead of time.sleep()
• Use context managers for automatic resource management

🏗️ Development

Setup Development Environment

# Clone repository
git clone https://git.noircoding.de/NoirPi/quick-browser.git
cd quick-browser

# Create virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux
source .venv/bin/activate

# Install development dependencies
pip install -e .[dev]

Running Tests

# All tests
pytest

# With coverage
pytest --cov=quick_browser

# Specific test
pytest tests/test_browser_framework.py

Code Quality

# Linting with Ruff
ruff check .

# Auto-fix
ruff check . --fix

# Formatting
ruff format .

# Type checking
mypy quick_browser/

Build Package

# Clean build
python -m build

# Upload to PyPI
twine upload dist/*

# Upload to Gitea
twine upload --repository gitea dist/*

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 Changelog

v1.2.0 (Current)

• 🌍 Cross-platform support (Windows + Linux)
• 🔧 New BrowserFramework API with context manager support
• 📦 Automatic Chromium and ChromeDriver management
• 🛠️ Modular architecture with utility components
• 🔒 Complete type safety and error handling
• ⚡ Performance optimizations and monitoring tools

v1.1.0 (2025-06-02)

• ✨ Initial release
• 🔧 Basic browser management
• 📦 Windows 64-bit optimization
• 🛡️ Error handling
• 📸 Screenshot support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues | Gitea Issues
• Documentation: Wiki | Gitea README
• Email: noirpi@noircoding.de

🙏 Acknowledgments

• Built on top of Selenium WebDriver
• Uses ungoogled-chromium for privacy-focused browsing
• Cross-platform compatibility inspired by modern Python practices
• Python Community and all beta testers

---

Made with ❤️ by NoirPi

Quick Browser Framework - Because browser automation shouldn't be complicated!