Home

Welcome to osn-selenium Documentation

osn-selenium is a sophisticated, highly modular wrapper around Selenium WebDriver designed for advanced automation scenarios, bot development, and stealth web scraping.

It goes beyond standard browser control by offering native asynchronous support via Trio, mathematical models for human-like user interactions, and deep integration with Chrome DevTools Protocol (CDP) for anti-fingerprinting and network control.

Below is a detailed overview of the library's capabilities and internal architecture.

---

Key Features & Architecture

The library is organized into several specialized packages. Click the links to learn more about each module.

1. Core Architecture

The entire framework is engineered to address limitations in the classic Selenium structure (the "God Object" problem). osn-selenium provides modularity through extensive use of Mixins, enhancing maintainability, code readability, and testability across all features. It significantly extends Selenium's built-in capabilities and synchronizes low-level browser control with high-level Python application logic.

2. Browser Handlers

Automated environment detection logic located in browsers_handler.

• Auto-Detection: Automatically finds installed browser binaries on Windows (Registry) and Linux (.desktop files / path).
• Version Parsing: Extracts exact version numbers for both browsers and WebDriver binaries to ensure compatibility.

3. WebDrivers

The core driver logic is split into two execution architectures and a unified base, supporting Chrome, Edge, and Yandex browsers.

• sync: The classic blocking implementation for linear scripts.
• trio_threads: An asynchronous implementation wrapping blocking calls in threads, allowing concurrent control of multiple browsers within a Trio event loop.
• unified: The shared logic layer (BlinkBaseMixin, CoreLifecycleMixin) that ensures consistency between sync and async modes.

4. Flags Management

Strictly typed configuration for browser startup arguments.

• Pydantic Models: Instead of passing raw lists of strings, use structured classes like ChromeFlags, BlinkFeatures, and EdgeArguments.
• Validation: Prevents invalid configuration states before the browser even starts.

5. Instances

The fundamental object layer responsible for integrating raw Selenium results into the framework's architecture.

• Wrappers: Every object returned by the driver (such as WebElement, Alert, ShadowRoot, SwitchTo, etc.) is wrapped in a dedicated class (instances/[sync|trio_threads]/...).
• Architectural Consistency: This ensures that objects maintain the correct execution model (await functionality in trio_threads or direct calls in sync) across the entire framework.

6. CDP Executors

A unified access point to the Chrome DevTools Protocol, located in executors.[sync|trio_threads].cdp.

• Version Routing: Automatically routes commands to the correct, version-specific CDP domain layer (supporting v140-v144).
• Dynamic Loading: Dynamically loads the required external CDP package based on the running browser version.
• BiDi Support: Extends core BiDi features for advanced, protocol-level control.

7. JavaScript Executors

A robust layer (executors.[sync|trio_threads].javascript) for executing browser-side scripts consistently across all driver implementations.

• Unified Interface: Provides a single method signature for running internal JavaScript helpers (e.g., precise viewport measurements, element boundary calculations) regardless of the chosen architecture (sync or trio_threads).
• Utility Scripts: Includes access to pre-written, tested scripts for complex tasks like finding a random clickable point within an element's visible area.

8. Human-Like Interactions

Specialized mixins that extend the built-in ActionChains functionality with advanced mimicry features.

• Mouse Movements (HMMoveMixin): Implements human-like paths with sinusoidal deviations and randomized timing.
• Keyboard Input (HMKeyboardMixin): Replaces robotic input with typing that includes randomized delays (50-200ms) between keystrokes to mimic human behavior.
• Smart Scrolling (HMScrollMixin): Provides methods for natural-looking scroll operations.

9. DevTools

Direct control over the browser via the Chrome DevTools Protocol (dev_tools package).

• Target Management: Monitors and attaches to pages, iframes, and service workers (TargetData).
• Network Interception: Handle fetch.RequestPaused and fetch.AuthRequired events to modify traffic on the fly.
• Logging System: Comprehensive logging of CDP events and Fingerprint detection attempts via MainLogger and TargetLogger.

10. Anti-Fingerprinting

A robust module (javascript.fingerprint) for modifying browser identity at the prototype level.

• Spoofing Rules: Apply noise or static values to APIs using rules like StaticItemSetRule, RandomArrayNoiseRule or RandomItemNoiseRule.
• Registry: A detailed map of hookable APIs (navigator, screen, webgl, audioContext) to prevent bot detection scripts from identifying the automation.

11. BiDi Mapping

The experimental, next-generation core of osn-selenium that transitions from traditional HTTP-based communication to the WebDriver BiDi protocol.

• True Asynchronicity: Unlike trio_threads, which wraps blocking calls, trio_bidi is natively event-driven, using a single persistent WebSocket connection for all operations.
• Context Isolation: Introduces the use_context pattern, allowing different Trio tasks to control multiple browser tabs simultaneously without global state conflicts.
• Zero-Overhead Mapping: Seamlessly translates standard Selenium commands into low-level BiDi messages, offering a significant performance boost and better event handling.

---

Quick Start

Here is a simple example using the Synchronous architecture with Human-like movements.

from selenium.webdriver.common.by import By

from osn_selenium.webdrivers.sync.chrome import ChromeWebDriver
from osn_selenium.flags.models.chrome import ChromeFlags, ChromeArguments

# 1. Configure browser flags using typed models
flags = ChromeFlags(
    argument=ChromeArguments(
        headless_mode=False,
        mute_audio=True,
        no_first_run=True
    )
)

# 2. Initialize the driver (Sync mode)
driver = ChromeWebDriver(
    webdriver_path="./chromedriver", 
    flags=flags
)
driver.start_webdriver()

# 3. Navigate
driver.get("https://github.com")

# 4. Human-like interaction
# The mouse will move in a natural curve with micro-deviations
search_input = driver.find_element(by=By.CSS_SELECTOR, value="[name='q']")
driver.action_chains().hm_move_to_element(search_input).click().hm_send_keys("osn-selenium").perform()

driver.quit()

---

Join the Journey

osn-selenium is an ambitious project aimed at redefining the boundaries of browser automation. We are moving toward a future of true asynchronicity and undetectable human mimicry, and we would love to have you involved!

Whether you are a developer interested in low-level protocol bridges (CDP/BiDi), a mathematician with ideas for better movement algorithms, or an automation specialist with feedback on the API, your contribution is valuable.

How You Can Help:

• Code Contributions: Check out our Roadmap to see what’s currently in development. We are especially looking for collaborators to help build and test the experimental Trio-BiDi bridge.
• Ideas & Feedback: Have a suggestion for a new feature? Or perhaps advice on how to make the Mixin architecture even more robust? We highly value your "wishes" and architectural tips.
• Platform Testing: Help us expand support for macOS or test the framework with different Chromium-based browsers like Brave or Opera.

Get in Touch:

• GitHub Issues: Report bugs or open a "Feature Request" for any new ideas.
• Pull Requests: If you’ve optimized a script or added a new browser flag definition, PRs are always welcome!
• Discussions: Use the repository discussions to brainstorm new approaches or ask questions about the architecture.

Let’s build the most powerful and undetectable automation framework together!