Tab

pydoll.browser.tab.Tab

Tab(browser, connection_port, target_id, browser_context_id=None)

Bases: FindElementsMixin

Controls a browser tab via Chrome DevTools Protocol.

Primary interface for web page automation including navigation, DOM manipulation, JavaScript execution, event handling, network monitoring, and specialized tasks like Cloudflare bypass.

This class implements a singleton pattern based on target_id to ensure only one Tab instance exists per browser tab.

Initialize tab controller for existing browser tab.

PARAMETER	DESCRIPTION
browser	Browser instance that created this tab. TYPE: Browser
connection_port	CDP WebSocket port. TYPE: int
target_id	CDP target identifier for this tab. TYPE: str
browser_context_id	Optional browser context ID. TYPE: Optional[str] DEFAULT: None

page_events_enabled property

page_events_enabled

Whether CDP Page domain events are enabled.

network_events_enabled property

network_events_enabled

Whether CDP Network domain events are enabled.

fetch_events_enabled property

fetch_events_enabled

Whether CDP Fetch domain events (request interception) are enabled.

dom_events_enabled property

dom_events_enabled

Whether CDP DOM domain events are enabled.

runtime_events_enabled property

runtime_events_enabled

Whether CDP Runtime domain events are enabled.

intercept_file_chooser_dialog_enabled property

intercept_file_chooser_dialog_enabled

Whether file chooser dialog interception is active.

current_url async property

current_url

Get current page URL (reflects redirects and client-side navigation).

page_source async property

page_source

Get complete HTML source of current page (live DOM state).

get_instance classmethod

get_instance(target_id)

Get existing Tab instance for target_id if it exists.

PARAMETER	DESCRIPTION
target_id	Target ID to look up. TYPE: str

RETURNS	DESCRIPTION
Optional[Tab]	Existing Tab instance or None if not found.

get_all_instances classmethod

get_all_instances()

Get all active Tab instances.

RETURNS	DESCRIPTION
dict[str, Tab]	Dictionary mapping target_id to Tab instances.

enable_page_events async

enable_page_events()

Enable CDP Page domain events (load, navigation, dialogs, etc.).

enable_network_events async

enable_network_events()

Enable CDP Network domain events (requests, responses, etc.).

enable_fetch_events async

enable_fetch_events(handle_auth=False, resource_type=None, request_stage=None)

Enable CDP Fetch domain for request interception.

PARAMETER	DESCRIPTION
handle_auth	Intercept authentication challenges. TYPE: bool DEFAULT: False
resource_type	Filter by resource type (all if None). TYPE: Optional[ResourceType] DEFAULT: None
request_stage	When to intercept (Request/Response). TYPE: Optional[RequestStage] DEFAULT: None

Note

Intercepted requests must be explicitly continued or timeout.

enable_dom_events async

enable_dom_events()

Enable CDP DOM domain events (document structure changes).

enable_runtime_events async

enable_runtime_events()

Enable CDP Runtime domain events.

enable_intercept_file_chooser_dialog async

enable_intercept_file_chooser_dialog()

Enable file chooser dialog interception for automated uploads.

Note

Use expect_file_chooser context manager for convenience.

enable_auto_solve_cloudflare_captcha async

enable_auto_solve_cloudflare_captcha(custom_selector=None, time_before_click=2, time_to_wait_captcha=5)

Enable automatic Cloudflare Turnstile captcha bypass.

PARAMETER	DESCRIPTION
custom_selector	Custom captcha selector (default: cf-turnstile class). TYPE: Optional[tuple[By, str]] DEFAULT: None
time_before_click	Delay before clicking captcha (default 2s). TYPE: int DEFAULT: 2
time_to_wait_captcha	Timeout for captcha detection (default 5s). TYPE: int DEFAULT: 5

disable_fetch_events async

disable_fetch_events()

Disable CDP Fetch domain and release paused requests.

disable_page_events async

disable_page_events()

Disable CDP Page domain events.

disable_network_events async

disable_network_events()

Disable CDP Network domain events.

disable_dom_events async

disable_dom_events()

Disable CDP DOM domain events.

disable_runtime_events async

disable_runtime_events()

Disable CDP Runtime domain events.

disable_intercept_file_chooser_dialog async

disable_intercept_file_chooser_dialog()

Disable file chooser dialog interception.

disable_auto_solve_cloudflare_captcha async

disable_auto_solve_cloudflare_captcha()

Disable automatic Cloudflare Turnstile captcha bypass.

close async

close()

Close this browser tab.

Note

Tab instance becomes invalid after calling this method.

get_frame async

get_frame(frame)

Get Tab object for interacting with iframe content.

PARAMETER	DESCRIPTION
frame	Tab representing the iframe tag. TYPE: WebElement

RETURNS	DESCRIPTION
IFrame	Tab instance configured for iframe interaction.

RAISES	DESCRIPTION
NotAnIFrame	If element is not an iframe.
InvalidIFrame	If iframe lacks valid src attribute.
IFrameNotFound	If iframe target not found in browser.

get_cookies async

get_cookies()

Get all cookies accessible from current page.

get_network_response_body async

get_network_response_body(request_id)

Get the response body for a given request ID.

PARAMETER	DESCRIPTION
request_id	Request ID to get the response body for. TYPE: str

RETURNS	DESCRIPTION
str	The response body for the given request ID.

RAISES	DESCRIPTION
NetworkEventsNotEnabled	If network events are not enabled.

get_network_logs async

get_network_logs(filter=None)

Get network logs.

PARAMETER	DESCRIPTION
filter	Filter to apply to the network logs. TYPE: Optional[str] DEFAULT: None

RETURNS	DESCRIPTION
list[NetworkLog]	The network logs.

RAISES	DESCRIPTION
NetworkEventsNotEnabled	If network events are not enabled.

set_cookies async

set_cookies(cookies)

Set multiple cookies for current page.

PARAMETER	DESCRIPTION
cookies	Cookie parameters (name/value required, others optional). TYPE: list[CookieParam]

Note

Defaults to current page's domain if not specified.

delete_all_cookies async

delete_all_cookies()

Delete all cookies from current browser context.

go_to async

go_to(url, timeout=300)

Navigate to URL and wait for loading to complete.

Refreshes if URL matches current page.

PARAMETER	DESCRIPTION
url	Target URL to navigate to. TYPE: str
timeout	Maximum seconds to wait for page load (default 300). TYPE: int DEFAULT: 300

RAISES	DESCRIPTION
PageLoadTimeout	If page doesn't finish loading within timeout.

refresh async

refresh(ignore_cache=False, script_to_evaluate_on_load=None)

Reload current page and wait for completion.

PARAMETER	DESCRIPTION
ignore_cache	Bypass browser cache if True. TYPE: bool DEFAULT: False
script_to_evaluate_on_load	JavaScript to execute after load. TYPE: Optional[str] DEFAULT: None

RAISES	DESCRIPTION
PageLoadTimeout	If page doesn't finish loading within timeout.

take_screenshot async

take_screenshot(path=None, quality=100, as_base64=False)

Capture screenshot of current page.

PARAMETER	DESCRIPTION
path	File path for screenshot (extension determines format). TYPE: Optional[str] DEFAULT: None
quality	Image quality 0-100 (default 100). TYPE: int DEFAULT: 100
as_base64	Return as base64 string instead of saving file. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Optional[str]	Base64 screenshot data if as_base64=True, None otherwise.

RAISES	DESCRIPTION
InvalidFileExtension	If file extension not supported.
ValueError	If path is None and as_base64 is False.

print_to_pdf async

print_to_pdf(path, landscape=False, display_header_footer=False, print_background=True, scale=1.0, as_base64=False)

Generate PDF of current page.

PARAMETER	DESCRIPTION
path	File path for PDF output. TYPE: str
landscape	Use landscape orientation. TYPE: bool DEFAULT: False
display_header_footer	Include header/footer. TYPE: bool DEFAULT: False
print_background	Include background graphics. TYPE: bool DEFAULT: True
scale	Scale factor (0.1-2.0). TYPE: float DEFAULT: 1.0
as_base64	Return as base64 string instead of saving. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Optional[str]	Base64 PDF data if as_base64=True, None otherwise.

has_dialog async

has_dialog()

Check if JavaScript dialog is currently displayed.

Note

Page events must be enabled to detect dialogs.

get_dialog_message async

get_dialog_message()

Get message text from current JavaScript dialog.

RAISES	DESCRIPTION
NoDialogPresent	If no dialog is currently displayed.

handle_dialog async

handle_dialog(accept, prompt_text=None)

Respond to JavaScript dialog.

PARAMETER	DESCRIPTION
accept	Accept/confirm dialog if True, dismiss/cancel if False. TYPE: bool
prompt_text	Text for prompt dialogs (ignored for alert/confirm). TYPE: Optional[str] DEFAULT: None

RAISES	DESCRIPTION
NoDialogPresent	If no dialog is currently displayed.

Note

Page events must be enabled to handle dialogs.

execute_script async

execute_script(script: str) -> EvaluateResponse

execute_script(script: str, element: WebElement) -> CallFunctionOnResponse

execute_script(script, element=None)

Execute JavaScript in page context.

PARAMETER	DESCRIPTION
script	JavaScript code to execute. TYPE: str
element	Element context (use 'argument' in script to reference). TYPE: Optional[WebElement] DEFAULT: None

Examples:

await page.execute_script('argument.click()', element) await page.execute_script('argument.value = "Hello"', element)

RAISES	DESCRIPTION
InvalidScriptWithElement	If script contains 'argument' but no element is provided.

continue_request async

continue_request(request_id, url=None, method=None, post_data=None, headers=None, intercept_response=None)

Continue paused request without modifications.

fail_request async

fail_request(request_id, error_reason)

Fail request with error code.

fulfill_request async

fulfill_request(request_id, response_code, response_headers=None, body=None, response_phrase=None)

Fulfill request with response data.

expect_file_chooser async

expect_file_chooser(files)

Context manager for automatic file upload handling.

PARAMETER	DESCRIPTION
files	File path(s) for upload. TYPE: Union[str, Path, list[Union[str, Path]]]

expect_and_bypass_cloudflare_captcha async

expect_and_bypass_cloudflare_captcha(custom_selector=None, time_before_click=2, time_to_wait_captcha=5)

Context manager for automatic Cloudflare captcha bypass.

PARAMETER	DESCRIPTION
custom_selector	Custom captcha selector (default: cf-turnstile class). TYPE: Optional[tuple[By, str]] DEFAULT: None
time_before_click	Delay before clicking (default 2s). TYPE: int DEFAULT: 2
time_to_wait_captcha	Timeout for captcha detection (default 5s). TYPE: int DEFAULT: 5

on async

on(event_name, callback, temporary=False)

Register CDP event listener.

Callback runs in background task to prevent blocking.

PARAMETER	DESCRIPTION
event_name	CDP event name (e.g., 'Page.loadEventFired'). TYPE: str
callback	Function called on event (sync or async). TYPE: Callable[[dict], Any]
temporary	Remove after first invocation. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
int	Callback ID for removal.

Note

Corresponding domain must be enabled before events fire.

find async

find(id=None, class_name=None, name=None, tag_name=None, text=None, timeout=0, find_all=False, raise_exc=True, **attributes)

Find element(s) using combination of common HTML attributes.

Flexible element location using standard attributes. Multiple attributes can be combined for specific selectors (builds XPath when multiple specified).

PARAMETER	DESCRIPTION
id	Element ID attribute value. TYPE: Optional[str] DEFAULT: None
class_name	CSS class name to match. TYPE: Optional[str] DEFAULT: None
name	Element name attribute value. TYPE: Optional[str] DEFAULT: None
tag_name	HTML tag name (e.g., "div", "input"). TYPE: Optional[str] DEFAULT: None
text	Text content to match within element. TYPE: Optional[str] DEFAULT: None
timeout	Maximum seconds to wait for elements to appear. TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True
**attributes	Additional HTML attributes to match. TYPE: dict[str, str] DEFAULT: {}

RETURNS	DESCRIPTION
Union[WebElement, list[WebElement], None]	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ValueError	If no search criteria provided.
ElementNotFound	If no elements found and raise_exc=True.
WaitElementTimeout	If timeout specified and no elements appear in time.

query async

query(expression, timeout=0, find_all=False, raise_exc=True)

Find element(s) using raw CSS selector or XPath expression.

Direct access using CSS or XPath syntax. Selector type automatically determined based on expression pattern.

PARAMETER	DESCRIPTION
expression	Selector expression (CSS, XPath, ID with #, class with .). TYPE: str
timeout	Maximum seconds to wait for elements to appear. TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Union[WebElement, list[WebElement], None]	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ElementNotFound	If no elements found and raise_exc=True.
WaitElementTimeout	If timeout specified and no elements appear in time.

find_or_wait_element async

find_or_wait_element(by, value, timeout=0, find_all=False, raise_exc=True)

Core element finding method with optional waiting capability.

Searches for elements with flexible waiting. If timeout specified, repeatedly attempts to find elements with 0.5s delays until success or timeout. Used by higher-level find() and query() methods.

PARAMETER	DESCRIPTION
by	Selector strategy (CSS_SELECTOR, XPATH, ID, etc.). TYPE: By
value	Selector value to locate element(s). TYPE: str
timeout	Maximum seconds to wait (0 = no waiting). TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Union[WebElement, list[WebElement], None]	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ElementNotFound	If no elements found with timeout=0 and raise_exc=True.
WaitElementTimeout	If elements not found within timeout and raise_exc=True.