refactor(tab): separate execute_script concerns

[3xp0rt]

Refactoring Pull Request

Refactoring Scope

The Tab class's execute_script method in pydoll/browser/tab.py, related tests and documentation.

Related Issue(s)

Addresses user feedback from GitHub Discussion #108 regarding async script execution capabilities

Description

Refactor the execute_script method by separating concerns to improve the API design. The new implementation should support asynchronous execution using await_promise=True and return_by_value=True, provide additional options for flexible usage in code. The original method handled both general script execution and element-specific execution, which has been split into two focused methods:

• execute_script: Enhanced with comprehensive runtime options for general script execution
• execute_element_script: New method specifically for executing scripts with element context

Motivation

Support for asynchronous code.

Before / After

Before

    @overload
    async def execute_script(self, script: str) -> EvaluateResponse: ...

    @overload
    async def execute_script(self, script: str, element: WebElement) -> CallFunctionOnResponse: ...

    async def execute_script(
        self, script: str, element: Optional[WebElement] = None
    ) -> Union[EvaluateResponse, CallFunctionOnResponse]:

After

    async def execute_script(
        self,
        script: str,
        *,
        object_group: Optional[str] = None,
        include_command_line_api: Optional[bool] = None,
        silent: Optional[bool] = None,
        context_id: Optional[int] = None,
        return_by_value: Optional[bool] = None,
        generate_preview: Optional[bool] = None,
        user_gesture: Optional[bool] = None,
        await_promise: Optional[bool] = None,
        throw_on_side_effect: Optional[bool] = None,
        timeout: Optional[float] = None,
        disable_breaks: Optional[bool] = None,
        repl_mode: Optional[bool] = None,
        allow_unsafe_eval_blocked_by_csp: Optional[bool] = None,
        unique_context_id: Optional[str] = None,
        serialization_options: Optional[SerializationOptions] = None,
    ) -> EvaluateResponse:
    
    async def execute_element_script(
        self,
        script: str,
        element: WebElement,
        *,
        arguments: Optional[list[CallArgument]] = None,
        silent: Optional[bool] = None,
        return_by_value: Optional[bool] = None,
        generate_preview: Optional[bool] = None,
        user_gesture: Optional[bool] = None,
        await_promise: Optional[bool] = None,
        execution_context_id: Optional[int] = None,
        object_group: Optional[str] = None,
        throw_on_side_effect: Optional[bool] = None,
        unique_context_id: Optional[str] = None,
        serialization_options: Optional[SerializationOptions] = None,
    ) -> CallFunctionOnResponse:

Performance Impact

• Performance improved
• Performance potentially decreased
• No significant performance change
• Performance impact unknown

Technical Debt

This refactoring addresses several technical debt issues:

• Mixed Responsibilities: The original method handled two different use cases
• Complex Method Signatures: Overloaded methods with optional parameters made the API confusing
• Limited Extensibility: The previous design lacked support for passing additional options and asynchronous execution, restricting flexibility

API Changes

• No changes to public API
• Public API changed, but backward compatible
• Breaking changes to public API

Testing Strategy

• Updated existing tests to use the new method signatures
• Verified that all existing functionality is preserved through the new API

Testing Checklist

• Existing tests updated
• New tests added for previously uncovered cases
• All tests pass
• Code coverage maintained or improved

Risks and Mitigations

• Breaking change for users who relied on the old execute_script(script, element) signature

Checklist before requesting a review

• My code follows the style guidelines of this project
• I have performed a thorough self-review of the refactored code
• I have commented my code, particularly in complex areas
• I have updated documentation if needed
• I have run poetry run task lint and fixed any issues
• I have run poetry run task test and all tests pass
• My commits follow the conventional commits style

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[3xp0rt]

Last commit refactors JavaScript execution by moving execute_element_script functionality from the Tab class to the WebElement class for better encapsulation.