Target Commands

Target commands manage browser targets including tabs, windows, and other browsing contexts.

Overview

The target commands module provides functionality for creating, managing, and controlling browser targets such as tabs, popup windows, and service workers.

pydoll.commands.target_commands

TargetCommands

A class for managing browser targets using Chrome DevTools Protocol.

The Target domain of CDP supports additional targets discovery and allows to attach to them. Targets can represent browser tabs, windows, frames, web workers, service workers, etc. The domain provides methods to create, discover, and control these targets.

This class provides methods to create commands for interacting with browser targets, including creating, activating, attaching to, and closing targets through CDP commands.

activate_target `staticmethod`

activate_target(target_id)

Generates a command to activate (focus) a target.

PARAMETER	DESCRIPTION
`target_id`	ID of the target to activate. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to activate the target. TYPE: `Command[Response]`

attach_to_target `staticmethod`

attach_to_target(target_id, flatten=None)

Generates a command to attach to a target with the given ID.

When attached to a target, you can send commands to it and receive events from it. This is essential for controlling and automating targets like browser tabs.

PARAMETER	DESCRIPTION
`target_id`	ID of the target to attach to. TYPE: `str`
`flatten`	If true, enables "flat" access to the session via specifying sessionId attribute in the commands. This is recommended as the non-flattened mode is being deprecated. See https://crbug.com/991325 TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to attach to the target, which will return a sessionId. TYPE: `Command[AttachToTargetResponse]`

close_target `staticmethod`

close_target(target_id)

Generates a command to close a target.

If the target is a page or a tab, it will be closed. This is equivalent to clicking the close button on a browser tab.

PARAMETER	DESCRIPTION
`target_id`	ID of the target to close. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to close the target, which will return a success flag. TYPE: `Command[Response]`

create_browser_context `staticmethod`

create_browser_context(dispose_on_detach=None, proxy_server=None, proxy_bypass_list=None, origins_with_universal_network_access=None)

Generates a command to create a new empty browser context.

A browser context is similar to an incognito profile but you can have more than one. Each context has its own set of cookies, local storage, and other browser data. This is useful for testing multiple users or isolating sessions.

PARAMETER	DESCRIPTION
`dispose_on_detach`	If specified, the context will be disposed when the debugging session disconnects. TYPE: `Optional[bool]` DEFAULT: `None`
`proxy_server`	Proxy server string, similar to the one passed to --proxy-server command line argument (e.g., "socks5://192.168.1.100:1080"). TYPE: `Optional[str]` DEFAULT: `None`
`proxy_bypass_list`	Proxy bypass list, similar to the one passed to --proxy-bypass-list command line argument (e.g., ".example.com,localhost"). TYPE:* `Optional[str]` DEFAULT: `None`
`origins_with_universal_network_access`	An optional list of origins to grant unlimited cross-origin access to. Parts of the URL other than those constituting origin are ignored. TYPE: `Optional[list[str]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to create a browser context, which will return the ID of the created context. TYPE: `Command[CreateBrowserContextResponse]`

create_target `staticmethod`

create_target(url, left=None, top=None, width=None, height=None, window_state=None, browser_context_id=None, enable_begin_frame_control=None, new_window=None, background=None, for_tab=None, hidden=None)

Generates a command to create a new page (target).

This is one of the primary methods to open a new tab or window with specific properties such as position, size, and browser context.

PARAMETER	DESCRIPTION
`url`	The initial URL the page will navigate to. An empty string indicates about:blank. TYPE: `str`
`left`	Frame left position in device-independent pixels (DIP). Requires newWindow to be true or in headless mode. TYPE: `Optional[int]` DEFAULT: `None`
`top`	Frame top position in DIP. Requires newWindow to be true or in headless mode. TYPE: `Optional[int]` DEFAULT: `None`
`width`	Frame width in DIP. TYPE: `Optional[int]` DEFAULT: `None`
`height`	Frame height in DIP. TYPE: `Optional[int]` DEFAULT: `None`
`window_state`	Frame window state: normal, minimized, maximized, or fullscreen. Default is normal. TYPE: `Optional[WindowState]` DEFAULT: `None`
`browser_context_id`	The browser context to create the page in. If not specified, the default browser context is used. TYPE: `Optional[str]` DEFAULT: `None`
`enable_begin_frame_control`	Whether BeginFrames for this target will be controlled via DevTools (headless shell only, not supported on MacOS yet, false by default). TYPE: `Optional[bool]` DEFAULT: `None`
`new_window`	Whether to create a new window or tab (false by default, not supported by headless shell). TYPE: `Optional[bool]` DEFAULT: `None`
`background`	Whether to create the target in background or foreground (false by default, not supported by headless shell). TYPE: `Optional[bool]` DEFAULT: `None`
`for_tab`	Whether to create the target of type "tab". TYPE: `Optional[bool]` DEFAULT: `None`
`hidden`	Whether to create a hidden target. The hidden target is observable via protocol, but not present in the tab UI strip. Cannot be created with forTab:true, newWindow:true or background:false. The life-time of the tab is limited to the life-time of the session. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to create a target, which will return the ID of the created target. TYPE: `Command[CreateTargetResponse]`

detach_from_target `staticmethod`

detach_from_target(session_id=None)

Generates a command to detach a session from its target.

After detaching, you will no longer receive events from the target and cannot send commands to it.

PARAMETER	DESCRIPTION
`session_id`	Session ID to detach. If not specified, detaches all sessions. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to detach from the target. TYPE: `Command[Response]`

dispose_browser_context `staticmethod`

dispose_browser_context(browser_context_id)

Generates a command to delete a browser context.

All pages belonging to the browser context will be closed without calling their beforeunload hooks. This is similar to closing an incognito profile.

PARAMETER	DESCRIPTION
`browser_context_id`	The ID of the browser context to dispose. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to dispose the browser context. TYPE: `Command[Response]`

get_browser_contexts `staticmethod`

get_browser_contexts()

Generates a command to get all browser contexts created with createBrowserContext.

This is useful for obtaining a list of all available contexts for managing multiple isolated browser sessions.

RETURNS	DESCRIPTION
`Command`	The CDP command to get all browser contexts, which will return an array of browser context IDs. TYPE: `Command[GetBrowserContextsResponse]`

get_targets `staticmethod`

get_targets(filter=None)

Generates a command to retrieve a list of available targets.

Targets include tabs, extensions, web workers, and other attachable entities in the browser. This is useful for discovering what targets exist before attaching to them.

PARAMETER	DESCRIPTION
`filter`	Only targets matching the filter will be reported. If filter is not specified and target discovery is currently enabled, a filter used for target discovery is used for consistency. TYPE: `Optional[list]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to get targets, which will return a list of TargetInfo objects with details about each target. TYPE: `Command[GetTargetsResponse]`

set_auto_attach `staticmethod`

set_auto_attach(auto_attach, wait_for_debugger_on_start=None, flatten=None, filter=None)

Generates a command to control whether to automatically attach to new targets.

This method controls whether to automatically attach to new targets which are considered to be directly related to the current one (for example, iframes or workers). When turned on, it also attaches to all existing related targets. When turned off, it automatically detaches from all currently attached targets.

PARAMETER	DESCRIPTION
`auto_attach`	Whether to auto-attach to related targets. TYPE: `bool`
`wait_for_debugger_on_start`	Whether to pause new targets when attaching to them. Use Runtime.runIfWaitingForDebugger to run paused targets. TYPE: `Optional[bool]` DEFAULT: `None`
`flatten`	Enables "flat" access to the session via specifying sessionId attribute in the commands. This mode is being preferred, and non-flattened mode is being deprecated (see crbug.com/991325). TYPE: `Optional[bool]` DEFAULT: `None`
`filter`	Only targets matching filter will be attached. TYPE: `Optional[list]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to set auto-attach behavior. TYPE: `Command[Response]`

set_discover_targets `staticmethod`

set_discover_targets(discover, filter=None)

Generates a command to control target discovery.

This method controls whether to discover available targets and notify via targetCreated/targetInfoChanged/targetDestroyed events. Target discovery is useful for monitoring when new tabs, workers, or other targets are created or destroyed.

PARAMETER	DESCRIPTION
`discover`	Whether to discover available targets. TYPE: `bool`
`filter`	Only targets matching filter will be discovered. If discover is false, filter must be omitted or empty. TYPE: `Optional[list]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to set target discovery. TYPE: `Command[Response]`

attach_to_browser_target `staticmethod`

attach_to_browser_target(session_id)

Generates a command to attach to the browser target.

This is an experimental method that attaches to the browser target, only using flat sessionId mode. The browser target is a special target that represents the browser itself rather than a page or other content.

PARAMETER	DESCRIPTION
`session_id`	ID of the session to attach to the browser target. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to attach to the browser target, which will return a new session ID. TYPE: `Command[AttachToBrowserTargetResponse]`

get_target_info `staticmethod`

get_target_info(target_id)

Generates a command to get information about a specific target.

This experimental method returns detailed information about a target, such as its type, URL, title, and other properties.

PARAMETER	DESCRIPTION
`target_id`	ID of the target to get information about. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to get target information, which will return a TargetInfo object with details about the target. TYPE: `Command[GetTargetInfoResponse]`

set_remote_locations `staticmethod`

set_remote_locations(locations)

Generates a command to enable target discovery for specified remote locations.

This experimental method enables target discovery for remote locations when setDiscoverTargets was set to true. This is useful for discovering targets on remote devices or in different browser instances.

PARAMETER	DESCRIPTION
`locations`	list of remote locations, each containing a host and port. TYPE: `list[RemoteLocation]`

RETURNS	DESCRIPTION
`Command`	The CDP command to set remote locations for target discovery. TYPE: `Command[Response]`

Usage

Target commands are used internally by browser classes to manage tabs and windows:

from pydoll.commands.target_commands import get_targets, create_target, close_target
from pydoll.connection.connection_handler import ConnectionHandler

# Get all browser targets
connection = ConnectionHandler()
targets = await get_targets(connection)

# Create a new tab
new_target = await create_target(connection, url="https://example.com")

# Close a target
await close_target(connection, target_id=new_target.target_id)

Key Functionality

The target commands module provides functions for:

Target Management

get_targets() - List all browser targets
create_target() - Create new tabs or windows
close_target() - Close specific targets
activate_target() - Bring target to foreground

Target Information

get_target_info() - Get detailed target information
Target types: page, background_page, service_worker, browser
Target states: attached, detached, crashed

Session Management

attach_to_target() - Attach to target for control
detach_from_target() - Detach from target
send_message_to_target() - Send commands to targets

Browser Context

create_browser_context() - Create isolated browser context
dispose_browser_context() - Remove browser context
get_browser_contexts() - List browser contexts

Target Types

Different types of targets can be managed:

Page Targets

# Create a new tab
page_target = await create_target(
    connection,
    url="https://example.com",
    width=1920,
    height=1080,
    browser_context_id=None  # Default context
)

# Create a popup window
popup_target = await create_target(
    connection,
    url="https://popup.example.com",
    width=800,
    height=600,
    new_window=True
)

Incognito Contexts

# Create incognito browser context
incognito_context = await create_browser_context(connection)

# Create tab in incognito context
incognito_tab = await create_target(
    connection,
    url="https://private.example.com",
    browser_context_id=incognito_context.browser_context_id
)

Advanced Features

Target Events

Target commands work with various target events: - Target.targetCreated - New target created - Target.targetDestroyed - Target closed - Target.targetInfoChanged - Target information updated - Target.targetCrashed - Target crashed

Multi-Target Coordination

# Manage multiple tabs
targets = await get_targets(connection)
page_targets = [t for t in targets if t.type == "page"]

for target in page_targets:
    # Perform operations on each tab
    await activate_target(connection, target_id=target.target_id)
    # ... do work in this tab

Target Isolation

# Create isolated browser context for testing
test_context = await create_browser_context(connection)

# All targets in this context are isolated
test_tab1 = await create_target(
    connection, 
    url="https://test1.com",
    browser_context_id=test_context.browser_context_id
)

test_tab2 = await create_target(
    connection,
    url="https://test2.com", 
    browser_context_id=test_context.browser_context_id
)

Browser Integration

Target commands are primarily used internally by the Chrome and Edge browser classes. The high-level browser APIs provide more convenient methods for tab management.

Target Commands

Overview

pydoll.commands.target_commands

TargetCommands

activate_target staticmethod

attach_to_target staticmethod

close_target staticmethod

create_browser_context staticmethod

create_target staticmethod

detach_from_target staticmethod

dispose_browser_context staticmethod

get_browser_contexts staticmethod

get_targets staticmethod

set_auto_attach staticmethod

set_discover_targets staticmethod

attach_to_browser_target staticmethod

get_target_info staticmethod

set_remote_locations staticmethod