Skip to content

Page Commands

Page commands handle page navigation, lifecycle events, and page-level operations.

Overview

The page commands module provides functionality for navigating between pages, managing page lifecycle, handling JavaScript execution, and controlling page behavior.

pydoll.commands.page_commands

PageCommands

This class encapsulates the page commands of the Chrome DevTools Protocol (CDP).

CDP's Page domain allows for interacting with browser pages, including navigation, content manipulation, and page state monitoring. These commands provide powerful capabilities for web automation, testing, and debugging.

The commands defined in this class provide functionality for: - Navigating to URLs and managing page history - Capturing screenshots and generating PDFs - Handling JavaScript dialogs - Enabling and controlling page events - Managing download behavior - Manipulating page content and state

add_script_to_evaluate_on_new_document staticmethod 

add_script_to_evaluate_on_new_document(source, world_name=None, include_command_line_api=None, run_immediately=None)

Creates a command to add a script that will be evaluated when a new document is created.

PARAMETER DESCRIPTION
source

Script source to be evaluated when a new document is created.

TYPE: str

world_name

If specified, creates an isolated world with the given name.

TYPE: Optional[str] DEFAULT: None

include_command_line_api

Whether to include command line API.

TYPE: Optional[bool] DEFAULT: None

run_immediately

Whether to run the script immediately on existing contexts.

TYPE: Optional[bool] DEFAULT: None

RETURNS DESCRIPTION
Command[AddScriptToEvaluateOnNewDocumentResponse]

Command[AddScriptToEvaluateOnNewDocumentResponse]: Command object with the identifier of the added script.

bring_to_front staticmethod 

bring_to_front()

Brings the page to front.

capture_screenshot staticmethod 

capture_screenshot(format=None, quality=None, clip=None, from_surface=None, capture_beyond_viewport=None, optimize_for_speed=None)

Creates a command to capture a screenshot of the current page.

PARAMETER DESCRIPTION
format

Image compression format (jpeg, png, or webp).

TYPE: Optional[str] DEFAULT: None

quality

Compression quality from 0-100 (jpeg only).

TYPE: Optional[int] DEFAULT: None

clip

Region of the page to capture.

TYPE: Optional[Viewport] DEFAULT: None

from_surface

Capture from the surface, not the view.

TYPE: Optional[bool] DEFAULT: None

capture_beyond_viewport

Capture beyond the viewport.

TYPE: Optional[bool] DEFAULT: None

optimize_for_speed

Optimize for speed, not for size.

TYPE: Optional[bool] DEFAULT: None

RETURNS DESCRIPTION
Command[CaptureScreenshotResponse]

Command[CaptureScreenshotResponse]: Command object with base64-encoded image data.

close staticmethod 

close()

Creates a command to close the current page.

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to close the page.

create_isolated_world staticmethod 

create_isolated_world(frame_id, world_name=None, grant_universal_access=None)

Creates a command to create an isolated world for the given frame.

PARAMETER DESCRIPTION
frame_id

ID of the frame in which to create the isolated world.

TYPE: str

world_name

Name to be reported in the Execution Context.

TYPE: Optional[str] DEFAULT: None

grant_universal_access

Whether to grant universal access.

TYPE: Optional[bool] DEFAULT: None

RETURNS DESCRIPTION
Command[CreateIsolatedWorldResponse]

Command[CreateIsolatedWorldResponse]: Command object with the execution context ID.

disable staticmethod 

disable()

Creates a command to disable page domain notifications.

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to disable the Page domain.

enable staticmethod 

enable(enable_file_chooser_opened_event=None)

Creates a command to enable page domain notifications.

PARAMETER DESCRIPTION
enable_file_chooser_opened_event

Whether to emit Page.fileChooserOpened event.

TYPE: Optional[bool] DEFAULT: None

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to enable the Page domain.

get_app_manifest staticmethod 

get_app_manifest(manifest_id=None)

Creates a command to get the manifest for the current document.

RETURNS DESCRIPTION
Command[GetAppManifestResponse]

Command[GetAppManifestResponse]: Command object with manifest information.

get_frame_tree staticmethod 

get_frame_tree()

Creates a command to get the frame tree for the current page.

RETURNS DESCRIPTION
Command[GetFrameTreeResponse]

Command[GetFrameTreeResponse]: Command object with frame tree information.

get_layout_metrics staticmethod 

get_layout_metrics()

Creates a command to get layout metrics for the page.

RETURNS DESCRIPTION
Command[GetLayoutMetricsResponse]

Command[GetLayoutMetricsResponse]: Command object with layout metrics.

get_navigation_history staticmethod 

get_navigation_history()

Creates a command to get the navigation history for the current page.

RETURNS DESCRIPTION
Command[GetNavigationHistoryResponse]

Command[GetNavigationHistoryResponse]: Command object with navigation history.

handle_javascript_dialog staticmethod 

handle_javascript_dialog(accept, prompt_text=None)

Creates a command to handle a JavaScript dialog.

PARAMETER DESCRIPTION
accept

Whether to accept or dismiss the dialog.

TYPE: bool

prompt_text

Text to enter in prompt dialogs.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to handle a JavaScript dialog.

navigate staticmethod 

navigate(url, referrer=None, transition_type=None, frame_id=None, referrer_policy=None)

Creates a command to navigate to a specific URL.

PARAMETER DESCRIPTION
url

URL to navigate to.

TYPE: str

referrer

Referrer URL.

TYPE: Optional[str] DEFAULT: None

transition_type

Intended transition type.

TYPE: Optional[str] DEFAULT: None

frame_id

Frame ID to navigate.

TYPE: Optional[str] DEFAULT: None

referrer_policy

Referrer policy.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
Command[NavigateResponse]

Command[NavigateResponse]: Command object to navigate to a URL.

navigate_to_history_entry staticmethod 

navigate_to_history_entry(entry_id)

Creates a command to navigate to a specific history entry.

PARAMETER DESCRIPTION
entry_id

ID of the history entry to navigate to.

TYPE: int

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to navigate to a history entry.

print_to_pdf staticmethod 

print_to_pdf(landscape=None, display_header_footer=None, print_background=None, scale=None, paper_width=None, paper_height=None, margin_top=None, margin_bottom=None, margin_left=None, margin_right=None, page_ranges=None, header_template=None, footer_template=None, prefer_css_page_size=None, transfer_mode=None, generate_tagged_pdf=None, generate_document_outline=None)

Creates a command to print the current page to PDF.

PARAMETER DESCRIPTION
landscape

Paper orientation.

TYPE: Optional[bool] DEFAULT: None

display_header_footer

Display header and footer.

TYPE: Optional[bool] DEFAULT: None

print_background

Print background graphics.

TYPE: Optional[bool] DEFAULT: None

scale

Scale of the webpage rendering.

TYPE: Optional[float] DEFAULT: None

paper_width

Paper width in inches.

TYPE: Optional[float] DEFAULT: None

paper_height

Paper height in inches.

TYPE: Optional[float] DEFAULT: None

margin_top

Top margin in inches.

TYPE: Optional[float] DEFAULT: None

margin_bottom

Bottom margin in inches.

TYPE: Optional[float] DEFAULT: None

margin_left

Left margin in inches.

TYPE: Optional[float] DEFAULT: None

margin_right

Right margin in inches.

TYPE: Optional[float] DEFAULT: None

page_ranges

Paper ranges to print, e.g., '1-5, 8, 11-13'.

TYPE: Optional[str] DEFAULT: None

header_template

HTML template for the print header.

TYPE: Optional[str] DEFAULT: None

footer_template

HTML template for the print footer.

TYPE: Optional[str] DEFAULT: None

prefer_css_page_size

Whether to prefer page size as defined by CSS.

TYPE: Optional[bool] DEFAULT: None

transfer_mode

Transfer mode.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
Command[PrintToPDFResponse]

Command[PrintToPDFResponse]: Command object to print the page to PDF.

reload staticmethod 

reload(ignore_cache=None, script_to_evaluate_on_load=None, loader_id=None)

Creates a command to reload the current page.

PARAMETER DESCRIPTION
ignore_cache

If true, browser cache is ignored.

TYPE: Optional[bool] DEFAULT: None

script_to_evaluate_on_load

Script to be injected into the page on load.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to reload the page.

reset_navigation_history staticmethod 

reset_navigation_history()

Creates a command to reset the navigation history.

remove_script_to_evaluate_on_new_document staticmethod 

remove_script_to_evaluate_on_new_document(identifier)

Creates a command to remove a script that was added to be evaluated on new documents.

PARAMETER DESCRIPTION
identifier

Identifier of the script to remove.

TYPE: str

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to remove a script.

set_bypass_csp staticmethod 

set_bypass_csp(enabled)

Creates a command to toggle bypassing page CSP.

PARAMETER DESCRIPTION
enabled

Whether to bypass page CSP.

TYPE: bool

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to toggle bypassing page CSP.

set_document_content staticmethod 

set_document_content(frame_id, html)

Creates a command to set the document content of a frame.

PARAMETER DESCRIPTION
frame_id

Frame ID to set the document content for.

TYPE: str

html

HTML content to set.

TYPE: str

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to set the document content.

set_intercept_file_chooser_dialog staticmethod 

set_intercept_file_chooser_dialog(enabled)

Creates a command to set whether to intercept file chooser dialogs.

PARAMETER DESCRIPTION
enabled

Whether to intercept file chooser dialogs.

TYPE: bool

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to set file chooser dialog interception.

set_lifecycle_events_enabled staticmethod 

set_lifecycle_events_enabled(enabled)

Creates a command to enable/disable lifecycle events.

PARAMETER DESCRIPTION
enabled

Whether to enable lifecycle events.

TYPE: bool

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to enable/disable lifecycle events.

stop_loading staticmethod 

stop_loading()

Creates a command to stop loading the page.

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to stop loading the page.

add_compilation_cache staticmethod 

add_compilation_cache(url, data)

Creates a command to add a compilation cache entry.

Experimental: This method is experimental and may be subject to change.

PARAMETER DESCRIPTION
url

URL for which to add the compilation cache entry.

TYPE: str

data

Base64-encoded data.

TYPE: str

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to add a compilation cache entry.

capture_snapshot staticmethod 

capture_snapshot(format='mhtml')

Creates a command to capture a snapshot of the page.

Experimental: This method is experimental and may be subject to change.

PARAMETER DESCRIPTION
format

Format of the snapshot (only 'mhtml' is supported).

TYPE: Literal['mhtml'] DEFAULT: 'mhtml'

RETURNS DESCRIPTION
Command[CaptureSnapshotResponse]

Command[CaptureSnapshotResponse]: Command object to capture a snapshot.

clear_compilation_cache staticmethod 

clear_compilation_cache()

Creates a command to clear the compilation cache.

crash staticmethod 

crash()

Creates a command to crash the page.

generate_test_report staticmethod 

generate_test_report(message, group=None)

Creates a command to generate a test report.

Experimental: This method is experimental and may be subject to change.

PARAMETER DESCRIPTION
message

Message to be displayed in the report.

TYPE: str

group

Group label for the report.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
Command[Response]

Command[Response]: Command object to generate a test report.

get_ad_script_ancestry_ids staticmethod 

get_ad_script_ancestry_ids(frame_id)

Creates a command to get the ad script ancestry IDs for a given frame.

Experimental: This method is experimental and may be subject to change.

PARAMETER DESCRIPTION
frame_id

ID of the frame to get ad script ancestry IDs for.

TYPE: str

RETURNS DESCRIPTION
Command[GetAdScriptAncestryIdsResponse]

Command[GetAdScriptAncestryIdsResponse]: Command object to get ad script ancestry IDs.

get_app_id staticmethod 

get_app_id(app_id=None, recommended_id=None)

Creates a command to get the app ID.

Experimental: This method is experimental and may be subject to change.

PARAMETER DESCRIPTION
app_id

App ID for verification.

TYPE: Optional[str] DEFAULT: None

recommended_id

Recommended app ID.

TYPE: Optional[str] DEFAULT: None

RETURNS DESCRIPTION
Command[GetAppIdResponse]

Command[GetAppIdResponse]: Command object to get the app ID.

get_installability_errors staticmethod 

get_installability_errors()

Creates a command to get the installability errors.

get_origin_trials staticmethod 

get_origin_trials(frame_id)

Creates a command to get origin trials for a given origin.

Experimental: This method is experimental and may be subject to change.

PARAMETER DESCRIPTION
frame_id

Frame ID to get trials for.

TYPE: Optional[str]

RETURNS DESCRIPTION
Command[GetOriginTrialsResponse]

Command[GetOriginTrialsResponse]: Command object to get origin trials.

get_permissions_policy_state staticmethod 

get_permissions_policy_state(frame_id)

Creates a command to get the permissions policy state.

get_resource_content staticmethod 

get_resource_content(frame_id, url)

Creates a command to get the resource content.

get_resource_tree staticmethod 

get_resource_tree()

Creates a command to get the resource tree.

produce_compilation_cache staticmethod 

produce_compilation_cache(scripts)

Creates a command to produce a compilation cache entry.

screencast_frame_ack staticmethod 

screencast_frame_ack(session_id)

Creates a command to acknowledge a screencast frame.

search_in_resource staticmethod 

search_in_resource(frame_id, url, query, case_sensitive=None, is_regex=None)

Creates a command to search for a string in a resource.

set_ad_blocking_enabled staticmethod 

set_ad_blocking_enabled(enabled)

Creates a command to set ad blocking enabled.

set_font_families staticmethod 

set_font_families(font_families, for_scripts)

Creates a command to set font families.

set_font_sizes staticmethod 

set_font_sizes(font_sizes)

Creates a command to set font sizes.

set_prerendering_allowed staticmethod 

set_prerendering_allowed(allowed)

Creates a command to set prerendering allowed.

set_rph_registration_mode staticmethod 

set_rph_registration_mode(mode)

Creates a command to set the RPH registration mode.

set_spc_transaction_mode staticmethod 

set_spc_transaction_mode(mode)

Creates a command to set the SPC transaction mode.

set_web_lifecycle_state staticmethod 

set_web_lifecycle_state(state)

Creates a command to set the web lifecycle state.

start_screencast staticmethod 

start_screencast(format, quality=None, max_width=None, max_height=None, every_nth_frame=None)

Creates a command to start a screencast.

stop_screencast staticmethod 

stop_screencast()

Creates a command to stop a screencast.

wait_for_debugger staticmethod 

wait_for_debugger()

Creates a command to wait for a debugger.

Usage

Page commands are used extensively by the Tab class for navigation and page management:

from pydoll.commands.page_commands import navigate, reload, enable
from pydoll.connection.connection_handler import ConnectionHandler

# Navigate to a URL
connection = ConnectionHandler()
await enable(connection)  # Enable page events
await navigate(connection, url="https://example.com")

# Reload the page
await reload(connection)

Key Functionality

The page commands module provides functions for:

  • navigate() - Navigate to URLs
  • reload() - Reload current page
  • go_back() - Navigate back in history
  • go_forward() - Navigate forward in history
  • stop_loading() - Stop page loading

Page Lifecycle

  • enable() / disable() - Enable/disable page events
  • get_frame_tree() - Get page frame structure
  • get_navigation_history() - Get navigation history

Content Management

  • get_resource_content() - Get page resource content
  • search_in_resource() - Search within page resources
  • set_document_content() - Set page HTML content

Screenshots & PDF

  • capture_screenshot() - Take page screenshots
  • print_to_pdf() - Generate PDF from page
  • capture_snapshot() - Capture page snapshots

JavaScript Execution

  • add_script_to_evaluate_on_new_document() - Add startup scripts
  • remove_script_to_evaluate_on_new_document() - Remove startup scripts

Page Settings

  • set_lifecycle_events_enabled() - Control lifecycle events
  • set_ad_blocking_enabled() - Enable/disable ad blocking
  • set_bypass_csp() - Bypass Content Security Policy

Advanced Features

Frame Management

# Get all frames in the page
frame_tree = await get_frame_tree(connection)
for frame in frame_tree.child_frames:
    print(f"Frame: {frame.frame.url}")

Resource Interception

# Get resource content
content = await get_resource_content(
    connection, 
    frame_id=frame_id, 
    url="https://example.com/script.js"
)

Page Events

The page commands work with various page events: - Page.loadEventFired - Page load completed - Page.domContentEventFired - DOM content loaded - Page.frameNavigated - Frame navigation - Page.frameStartedLoading - Frame loading started

Tab Class Integration

Most page operations are available through the Tab class methods like tab.go_to(), tab.reload(), and tab.screenshot() which provide a more convenient API.