Flags Management

Flags Management Overview

In standard Selenium, configuring a browser often involves passing raw strings like --headless or --user-agent="..." to an Options object. This is prone to typos and hard to maintain.

osn-selenium introduces a structured Flags Management system. Every browser configuration is a typed model, ensuring that your settings are validated before the browser process even starts.

---

Core Concepts

The configuration is divided into four distinct categories of "flags":

Flag Type	Category in Code	Description
Arguments	argument	Command-line flags passed to the browser binary (e.g., --mute-audio).
Experimental Options	experimental_option	Specialized Chromium key-value pairs (e.g., debuggerAddress).
Attributes	attribute	Direct properties of the Selenium Options object (e.g., enable_bidi).
Blink Features	blink_feature	A specific list of internal Blink engine features enabled via --enable-blink-features or --disable-blink-features.

---

Hierarchy of Models

The library uses a hierarchical model structure to maximize code reuse and ensure browser specificity.

BrowserFlags

Located in osn_selenium/flags/models/base.py, this defines the common structure for any browser, containing basic arguments and attributes like se_downloads_enabled.

BlinkFlags

Located in osn_selenium/flags/models/blink.py, this extends the base for all Chromium-based browsers. It adds hundreds of predefined flags (like headless_mode, no_sandbox, proxy_server) and the BlinkFeatures sub-model for engine-level control.

Browser-Specific Models

• ChromeFlags: Specific to Google Chrome.
• EdgeFlags: Specific to Microsoft Edge.
• YandexFlags: Specialized for Yandex Browser.

---

The Flags Manager

The FlagsManager (e.g., ChromeFlagsManager) is the engine that takes your typed models and transforms them into a native Selenium Options object.

Key Responsibilities:

1. Validation: Every flag has an adding_validation_function (e.g., str_adding_validation_function). If you try to set a path that doesn't exist or an empty string, the manager will catch it.
2. MRO of Configuration: Managers support set_flags() (replaces everything) and update_flags() (merges with existing).
3. Command Generation: The manager generates the full CLI string used for manual process launching (see start_command property).

---

Usage Example

Instead of remembering CLI flags, use IDE auto-completion with the typed models.

from osn_selenium.flags.models.chrome import ChromeFlags, ChromeArguments, ChromeAttributes
from osn_selenium.flags.models.blink import BlinkFeatures

from osn_selenium.webdrivers.sync.chrome import ChromeWebDriver


# Define complex configuration using Pydantic models
my_flags = ChromeFlags(
    argument=ChromeArguments(
        headless_mode=True,
        user_agent="Mozilla/5.0 (Custom Engine)",
        mute_audio=True,
        disable_gpu=True
    ),
    blink_feature=BlinkFeatures(
        automation_controlled=False, # Help bypass detection
        heavy_ad_mitigations=True
    ),
    attribute=ChromeAttributes(
        enable_bidi=True
    )
)

driver = ChromeWebDriver(webdriver_path="./chromedriver")

# Apply to a driver
driver.update_settings(flags=my_flags)

---

Custom Flags & Extensibility

While osn-selenium comes with hundreds of predefined flags, the browser landscape changes rapidly. To handle new CLI arguments or experimental options not yet in the library, the framework provides a robust extension mechanism.

Every FlagsManager is strictly validated. If you attempt to set a flag that isn't defined in the manager's registry, the system will raise a FlagNotDefinedError. To add new capabilities, you must define them using FlagDefinition and FlagType.

Defining a New Flag

A FlagDefinition is a contract that tells the manager how to handle a specific setting. It requires:

• name: The key used in your Pydantic model or dictionary.
• command: The actual string passed to the browser (e.g., --new-feature={value}).
• type: The category (argument, experimental_option, attribute, or blink_feature).
• mode: Where this flag should be applied (webdriver_option, startup_argument, or both).
• adding_validation_function: A callable that returns True if the provided value is valid.

If the {value} placeholder is present in the command parameter of a FlagDefinition, the framework will automatically substitute it with the actual argument value during the generation of both WebDriver options and the CLI startup string.

Creating a Custom Manager

You can inject custom definitions directly into a manager's constructor. This allows you to support any browser feature without modifying the library's source code.

from osn_selenium.flags.chrome import ChromeFlagsManager
from osn_selenium.flags.models.base import FlagDefinition
from osn_selenium.flags._validators import str_adding_validation_function

# 1. Define your custom flag
custom_defs = {
    "my_secret_feature": FlagDefinition(
        name="my_secret_feature",
        command="--enable-secret-engine={value}",
        type="argument",
        mode="both",
        adding_validation_function=str_adding_validation_function
    )
}

# 2. Initialize the manager with custom definitions
manager = ChromeFlagsManager(flags_definitions=custom_defs)

# 3. Now the manager accepts 'my_secret_feature' and validates it as a string
manager.update_arguments({"my_secret_feature": "high-performance"})

Support for New Flag Types

If you need to introduce an entirely new category of flags (beyond arguments or experimental options), you can use the FlagType class. This requires providing a set of handler functions:

• set_flag_function / remove_flag_function
• set_flags_function / update_flags_function / clear_flags_function
• build_options_function / build_start_args_function

This deep extensibility ensures that osn-selenium can adapt to any future WebDriver protocol changes or niche browser forks.