Preload

The preload module injects JavaScript before page load. For full usage examples, see Preload Scripts.

Methods

add_preload_script

Inject a function that runs before the page's own scripts:

result = await client.preload.add_preload_script(
    function_declaration="() => { window.myFlag = true; }",
    contexts=["context-id-1"],
)
# result.script = "preload-script-id"

Preload scripts can also be scoped to specific user contexts:

result = await client.preload.add_preload_script(
    function_declaration="() => { window.myFlag = true; }",
    user_contexts=["user-context-id-1"],
)

remove_preload_script

Remove a previously added preload script:

await client.preload.remove_preload_script("preload-script-id")

Reference

PreloadModule

Module for managing preload scripts.

Preload scripts are injected into pages before any other script runs, allowing you to modify the page environment early.

Commands

• add_preload_script — inject a script before page load
• remove_preload_script — remove a previously added script

Example

script_id = await client.preload.add_script( "() => { window.__injected = true; }", )

... navigate and verify ...

await client.preload.remove_script(script_id)

Source code in bidiwave/modules/preload.py

class PreloadModule:
    """Module for managing preload scripts.

    Preload scripts are injected into pages before any other script runs,
    allowing you to modify the page environment early.

    Commands:
        - add_preload_script — inject a script before page load
        - remove_preload_script — remove a previously added script

    Example:
        script_id = await client.preload.add_script(
            "() => { window.__injected = true; }",
        )
        # ... navigate and verify ...
        await client.preload.remove_script(script_id)
    """

    def __init__(self, connection: Connection) -> None:
        self._connection = connection

    async def add_script(
        self,
        function_declaration: str,
        arguments: list[dict[str, Any]] | None = None,
        contexts: list[str] | None = None,
        user_contexts: list[str] | None = None,
        sandbox: str | None = None,
    ) -> str:
        """Adds a preload script.

        Args:
            function_declaration: JS function to execute before page load.
            arguments: Arguments to pass to the function.
            contexts: Context IDs where the script should run. None = all.
            user_contexts: User context IDs where the script should run. None = all.
            sandbox: Sandbox name to run the script in.

        Returns:
            Preload script ID for later removal.
        """
        params: dict[str, Any] = {
            "functionDeclaration": function_declaration,
        }
        if arguments is not None:
            params["arguments"] = arguments
        if contexts is not None:
            params["contexts"] = contexts
        if user_contexts is not None:
            params["userContexts"] = user_contexts
        if sandbox is not None:
            params["sandbox"] = sandbox
        result = await self._connection.send_command(PRELOAD_ADD_SCRIPT, params)
        parsed = AddPreloadScriptResult.model_validate(result)
        return parsed.script

    async def remove_script(self, script_id: str) -> None:
        """Removes a preload script.

        Args:
            script_id: ID returned by add_script.
        """
        await self._connection.send_command(
            PRELOAD_REMOVE_SCRIPT, {"script": script_id}
        )

add_script async

add_script(function_declaration: str, arguments: list[dict[str, Any]] | None = None, contexts: list[str] | None = None, user_contexts: list[str] | None = None, sandbox: str | None = None) -> str

Adds a preload script.

Parameters:

Name	Type	Description	Default
function_declaration	str	JS function to execute before page load.	required
arguments	list[dict[str, Any]] | None	Arguments to pass to the function.	None
contexts	list[str] | None	Context IDs where the script should run. None = all.	None
user_contexts	list[str] | None	User context IDs where the script should run. None = all.	None
sandbox	str | None	Sandbox name to run the script in.	None

Returns:

Type	Description
str	Preload script ID for later removal.

Source code in bidiwave/modules/preload.py

async def add_script(
    self,
    function_declaration: str,
    arguments: list[dict[str, Any]] | None = None,
    contexts: list[str] | None = None,
    user_contexts: list[str] | None = None,
    sandbox: str | None = None,
) -> str:
    """Adds a preload script.

    Args:
        function_declaration: JS function to execute before page load.
        arguments: Arguments to pass to the function.
        contexts: Context IDs where the script should run. None = all.
        user_contexts: User context IDs where the script should run. None = all.
        sandbox: Sandbox name to run the script in.

    Returns:
        Preload script ID for later removal.
    """
    params: dict[str, Any] = {
        "functionDeclaration": function_declaration,
    }
    if arguments is not None:
        params["arguments"] = arguments
    if contexts is not None:
        params["contexts"] = contexts
    if user_contexts is not None:
        params["userContexts"] = user_contexts
    if sandbox is not None:
        params["sandbox"] = sandbox
    result = await self._connection.send_command(PRELOAD_ADD_SCRIPT, params)
    parsed = AddPreloadScriptResult.model_validate(result)
    return parsed.script

remove_script async

remove_script(script_id: str) -> None

Removes a preload script.

Parameters:

Name	Type	Description	Default
script_id	str	ID returned by add_script.	required

Source code in bidiwave/modules/preload.py

async def remove_script(self, script_id: str) -> None:
    """Removes a preload script.

    Args:
        script_id: ID returned by add_script.
    """
    await self._connection.send_command(
        PRELOAD_REMOVE_SCRIPT, {"script": script_id}
    )