Skip to content

Emulation

The emulation module overrides browser settings for device simulation. For full usage examples, see Emulation.

Methods

  • set_geolocation — simulate a geographic location or a position error
  • set_locale — override the browser locale (e.g. "fr-FR")
  • set_screen_orientation — set screen orientation ({"type": "portrait-primary", "natural": "portrait"})
  • set_timezone — change the browser's time zone
  • set_network_conditions — offline emulation (the spec's only network condition)
  • set_user_agent — override the User-Agent string

Locale override

await client.emulation.set_locale("fr-FR", contexts=["context-id-1"])

Screen orientation

await client.emulation.set_screen_orientation(
    {"type": "portrait-primary", "natural": "portrait"},
    contexts=["context-id-1"],
)

Geolocation with error simulation

# Simulate a position error (e.g. GPS unavailable)
await client.emulation.set_geolocation(
    error={"type": "positionUnavailable"},
    contexts=["context-id-1"],
)

# Or simulate a real position
await client.emulation.set_geolocation(
    coordinates={"latitude": 35.6762, "longitude": 139.6503, "accuracy": 1.0},
    user_contexts=["user-context-id-1"],
)

Reference

EmulationModule

Module for emulating device environment conditions.

Commands
  • set_geolocation — override geolocation coordinates
  • set_network_conditions — throttle or simulate offline network
  • set_timezone — override the browser timezone
  • set_user_agent — override the User-Agent string
Example

await client.emulation.set_geolocation( coordinates={"latitude": 37.7749, "longitude": -122.4194}, contexts=[ctx_id], ) await client.emulation.set_timezone("America/Los_Angeles") await client.emulation.set_user_agent("MyBot/1.0")

Source code in bidiwave/modules/emulation.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
class EmulationModule:
    """Module for emulating device environment conditions.

    Commands:
        - set_geolocation — override geolocation coordinates
        - set_network_conditions — throttle or simulate offline network
        - set_timezone — override the browser timezone
        - set_user_agent — override the User-Agent string

    Example:
        await client.emulation.set_geolocation(
            coordinates={"latitude": 37.7749, "longitude": -122.4194},
            contexts=[ctx_id],
        )
        await client.emulation.set_timezone("America/Los_Angeles")
        await client.emulation.set_user_agent("MyBot/1.0")
    """

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

    async def set_geolocation(
        self,
        coordinates: dict[str, float] | None = None,
        contexts: list[str] | None = None,
        user_contexts: list[str] | None = None,
        error: dict[str, str] | None = None,
    ) -> None:
        """Overrides the geolocation coordinates.

        Args:
            coordinates: Dict with 'latitude' and 'longitude' keys.
                None to clear the override (sends ``coordinates: null``).
            contexts: Context IDs to apply to. None = all.
            user_contexts: User context IDs to apply to. None = all.
            error: Error dict to simulate, e.g. {"type": "positionUnavailable"}.
                Mutually exclusive with `coordinates`.
        """
        if coordinates is not None and error is not None:
            raise ValueError("coordinates and error are mutually exclusive")
        # Spec requires exactly one of `coordinates` (or null) / `error`.
        if error is not None:
            params: dict[str, Any] = {"error": error}
        else:
            params = {"coordinates": coordinates}
        if contexts is not None:
            params["contexts"] = contexts
        if user_contexts is not None:
            params["userContexts"] = user_contexts
        await self._connection.send_command(EMULATION_SET_GEOLOCATION, params)

    async def set_network_conditions(
        self,
        offline: bool = True,
        contexts: list[str] | None = None,
        user_contexts: list[str] | None = None,
    ) -> None:
        """Overrides network conditions.

        Per the W3C BiDi spec (emulation.setNetworkConditions), the only
        supported condition is offline emulation. Pass ``offline=False``
        to clear the override (sends ``networkConditions: null``).

        Args:
            offline: True to simulate offline mode, False to clear.
            contexts: Context IDs to apply to. None = all.
            user_contexts: User context IDs to apply to. None = all.
        """
        params: dict[str, Any] = {
            "networkConditions": {"type": "offline"} if offline else None,
        }
        if contexts is not None:
            params["contexts"] = contexts
        if user_contexts is not None:
            params["userContexts"] = user_contexts
        await self._connection.send_command(
            EMULATION_SET_NETWORK_CONDITIONS, params
        )

    async def set_timezone(
        self,
        timezone: str | None,
        contexts: list[str] | None = None,
        user_contexts: list[str] | None = None,
    ) -> None:
        """Overrides the browser timezone.

        Args:
            timezone: IANA timezone identifier (e.g. "America/New_York").
                None to clear the override (sends ``timezone: null``).
            contexts: Context IDs to apply to. None = all.
            user_contexts: User context IDs to apply to. None = all.
        """
        params: dict[str, Any] = {"timezone": timezone}
        if contexts is not None:
            params["contexts"] = contexts
        if user_contexts is not None:
            params["userContexts"] = user_contexts
        await self._connection.send_command(EMULATION_SET_TIMEZONE, params)

    async def set_user_agent(
        self,
        user_agent: str | None,
        contexts: list[str] | None = None,
        user_contexts: list[str] | None = None,
    ) -> None:
        """Overrides the User-Agent string.

        Per the W3C BiDi spec (emulation.setUserAgentOverride), only the
        User-Agent string itself can be overridden.

        Args:
            user_agent: User-Agent string to set. None to clear the override.
            contexts: Context IDs to apply to. None = all.
            user_contexts: User context IDs to apply to. None = all.
        """
        params: dict[str, Any] = {"userAgent": user_agent}
        if contexts is not None:
            params["contexts"] = contexts
        if user_contexts is not None:
            params["userContexts"] = user_contexts
        await self._connection.send_command(EMULATION_SET_USER_AGENT, params)

    async def set_locale(
        self,
        locale: str | None = None,
        contexts: list[str] | None = None,
        user_contexts: list[str] | None = None,
    ) -> None:
        """Overrides the browser locale.

        Args:
            locale: Locale identifier (e.g. "en-US", "fr-FR").
                None to clear the override (sends ``locale: null``).
            contexts: Context IDs to apply to. None = all.
            user_contexts: User context IDs to apply to. None = all.
        """
        params: dict[str, Any] = {"locale": locale}
        if contexts is not None:
            params["contexts"] = contexts
        if user_contexts is not None:
            params["userContexts"] = user_contexts
        await self._connection.send_command(EMULATION_SET_LOCALE, params)

    async def set_screen_orientation(
        self,
        orientation: dict[str, Any] | None = None,
        contexts: list[str] | None = None,
        user_contexts: list[str] | None = None,
    ) -> None:
        """Overrides the screen orientation.

        Args:
            orientation: Dict with 'natural' ("portrait" or "landscape")
                and 'type' ("portrait-primary", "portrait-secondary",
                "landscape-primary", "landscape-secondary") per the spec's
                emulation.ScreenOrientation. None to clear the override
                (sends ``screenOrientation: null``).
            contexts: Context IDs to apply to. None = all.
            user_contexts: User context IDs to apply to. None = all.
        """
        params: dict[str, Any] = {"screenOrientation": orientation}
        if contexts is not None:
            params["contexts"] = contexts
        if user_contexts is not None:
            params["userContexts"] = user_contexts
        await self._connection.send_command(
            EMULATION_SET_SCREEN_ORIENTATION, params
        )

set_geolocation async 

set_geolocation(coordinates: dict[str, float] | None = None, contexts: list[str] | None = None, user_contexts: list[str] | None = None, error: dict[str, str] | None = None) -> None

Overrides the geolocation coordinates.

Parameters:

Name Type Description Default
coordinates dict[str, float] | None

Dict with 'latitude' and 'longitude' keys. None to clear the override (sends coordinates: null).

 None
contexts list[str] | None

Context IDs to apply to. None = all.

 None
user_contexts list[str] | None

User context IDs to apply to. None = all.

 None
error dict[str, str] | None

Error dict to simulate, e.g. {"type": "positionUnavailable"}. Mutually exclusive with coordinates.

 None
Source code in bidiwave/modules/emulation.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
async def set_geolocation(
    self,
    coordinates: dict[str, float] | None = None,
    contexts: list[str] | None = None,
    user_contexts: list[str] | None = None,
    error: dict[str, str] | None = None,
) -> None:
    """Overrides the geolocation coordinates.

    Args:
        coordinates: Dict with 'latitude' and 'longitude' keys.
            None to clear the override (sends ``coordinates: null``).
        contexts: Context IDs to apply to. None = all.
        user_contexts: User context IDs to apply to. None = all.
        error: Error dict to simulate, e.g. {"type": "positionUnavailable"}.
            Mutually exclusive with `coordinates`.
    """
    if coordinates is not None and error is not None:
        raise ValueError("coordinates and error are mutually exclusive")
    # Spec requires exactly one of `coordinates` (or null) / `error`.
    if error is not None:
        params: dict[str, Any] = {"error": error}
    else:
        params = {"coordinates": coordinates}
    if contexts is not None:
        params["contexts"] = contexts
    if user_contexts is not None:
        params["userContexts"] = user_contexts
    await self._connection.send_command(EMULATION_SET_GEOLOCATION, params)

set_network_conditions async 

set_network_conditions(offline: bool = True, contexts: list[str] | None = None, user_contexts: list[str] | None = None) -> None

Overrides network conditions.

Per the W3C BiDi spec (emulation.setNetworkConditions), the only supported condition is offline emulation. Pass offline=False to clear the override (sends networkConditions: null).

Parameters:

Name Type Description Default
offline bool

True to simulate offline mode, False to clear.

 True
contexts list[str] | None

Context IDs to apply to. None = all.

 None
user_contexts list[str] | None

User context IDs to apply to. None = all.

 None
Source code in bidiwave/modules/emulation.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
async def set_network_conditions(
    self,
    offline: bool = True,
    contexts: list[str] | None = None,
    user_contexts: list[str] | None = None,
) -> None:
    """Overrides network conditions.

    Per the W3C BiDi spec (emulation.setNetworkConditions), the only
    supported condition is offline emulation. Pass ``offline=False``
    to clear the override (sends ``networkConditions: null``).

    Args:
        offline: True to simulate offline mode, False to clear.
        contexts: Context IDs to apply to. None = all.
        user_contexts: User context IDs to apply to. None = all.
    """
    params: dict[str, Any] = {
        "networkConditions": {"type": "offline"} if offline else None,
    }
    if contexts is not None:
        params["contexts"] = contexts
    if user_contexts is not None:
        params["userContexts"] = user_contexts
    await self._connection.send_command(
        EMULATION_SET_NETWORK_CONDITIONS, params
    )

set_timezone async 

set_timezone(timezone: str | None, contexts: list[str] | None = None, user_contexts: list[str] | None = None) -> None

Overrides the browser timezone.

Parameters:

Name Type Description Default
timezone str | None

IANA timezone identifier (e.g. "America/New_York"). None to clear the override (sends timezone: null).

 required
contexts list[str] | None

Context IDs to apply to. None = all.

 None
user_contexts list[str] | None

User context IDs to apply to. None = all.

 None
Source code in bidiwave/modules/emulation.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
async def set_timezone(
    self,
    timezone: str | None,
    contexts: list[str] | None = None,
    user_contexts: list[str] | None = None,
) -> None:
    """Overrides the browser timezone.

    Args:
        timezone: IANA timezone identifier (e.g. "America/New_York").
            None to clear the override (sends ``timezone: null``).
        contexts: Context IDs to apply to. None = all.
        user_contexts: User context IDs to apply to. None = all.
    """
    params: dict[str, Any] = {"timezone": timezone}
    if contexts is not None:
        params["contexts"] = contexts
    if user_contexts is not None:
        params["userContexts"] = user_contexts
    await self._connection.send_command(EMULATION_SET_TIMEZONE, params)

set_user_agent async 

set_user_agent(user_agent: str | None, contexts: list[str] | None = None, user_contexts: list[str] | None = None) -> None

Overrides the User-Agent string.

Per the W3C BiDi spec (emulation.setUserAgentOverride), only the User-Agent string itself can be overridden.

Parameters:

Name Type Description Default
user_agent str | None

User-Agent string to set. None to clear the override.

 required
contexts list[str] | None

Context IDs to apply to. None = all.

 None
user_contexts list[str] | None

User context IDs to apply to. None = all.

 None
Source code in bidiwave/modules/emulation.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
async def set_user_agent(
    self,
    user_agent: str | None,
    contexts: list[str] | None = None,
    user_contexts: list[str] | None = None,
) -> None:
    """Overrides the User-Agent string.

    Per the W3C BiDi spec (emulation.setUserAgentOverride), only the
    User-Agent string itself can be overridden.

    Args:
        user_agent: User-Agent string to set. None to clear the override.
        contexts: Context IDs to apply to. None = all.
        user_contexts: User context IDs to apply to. None = all.
    """
    params: dict[str, Any] = {"userAgent": user_agent}
    if contexts is not None:
        params["contexts"] = contexts
    if user_contexts is not None:
        params["userContexts"] = user_contexts
    await self._connection.send_command(EMULATION_SET_USER_AGENT, params)

set_locale async 

set_locale(locale: str | None = None, contexts: list[str] | None = None, user_contexts: list[str] | None = None) -> None

Overrides the browser locale.

Parameters:

Name Type Description Default
locale str | None

Locale identifier (e.g. "en-US", "fr-FR"). None to clear the override (sends locale: null).

 None
contexts list[str] | None

Context IDs to apply to. None = all.

 None
user_contexts list[str] | None

User context IDs to apply to. None = all.

 None
Source code in bidiwave/modules/emulation.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
async def set_locale(
    self,
    locale: str | None = None,
    contexts: list[str] | None = None,
    user_contexts: list[str] | None = None,
) -> None:
    """Overrides the browser locale.

    Args:
        locale: Locale identifier (e.g. "en-US", "fr-FR").
            None to clear the override (sends ``locale: null``).
        contexts: Context IDs to apply to. None = all.
        user_contexts: User context IDs to apply to. None = all.
    """
    params: dict[str, Any] = {"locale": locale}
    if contexts is not None:
        params["contexts"] = contexts
    if user_contexts is not None:
        params["userContexts"] = user_contexts
    await self._connection.send_command(EMULATION_SET_LOCALE, params)

set_screen_orientation async 

set_screen_orientation(orientation: dict[str, Any] | None = None, contexts: list[str] | None = None, user_contexts: list[str] | None = None) -> None

Overrides the screen orientation.

Parameters:

Name Type Description Default
orientation dict[str, Any] | None

Dict with 'natural' ("portrait" or "landscape") and 'type' ("portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary") per the spec's emulation.ScreenOrientation. None to clear the override (sends screenOrientation: null).

 None
contexts list[str] | None

Context IDs to apply to. None = all.

 None
user_contexts list[str] | None

User context IDs to apply to. None = all.

 None
Source code in bidiwave/modules/emulation.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
async def set_screen_orientation(
    self,
    orientation: dict[str, Any] | None = None,
    contexts: list[str] | None = None,
    user_contexts: list[str] | None = None,
) -> None:
    """Overrides the screen orientation.

    Args:
        orientation: Dict with 'natural' ("portrait" or "landscape")
            and 'type' ("portrait-primary", "portrait-secondary",
            "landscape-primary", "landscape-secondary") per the spec's
            emulation.ScreenOrientation. None to clear the override
            (sends ``screenOrientation: null``).
        contexts: Context IDs to apply to. None = all.
        user_contexts: User context IDs to apply to. None = all.
    """
    params: dict[str, Any] = {"screenOrientation": orientation}
    if contexts is not None:
        params["contexts"] = contexts
    if user_contexts is not None:
        params["userContexts"] = user_contexts
    await self._connection.send_command(
        EMULATION_SET_SCREEN_ORIENTATION, params
    )