Geckordp

https://jpramosi.github.io/geckordp/
Admin
Geckordp is a Python client library for Firefox DevTools that enables remote debugging, web UI...
Tokens:36,238
Snippets:200
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Basic geckordp Usage Example

Source: https://jpramosi.github.io/geckordp/index.html

This example demonstrates how to start Firefox, connect to it using RDPClient, and retrieve a list of open tabs. It requires Firefox to be installed and accessible.

```python
import json

from geckordp.actors.root import RootActor
from geckordp.firefox import Firefox
from geckordp.profile import ProfileManager
from geckordp.rdp_client import RDPClient

""" Uncomment to enable debug output
"""
# from geckordp.settings import GECKORDP
# GECKORDP.DEBUG = 1
# GECKORDP.DEBUG_REQUEST = 1
# GECKORDP.DEBUG_RESPONSE = 1


def main():
    # clone default profile to 'geckordp'
    pm = ProfileManager()
    profile_name = "geckordp"
    port = 6000
    pm.clone("default-release", profile_name)
    profile = pm.get_profile_by_name(profile_name)
    profile.set_required_configs()

    # start firefox with specified profile
    Firefox.start("https://example.com/", port, profile_name, ["-headless"])

    # create client and connect to firefox
    client = RDPClient()
    client.connect("localhost", port)

    # initialize root
    root = RootActor(client)

    # get a list of tabs
    tabs = root.list_tabs()
    print(json.dumps(tabs, indent=2))

    input()


if __name__ == "__main__":
    main()

```

--------------------------------

### Initialize and Start Firefox Profile

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Clones the default Firefox profile, sets required configurations, and starts Firefox in headless mode with the specified profile and port. This setup is necessary before establishing an RDP connection.

```python
# clone default profile to 'geckordp'
    pm = ProfileManager()
    profile_name = "geckop"
    pm.clone("default-release", profile_name)
    profile = pm.get_profile_by_name(profile_name)
    profile.set_required_configs()

    # start firefox with specified profile
    Firefox.start("https://example.com/", args.port, profile_name, ["-headless"])
```

--------------------------------

### Firefox.start

Source: https://jpramosi.github.io/geckordp/geckordp.firefox.html

Starts a new Firefox instance with specified RDP server settings and profile configuration.

```APIDOC
## POST Firefox.start

### Description
Starts a firefox instance with the specified URL, port, and profile.

### Method
Static Method

### Parameters
- **url** (str) - Required - The url for the start page
- **port** (int) - Required - The port to use for the rdp server
- **profile** (str) - Required - The profile to use
- **append_args** (List[str]) - Optional - Additional args for Firefox
- **override_firefox_path** (str) - Optional - Overrides the default firefox binary path
- **auto_kill** (bool) - Optional - Enables the termination of firefox if the python process is also terminated
- **wait** (bool) - Optional - Waits for the firefox instance to finish loading

### Response
- **Return Type** (subprocess.Popen) - The process handle.
```

--------------------------------

### Install Temporary Add-on with AddonsActor

Source: https://jpramosi.github.io/geckordp/actors/actors.addon.addons.html

Use the `install_temporary_addon` method from the `AddonsActor` class to install a temporary add-on. Provide the path to the add-on as a string argument.

```python
install_temporary_addon(_addon_path : str_)
```

--------------------------------

### Installing a Temporary Addon

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

Installs a temporary Firefox addon from a given path. If the addon is not already installed, this function handles its installation and returns the addon ID.

```python
# install temporary addon if not found, else set flag for reloading it
addons = [
    addon for addon in root.list_addons() if addon_path in addon.get("url", "")
]
reload_now = False
if len(addons) == 0:
    print(f"install temporary addon from '{addon_path}'")
    response = AddonsActor(
        client, root_actor_ids["addonsActor"]
    ).install_temporary_addon(addon_path)
    addon_id = response.get("id", None)
    if addon_id is None:
        print(f"addon could not be loaded:\n'{json.dumps(response, indent=2)}'")
        return
    print(f"addon '{addon_id}' loaded")
else:
    print("addon already installed, start reloading it")
    reload_now = True
```

--------------------------------

### Iterate Through Web Extensions

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Lists all installed web extensions and initializes a WebExtensionActor for each. This allows for interaction with browser extensions.

```python
# WebExtensionActor
    ###################################################
    for descriptor in ROOT.list_addons():
        EXTENSION = WebExtensionActor(client, descriptor["actor"])
```

--------------------------------

### Initialize Geckordp and Retrieve Cookies

Source: https://jpramosi.github.io/geckordp/examples/cookie_storage.html

Sets up the RDP client, clones a profile, starts Firefox, and uses a watcher to extract cookie storage data.

```python
GECKORDP.DEBUG_RESPONSE = 1


def main():
    # parse arguments
    parser = argparse.ArgumentParser(description="")
    parser.add_argument(
        "--host", type=str, default="localhost", help="The host to connect to"
    )
    parser.add_argument(
        "--port", type=int, default="6000", help="The port to connect to"
    )
    args, _ = parser.parse_known_args()

    # clone default profile to 'geckordp'
    pm = ProfileManager()
    profile_name = "geckordp"
    pm.clone("default-release", profile_name)
    profile = pm.get_profile_by_name(profile_name)
    profile.set_required_configs()

    # start firefox with specified profile
    Firefox.start(
        "https://samesitetest.com/cookies/set", args.port, profile_name, ["-headless"]
    )

    # create client and connect to firefox
    client = RDPClient()
    client.connect(args.host, args.port)

    # initialize root
    root = RootActor(client)

    # get a single tab from tabs and retrieve its actor ID
    tabs = root.list_tabs()
    tab_descriptor = tabs[0]
    tab = TabActor(client, tab_descriptor["actor"])

    # initialize watcher
    watcher_ctx = tab.get_watcher()
    watcher = WatcherActor(client, watcher_ctx["actor"])

    ###################################################
    # This procedure will retrieve the cookie resource
    # which contains the actor and hosts

    # cookie data
    cookie_resource = {}
    cookie_fut = Future()

    # receive here resource data of cookie storage
    async def on_cookie_resource(data: dict):
        array = data.get("array", [])
        for obj in array:
            obj: list
            for i, item in enumerate(obj):
                item: str | list
                if isinstance(item, str) and "cookies" in item:
                    # obj[i + 1] = next item in array
                    for cookie_obj in obj[i + 1]:
                        cookie_obj: dict
                        if "cookie" in cookie_obj.get("actor", ""):
                            # just get the first one for example purposes
                            try:
                                cookie_fut.set_result(cookie_obj)
                            except:
                                pass
                            break

    # add event listener with the specified watcher actor ID
    # - watcher.actor_id = Resources.COOKIE
    # - watcher.actor_id = Resources.INDEXED
    # - actor_ids["actor"] = Resources.CACHE_STORAGE
    # - actor_ids["actor"] = Resources.LOCAL_STORAGE
    # - actor_ids["actor"] = Resources.SESSION_STORAGE
    client.add_event_listener(
        watcher.actor_id, Events.Watcher.RESOURCES_AVAILABLE_ARRAY, on_cookie_resource
    )

    # set frame as target and notify server to watch for cookie resources
    watcher.watch_targets(WatcherActor.Targets.FRAME)
    watcher.watch_resources([Resources.COOKIE])

    # wait for resource to be available within 3 seconds
    cookie_resource = cookie_fut.result(3.0)

    # get data from resource
    hosts = cookie_resource.get("hosts", {})
    cookie_storage_actor_id = cookie_resource.get("actor", "")
    cookie_actor = CookieStorageActor(client, cookie_storage_actor_id)

    # get specific url from hosts which will be used to retrieve storage objects
    # the first host can also be used, since only cookies will be shown for the current web page
    host = ""
    for h, _ in hosts.items():
        if "samesitetest.com" in h:
            host = h
    if host == "":
        raise RuntimeError("host not found")

    # retrieve the actual cookie list for this host
    cookie_objects = cookie_actor.get_store_objects(host, options={"sessionString": ""})
    print(json.dumps(cookie_objects, indent=2))
```

--------------------------------

### POST /addons/install_temporary_addon

Source: https://jpramosi.github.io/geckordp/actors/actors.addon.addons.html

Installs a temporary addon into the Firefox instance using the AddonsActor.

```APIDOC
## POST /addons/install_temporary_addon

### Description
Installs a temporary addon from the local file system into the target Firefox instance.

### Method
POST

### Parameters
#### Request Body
- **addon_path** (str) - Required - The local file system path to the addon file to be installed.

### Request Example
{
  "addon_path": "/path/to/extension.xpi"
}

### Response
#### Success Response (200)
- **result** (object) - The result of the installation process.
```

--------------------------------

### Install geckordp with venv

Source: https://jpramosi.github.io/geckordp/index.html

Install geckordp within a Python virtual environment. Activate the environment before installing.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade geckordp
```

--------------------------------

### Start Web Console Listeners

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the WebConsoleActor and starts its listeners. This is used for receiving console messages and events from the browser.

```python
# WebConsoleActor
    ###################################################
    CONSOLE = WebConsoleActor(client, actor_ids["consoleActor"])
    CONSOLE.start_listeners([])
```

--------------------------------

### MemoryActor start_recording_allocations() Method

Source: https://jpramosi.github.io/geckordp/actors/actors.memory.html

Starts recording memory allocations. Optional arguments for probability and maximum log length can be provided.

```python
start_recording_allocations(_probability : float | None = None_, _max_log_length : int | None = None_)
```

--------------------------------

### Listing All Installed Addons

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

Prints a JSON-formatted list of all currently installed Firefox addons. This command is useful for identifying addon IDs and their associated URLs.

```python
# if user just wants to know the list of addons, print it and return
if args.list:
    print(json.dumps(root.list_addons(), indent=2))
    return
```

--------------------------------

### Initialize GeckoDP Actors

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

This script imports all available actors from the geckordp library, demonstrating the initialization procedure. It includes setup for debugging if uncommented.

```python
""" This example demonstrates the initialization procedure of every available actor. """

# pylint: disable=unused-variable
# pylint: disable=invalid-name
import argparse
import json
from concurrent.futures import Future

from geckordp.actors.accessibility.accessibility import AccessibilityActor
from geckordp.actors.accessibility.accessible import AccessibleActor
from geckordp.actors.accessibility.accessible_walker import AccessibleWalkerActor
from geckordp.actors.accessibility.parent_accessibility import ParentAccessibilityActor
from geckordp.actors.accessibility.simulator import SimulatorActor
from geckordp.actors.addon.addons import AddonsActor
from geckordp.actors.addon.web_extension_inspected_window import \
    WebExtensionInspectedWindowActor
from geckordp.actors.descriptors.process import ProcessActor
from geckordp.actors.descriptors.tab import TabActor
from geckordp.actors.descriptors.web_extension import WebExtensionActor
from geckordp.actors.descriptors.worker import WorkerActor
from geckordp.actors.device import DeviceActor
from geckordp.actors.events import Events
from geckordp.actors.heap_snapshot import HeapSnapshotActor
from geckordp.actors.inspector import InspectorActor
from geckordp.actors.memory import MemoryActor
from geckordp.actors.network_content import NetworkContentActor
from geckordp.actors.network_event import NetworkEventActor
from geckordp.actors.network_parent import NetworkParentActor
from geckordp.actors.node import NodeActor
from geckordp.actors.node_list import NodeListActor
from geckordp.actors.preference import PreferenceActor
from geckordp.actors.resources import Resources
from geckordp.actors.root import RootActor
from geckordp.actors.screenshot import ScreenshotActor
from geckordp.actors.source import SourceActor
from geckordp.actors.storage import \
    CacheStorageActor,
    CookieStorageActor,
    IndexedDBStorageActor,
    LocalStorageActor,
    SessionStorageActor
from geckordp.actors.string import StringActor
from geckordp.actors.target_configuration import TargetConfigurationActor
from geckordp.actors.targets.content_process import ContentProcessActor
from geckordp.actors.targets.window_global import WindowGlobalActor
from geckordp.actors.thread import ThreadActor
from geckordp.actors.thread_configuration import ThreadConfigurationActor
from geckordp.actors.walker import WalkerActor
from geckordp.actors.watcher import WatcherActor
from geckordp.actors.web_console import WebConsoleActor
from geckordp.firefox import Firefox
from geckordp.profile import ProfileManager
from geckordp.rdp_client import RDPClient

""" Uncomment to enable debug output
"""
# from geckordp.settings import GECKORDP
# GECKORDP.DEBUG = 1
# GECKORDP.DEBUG_REQUEST = 1

```

--------------------------------

### Generate Sphinx Documentation

Source: https://jpramosi.github.io/geckordp/index.html

Generate HTML documentation using Sphinx. Ensure you have Sphinx installed and configured in the docs directory.

```bash
sphinx-build -a -c docs/src -b html docs/build docs
```

--------------------------------

### Install geckordp with pip

Source: https://jpramosi.github.io/geckordp/index.html

Install the geckordp package using pip. The develop extra includes development dependencies.

```bash
pip install --upgrade geckordp
# python -m pip install --upgrade geckordp
# python -m pip install --upgrade geckordp[develop]
```

--------------------------------

### Take Heap Snapshot with GeckoDP

Source: https://jpramosi.github.io/geckordp/examples/heap_snapshot.html

This script demonstrates how to take a heap snapshot of a Firefox tab. It requires setting up a profile, starting Firefox, connecting via RDP, and then using the Memory and HeapSnapshot actors to save the snapshot. Ensure the output file has a .fxsnapshot extension.

```python
""" This example demonstrates how to take a heap snapshot.
"""

import base64
import datetime
import os
from pathlib import Path

from geckordp.actors.descriptors.tab import TabActor
from geckordp.actors.heap_snapshot import HeapSnapshotActor
from geckordp.actors.memory import MemoryActor
from geckordp.actors.root import RootActor
from geckordp.firefox import Firefox
from geckordp.profile import ProfileManager
from geckordp.rdp_client import RDPClient

""" Uncomment to enable debug output
"""
# from geckordp.settings import GECKORDP
# GECKORDP.DEBUG = 1
# GECKORDP.DEBUG_REQUEST = 1
# GECKORDP.DEBUG_RESPONSE = 1


def screenshot(
    heap_snapshot_actor: HeapSnapshotActor, snapshot_id: str, file: Path
) -> bool:
    path = Path(file).absolute()

    if path.suffix != ".fxsnapshot":
        raise RuntimeError("type must be .fxsnapshot")

    response = heap_snapshot_actor.transfer_heap_snapshot(snapshot_id)
    data = base64.b64decode(response["data"])
    assert response["data-decoded-size"] == len(data)

    if file == "":
        return False

    Path(os.path.dirname(path)).mkdir(parents=True, exist_ok=True)
    with open(str(path), "wb") as f:
        f.write(data)

    return os.access(str(path), os.R_OK)


def main():
    # At the moment not working, see tests/actors/test_heap_snapshot.py

    # clone default profile to 'geckordp'
    pm = ProfileManager()
    profile_name = "geckordp"
    port = 6000
    pm.clone("default-release", profile_name)
    profile = pm.get_profile_by_name(profile_name)
    profile.set_required_configs()

    # start firefox with specified profile
    Firefox.start("https://example.com/", port, profile_name, ["-headless"])

    # create client and connect to firefox
    client = RDPClient()
    client.connect("localhost", port)

    # initialize root
    root = RootActor(client)
    root_actor_ids = root.get_root()

    # get a single tab from tabs and retrieve its actor ID and context
    tabs = root.list_tabs()
    tab_descriptor = tabs[0]
    tab = TabActor(client, tab_descriptor["actor"])
    actor_ids = tab.get_target()

    # initialize memory actor and retrieve the snapshot id
    memory = MemoryActor(client, actor_ids["memoryActor"])
    memory.attach()
    snapshot_id = memory.save_heap_snapshot()

    # initialize heap snapshot actor to transfer and create a heap snapshot file
    snapshot_actor = HeapSnapshotActor(client, root_actor_ids["heapSnapshotFileActor"])
    date_string =
        (
            datetime.datetime.now()
            .replace(microsecond=0)
            .isoformat()
            .replace(":", "")
            .replace("-", "")
        )
    snapshot_path = Path(f"Heap-{date_string}.fxsnapshot")
    info_url = "https://developer.mozilla.org/en-US/docs/Tools/Memory/Basic_operations#saving_and_loading_snapshots"
    if screenshot(snapshot_actor, snapshot_id, snapshot_path):
        print(
            f"successfull snapshot: {snapshot_path}\n\nTo load a snapshot, visit {info_url} for more information"
        )
    else:
        print("failed to take a snapshot")

    input()


if __name__ == "__main__":
    main()

```

--------------------------------

### Exemplary GPG Output

Source: https://jpramosi.github.io/geckordp/index.html

This is an example of the expected output when verifying a GPG signature. It confirms the signature is good and shows the key details.

```text
# exemplary output:
gpg: Signature made Di 03 Sep 2024 11:19:17 CEST
gpg:                using RSA key 21F942661941E642894267539B8551A5AEA1227A
gpg:                issuer "jimmy.pramosi@protonmail.com"
gpg: Good signature from "Jimmy Pramosi (git) <jimmy.pramosi@protonmail.com>" [ultimate]
```

--------------------------------

### Checking Addon Existence via List Addons

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

Verifies if an addon is present in the list of installed addons by checking its URL. This is used after attempting to install or to confirm an existing addon.

```python
# check whether addon can be found via list_addons()
addons = [
    addon for addon in root.list_addons() if addon_path in addon.get("url", "")
]
if len(addons) == 0:
    print("addon wasn't found in list")
    return
```

--------------------------------

### Main Execution Loop with File Watching

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

Starts the main loop of the GeckoDP tool, keeping the observer alive and listening for keyboard interrupts to stop the process gracefully. It disconnects the RDP client upon exit.

```python
# sleep and let the observer handle file updates
try:
    while True:
        sleep(1)
except KeyboardInterrupt:
    observer.stop()
    client.disconnect()


if __name__ == "__main__":
    main()
```

--------------------------------

### Run geckordp Tests

Source: https://jpramosi.github.io/geckordp/index.html

Clone the geckordp repository and run the tests within a virtual environment. This is useful for verifying the installation and for development.

```bash
cd <your-repositories-path>
git clone https://github.com/jpramosi/geckordp
cd geckordp
python -m venv .venv
source .venv/bin/activate
python -m pip install -e $PWD
pytest tests/ &> test.log
```

--------------------------------

### Forcing an Immediate Addon Reload

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

If the addon was already installed, this code block forces an immediate reload by simulating a file system event. This ensures the latest version is loaded.

```python
# reload now if flag was set
if reload_now:
    ev = FileSystemEvent(addon_path)
    ev.event_type = EVENT_TYPE_CREATED  # type: ignore
    ev.is_directory = True
    event_handler.reload(ev)
```

--------------------------------

### Initialize Simulator Actor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the SimulatorActor using the AccessibilityActor to get the simulator context. This actor is likely used for simulating user interactions or device conditions.

```python
# SimulatorActor
    ###################################################
    simulator = SimulatorActor(client, ACCESSIBILITY.get_simulator())
```

--------------------------------

### List and Process Processes

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Lists all running processes and iterates through them. For each process, it retrieves target context and initializes a WebConsoleActor. If a process is not the parent, it also initializes a ContentProcessActor.

```python
# ContentProcessActor
    ###################################################
    process_descriptors = ROOT.list_processes()
    for descriptor in process_descriptors:
        actor_id = descriptor["actor"]
        is_parent = descriptor["isParent"]

        PROCESS = ProcessActor(client, actor_id)
        target_ctx = PROCESS.get_target()

        CONSOLE = WebConsoleActor(client, target_ctx["consoleActor"])

        if not is_parent:
            CONTENT_PROCESS = ContentProcessActor(client, target_ctx["actor"])
```

--------------------------------

### Watch and Retrieve LocalStorage Resources

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Sets up a listener to watch for Local Storage resources and retrieves the first available actor. Requires the WATCHER to be initialized and watching for LOCAL_STORAGE resources.

```python
local_resource = {}
    local_fut = Future()

    async def on_local_resource(data: dict):
        array = data.get("array", [])
        for sub_array in array:
            sub_array: list
            for i, item in enumerate(sub_array):
                item: str | list
                if isinstance(item, str) and "local-storage" in item:
                    # obj[i + 1] = next item in array
                    for obj in sub_array[i + 1]:
                        obj: dict
                        if "local" in obj.get("actor", ""):
                            # just get the first one for example purposes
                            try:
                                local_fut.set_result(obj)
                            except:
                                pass
                            break

    client.add_event_listener(
        global_target_ctx["actor"],
        Events.Watcher.RESOURCES_AVAILABLE_ARRAY,
        on_local_resource,
    )

    WATCHER.watch_resources([Resources.LOCAL_STORAGE])

    local_resource = local_fut.result(3.0)

    local_storage_id = local_resource.get("actor", "")
    LOCAL = LocalStorageActor(client, local_storage_id)
```

--------------------------------

### StringActor.substring()

Source: https://jpramosi.github.io/geckordp/actors/actors.string.html

Retrieves a substring from a string actor based on the provided start and end indices.

```APIDOC
## StringActor.substring()

### Description
Retrieves a specific portion of a string managed by the StringActor.

### Parameters
#### Arguments
- **start** (int) - Required - The starting index of the substring.
- **end** (int) - Required - The ending index of the substring.
```

--------------------------------

### Connecting to Firefox RDP Client

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

Initializes an RDPClient and establishes a connection to the specified host and port. This is a prerequisite for interacting with Firefox's debugging capabilities.

```python
# create client and connect to firefox
client = RDPClient()
client.connect(args.host, args.port)
```

--------------------------------

### Initialize TargetConfigurationActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the TargetConfigurationActor for configuring targets. Requires a client and target configuration context.

```python
target_config_ctx = WATCHER.get_target_configuration_actor()
TARGET_CONFIG = TargetConfigurationActor(client, target_config_ctx["actor"])
```

--------------------------------

### Register Resource Listener and Navigate

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Registers a listener for resource availability and triggers navigation to a target URL.

```python
"""
    - register handler and trigger it by visiting a new page
    - received actor IDs can be also stored temporary
      and initiated later
    """
    client.add_event_listener(
        watcher_ctx["actor"],
        Events.Watcher.RESOURCES_AVAILABLE_ARRAY,
        on_resource_available,
    )

    WEB.navigate_to("https://example.com/")

    input()
```

--------------------------------

### Initialize Browser and Tab Actors

Source: https://jpramosi.github.io/geckordp/index.html

Required sequence of actor initializations for browser and tab sessions.

```text
RDPClient()                 -> .connect()
    v
RootActor()                 -> .get_root()
    v
DeviceActor()               -> .get_description()
    v
ProcessActor()              -> .get_target()
    v
WebConsoleActor()           -> .start_listeners([])
    v
ContentProcessActor()       -> .list_workers()
```

```text
TabActor()                  -> .get_target()*
    v
WebConsoleActor()           -> .start_listeners([])*
    v
ThreadActor()               -> .attach()*
    v
WatcherActor()              -> .watch_resources(...)*
    v
TargetConfigurationActor()
```

--------------------------------

### Watch and Retrieve SessionStorage Resources

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Sets up a listener to watch for Session Storage resources and retrieves the first available actor. Requires the WATCHER to be initialized and watching for FRAME targets and SESSION_STORAGE resources.

```python
session_resource = {}
    session_fut = Future()

    async def on_session_resource(data: dict):
        array = data.get("array", [])
        for sub_array in array:
            sub_array: list
            for i, item in enumerate(sub_array):
                item: str | list
                if isinstance(item, str) and "session-storage" in item:
                    # obj[i + 1] = next item in array
                    for obj in sub_array[i + 1]:
                        obj: dict
                        if "session" in obj.get("actor", ""):
                            # just get the first one for example purposes
                            try:
                                session_fut.set_result(obj)
                            except:
                                pass
                            break

    client.add_event_listener(
        global_target_ctx["actor"],
        Events.Watcher.RESOURCES_AVAILABLE_ARRAY,
        on_session_resource,
    )

    WATCHER.watch_targets(WatcherActor.Targets.FRAME)
    WATCHER.watch_resources([Resources.SESSION_STORAGE])

    session_resource = session_fut.result(3.0)

    session_storage_id = session_resource.get("actor", "")
    SESSION = SessionStorageActor(client, session_storage_id)
```

--------------------------------

### Initialize ScreenshotActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the ScreenshotActor for capturing screenshots.

```python
SCREENSHOT = ScreenshotActor(client, root_actor_ids["screenshotActor"])
```

--------------------------------

### Iterate and Initialize SourceActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Iterates through thread sources and initializes a SourceActor for each available source descriptor. Requires a client and thread actor.

```python
for descriptor in THREAD.sources():
    if descriptor.get("actor", None) is not None:
        SOURCE = SourceActor(client, descriptor["actor"])
```

--------------------------------

### Watch for Target Availability

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Sets up an event listener to watch for available targets and retrieves the global target context. This involves watching for FRAME targets and setting a future result when a matching target is found.

```python
global_target_ctx = {}
target_fut = Future()

def on_target(data: dict):
    if "target" not in data or "browsingContextID" not in data["target"]:
        return
    if tab_ctx["browsingContextID"] == data["target"]["browsingContextID"]:
        target_fut.set_result(data["target"])

client.add_event_listener(
    WATCHER.actor_id, Events.Watcher.TARGET_AVAILABLE_FORM, on_target
)

try:
    WATCHER.watch_targets(WatcherActor.Targets.FRAME)
    global_target_ctx = target_fut.result(3.0)
finally:
    client.remove_event_listener(
        WATCHER.actor_id, Events.Watcher.TARGET_AVAILABLE_FORM, on_target
    )
```

--------------------------------

### RDPClient Connection Methods

Source: https://jpramosi.github.io/geckordp/geckordp.rdp_client.html

Methods for establishing and checking the connection to the Firefox debug server.

```APIDOC
## connect(host, port)

### Description
Connects to the firefox debug server.

### Parameters
#### Request Body
- **host** (str) - Required - The host to connect to, usually 'localhost'
- **port** (int) - Required - The port to use, default '6000'

### Response
#### Success Response (200)
- **response** (dict | None) - The server response on successful established connection.

## connected()

### Description
Check whether the client is currently connected to the server.

### Response
#### Success Response (200)
- **status** (bool) - True: Connected; False: Disconnected

## disconnect()

### Description
Disconnects from the debug server.
```

--------------------------------

### Initialize ThreadConfigurationActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the ThreadConfigurationActor for configuring threads. Requires a client and thread configuration context.

```python
thread_config_ctx = WATCHER.get_thread_configuration_actor()
THREAD_CONFIG = ThreadConfigurationActor(client, thread_config_ctx["actor"])
```

--------------------------------

### Watch and Retrieve IndexedDB Resources

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Sets up a listener to watch for IndexedDB resources and retrieves the first available actor. Requires the WATCHER to be initialized and watching for FRAME targets and INDEXED_DB resources.

```python
indexed_resource = {}
    indexed_fut = Future()

    async def on_indexed_resource(data: dict):
        array = data.get("array", [])
        for sub_array in array:
            sub_array: list
            for i, item in enumerate(sub_array):
                item: str | list
                if isinstance(item, str) and "indexed-db" in item:
                    # obj[i + 1] = next item in array
                    for obj in sub_array[i + 1]:
                        obj: dict
                        if "indexedDB" in obj.get("actor", ""):
                            # just get the first one for example purposes
                            try:
                                indexed_fut.set_result(obj)
                            except:
                                pass
                            break

    client.add_event_listener(
        WATCHER.actor_id,
        Events.Watcher.RESOURCES_AVAILABLE_ARRAY, on_indexed_resource
    )

    WATCHER.watch_targets(WatcherActor.Targets.FRAME)
    WATCHER.watch_resources([Resources.INDEXED_DB])

    indexed_resource = indexed_fut.result(3.0)

    indexed_storage_id = indexed_resource.get("actor", "")
    INDEXED = IndexedDBStorageActor(client, indexed_storage_id)
```

--------------------------------

### Firefox.get_binary_path

Source: https://jpramosi.github.io/geckordp/geckordp.firefox.html

Retrieves the file system path to the Firefox binary.

```APIDOC
## GET Firefox.get_binary_path

### Description
Returns the path of the firefox binary.

### Method
Static Method

### Response
- **Return Type** (str) - The path of the firefox binary.

### Errors
- **RuntimeError** - If platform is not supported or firefox is not found.
```

--------------------------------

### geckordp.settings Configuration

Source: https://jpramosi.github.io/geckordp/geckordp.settings.html

Accessing and configuring global settings for the geckordp library.

```APIDOC
## geckordp.settings.Settings

### Description
Provides access to global configuration settings for geckordp. These settings can be retrieved or modified to control debugging behavior and logging output.

### Properties
- **DEBUG** (int) - Controls debug mode (0: disabled, 1: enabled). Env: GECKORDP_DEBUG
- **DEBUG_EVENTS** (int) - Logs all received events (0: disabled, 1: enabled). Env: GECKORDP_DEBUG_EVENTS
- **DEBUG_REQUEST** (int) - Logs all sent requests (0: disabled, 1: enabled). Env: GECKORDP_DEBUG_REQUEST
- **DEBUG_REQUEST_FORMAT** (int) - Formats debug print output for requests (0: disabled, 1: enabled). Env: GECKORDP_DEBUG_REQUEST_FORMAT
- **DEBUG_RESPONSE** (int) - Logs all received responses (0: disabled, 1: enabled). Env: GECKORDP_DEBUG_RESPONSE
- **DEBUG_RESPONSE_FORMAT** (int) - Formats debug print output for responses (0: disabled, 1: enabled). Env: GECKORDP_DEBUG_RESPONSE_FORMAT
- **LOG_FILE** (str) - Path to log file (empty string: disabled). Env: GECKORDP_LOG_FILE
- **LOG_LEVEL** (str) - Logging severity level ('debug', 'info', 'warn', 'error', 'fatal'). Env: GECKORDP_LOG_LEVEL
```

--------------------------------

### Initialize PreferenceActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the PreferenceActor for managing browser preferences. Requires a client and the root actor ID for preference.

```python
PERFERENCE = PreferenceActor(client, root_actor_ids["preferenceActor"])
```

--------------------------------

### Scheduling Directory Observer for Addon Reloading

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

Sets up an observer to watch the addon's directory for changes. When changes are detected, the `DirectoryObserver` will trigger a reload of the addon.

```python
# retrieve the ID of the found addon and start the file watcher
event_handler = DirectoryObserver(WebExtensionActor(client, addons[0]["actor"]))
observer = Observer()
observer.schedule(event_handler, path=addon_path, recursive=True)
observer.start()
```

--------------------------------

### Command-Line Argument Parsing for GeckoDP

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

This function sets up argument parsing for the GeckoDP tool, allowing users to specify connection details, addon paths, and operational modes like listing addons or visiting the debug page.

```python
def main():
    # parse arguments
    parser = argparse.ArgumentParser(description="")
    parser.add_argument(
        "--host", type=str, default="localhost", help="The host to connect to"
    )
    parser.add_argument(
        "--port", type=int, default="6000", help="The port to connect to"
    )
    parser.add_argument(
        "--addon", type=str, default="", metavar="<addonpath>", help="The addon path"
    )
    parser.add_argument("--list", action="store_true", help="List all addons")
    parser.add_argument(
        "--visit", action="store_true", help="Visit the debug page of the addon"
    )
    args, _ = parser.parse_known_args()

    if args.addon == "":
        parser.print_help()
        return 1
```

--------------------------------

### SimulatorActor.simulate()

Source: https://jpramosi.github.io/geckordp/actors/actors.accessibility.simulator.html

Simulates accessibility features for testing purposes.

```APIDOC
## POST /actors/accessibility/simulator/simulate

### Description
Simulates accessibility features for testing purposes.

### Method
POST

### Endpoint
/actors/accessibility/simulator/simulate

### Parameters
#### Request Body
- **simulate_matrix** (Types) - Required - The type of simulation to perform. Possible values are ACHROMATOPSIA, CONTRAST_LOSS, DEUTERANOPIA, NONE, PROTANOPIA, TRITANOPIA.

### Request Example
```json
{
  "simulate_matrix": "CONTRAST_LOSS"
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the simulation.

#### Response Example
```json
{
  "result": {}
}
```
```

--------------------------------

### Enable Debug Logging

Source: https://jpramosi.github.io/geckordp/index.html

Configuration settings to print RDP request and response packets for debugging.

```python
from geckordp.settings import GECKORDP
GECKORDP.DEBUG = 1
GECKORDP.DEBUG_REQUEST = 1
GECKORDP.DEBUG_RESPONSE = 1
# environment variables can also be used for e.g.
# GECKORDP_DEBUG_RESPONSE=1
```

--------------------------------

### Initialize WalkerActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the WalkerActor for DOM traversal. Requires a client and a walker context.

```python
walker_ctx = INSPECTOR.get_walker()
WALKER = WalkerActor(client, walker_ctx["actor"])
```

--------------------------------

### ResourceActor Methods

Source: https://jpramosi.github.io/geckordp/actors/actors.resources.html

Methods for managing resource monitoring in the geckordp framework.

```APIDOC
## ResourceActor Methods

### Description
Methods to control the lifecycle of resource monitoring for specific resource types.

### Parameters
#### Request Body
- **resources** (List[Resources]) - Required - A list of resource types to watch, unwatch, or clear.

### Methods
- **watch_resources(resources)**: Starts monitoring the specified resource types.
- **unwatch_resources(resources)**: Stops monitoring the specified resource types.
- **clear_resources(resources)**: Clears the specified resource types.
```

--------------------------------

### WebConsoleActor Methods

Source: https://jpramosi.github.io/geckordp/actors/actors.web_console.html

This section details the methods available on the WebConsoleActor for interacting with the web console.

```APIDOC
## WebConsoleActor Methods

### Description
Provides methods to interact with the web console, including evaluating JavaScript, managing messages, and controlling listeners.

### Methods

#### `autocomplete(text: str, cursor = 0, frame_actor = '', selected_node_actor = '', authorized_evaluations_json: dict | None = None, expression_vars_json: dict | None = None)`

- **text** (str) - The text to autocomplete.
- **cursor** (int) - The cursor position.
- **frame_actor** (str) - The actor for the frame.
- **selected_node_actor** (str) - The actor for the selected node.
- **authorized_evaluations_json** (dict | None) - JSON object for authorized evaluations.
- **expression_vars_json** (dict | None) - JSON object for expression variables.

#### `clear_messages_cache()`

Clears the messages cache.

#### `evaluate_js_async(text: str, eager = False, frame_actor = '', selected_node_actor = '', selected_object_actor = '', inner_window_id = -1, mapped: dict | None = None)`

- **text** (str) - The JavaScript code to evaluate.
- **eager** (bool) - Whether to evaluate eagerly.
- **frame_actor** (str) - The actor for the frame.
- **selected_node_actor** (str) - The actor for the selected node.
- **selected_object_actor** (str) - The actor for the selected object.
- **inner_window_id** (int) - The inner window ID.
- **mapped** (dict | None) - Mapped data.

#### `get_cached_messages(message_types: List[MessageTypes])`

- **message_types** (List[MessageTypes]) - A list of message types to retrieve.

#### `start_listeners(listeners: List[Listeners])`

- **listeners** (List[Listeners]) - A list of listeners to start.

#### `stop_listeners(listeners: List[Listeners])`

- **listeners** (List[Listeners]) - A list of listeners to stop.

### Enums

#### `Listeners`

- **CONSOLE_API** ('ConsoleAPI')
- **DOCUMENT_EVENTS** ('DocumentEvents')
- **FILE_ACTIVITY** ('FileActivity')
- **PAGE_ERROR** ('PageError')
- **REFLOW_ACTIVITY** ('ReflowActivity')

#### `MessageTypes`

- **CONSOLE_API** ('ConsoleAPI')
- **PAGE_ERROR** ('PageError')
```

--------------------------------

### Connect to Firefox Remote Debugging Protocol

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Establishes a connection to the Firefox RDP server using the RDPClient. Requires the host and port to be specified.

```python
# RDPClient
    ###################################################
    client = RDPClient()
    client.connect(args.host, args.port)
```

--------------------------------

### Initialize HeapSnapshotActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the HeapSnapshotActor for heap snapshot operations. Requires a client and the root actor ID for heap snapshot.

```python
SNAPSHOT = HeapSnapshotActor(client, root_actor_ids["heapSnapshotFileActor"])
```

--------------------------------

### DirectoryObserver for File System Events

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

This class observes file system events for a given directory and triggers a reload of the associated addon when changes are detected. It uses a timer to debounce rapid file changes.

```python
class DirectoryObserver(FileSystemEventHandler):

    def __init__(self, addon_actor: WebExtensionActor):
        self.__delay_sec = 0.7
        self.__addon = addon_actor
        self.__delay_timer = Timer(-1, self.reload)

    def on_any_event(self, event: FileSystemEvent):
        self.__delay_trigger(event)

    def __delay_trigger(self, event: FileSystemEvent):
        self.__delay_timer.cancel()
        self.__delay_timer = Timer(self.__delay_sec, self.reload, args=[event])
        self.__delay_timer.start()

    def reload(self, event: FileSystemEvent):
        response = self.__addon.reload()
        print(f"reload '{event.src_path}':\n{json.dumps(response, indent=2)}")
```

--------------------------------

### Navigating to Addon Debugger Page

Source: https://jpramosi.github.io/geckordp/examples/addon_reloader.html

Opens the Firefox developer tools for a specific extension in a new tab. This allows for live debugging of the extension's code and behavior.

```python
# visit extension page with debugger
if args.visit:
    tab = TabActor(client, root.current_tab()["actor"])
    tab_actor_ids = tab.get_target()
    web = WindowGlobalActor(client, tab_actor_ids["actor"])
    web.navigate_to(
        f"about:devtools-toolbox?id={quote(addons[0]['id'])}&type=extension"
    )
```

--------------------------------

### Access Device Actor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the DeviceActor using the client and the device actor ID obtained from the root actors. This actor provides information and control over the device.

```python
# DeviceActor
    ###################################################
    DEVICE = DeviceActor(client, root_actor_ids["deviceActor"])
```

--------------------------------

### Initialize CookieStorageActor

Source: https://jpramosi.github.io/geckordp/examples/actor_initialization.html

Initializes the CookieStorageActor for managing cookies.

```python
COOKIE = CookieStorageActor(client, cookie_storage_id)
```

--------------------------------

### Check Package Signature

Source: https://jpramosi.github.io/geckordp/index.html

Download the geckordp package and verify its signature using GPG. This ensures the integrity and authenticity of the downloaded file.

```bash
pip download --no-deps geckordp
wget https://github.com/jpramosi.gpg -O pub.gpg
wget https://raw.githubusercontent.com/jpramosi/geckordp/master/signatures/geckordp-latest-py3-none-any.whl.asc -O latest.asc
gpg --no-default-keyring --output pub.sig --dearmor pub.gpg
gpg --no-default-keyring --keyring ./pub.sig --verify latest.asc geckordp-*.whl
```

--------------------------------

### DeviceActor Class

Source: https://jpramosi.github.io/geckordp/actors/actors.device.html

Information about the DeviceActor class, its inheritance, and available methods.

```APIDOC
## actors.device.DeviceActor

### Description
Represents a device actor within the geckordp framework. This class inherits from the base `Actor` class.

### Method
`get_description()`

### Endpoint
N/A (This is a class method, not a direct API endpoint)

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **description** (dict) - A dictionary containing device-related information.

### Response Example
```json
{
  "description": {
    "deviceName": "Example Device",
    "os": "ExampleOS",
    "osVersion": "1.0"
  }
}
```
```

--------------------------------

### List Firefox Tabs via RDP

Source: https://jpramosi.github.io/geckordp/examples/list_tabs.html

This script manages Firefox profiles, launches the browser if necessary, and uses the RootActor to list all open tabs. It requires the geckordp library and assumes a running Firefox instance or the ability to spawn one.

```python
""" This basic example demonstrates how to list all tabs.
"""

import json
from subprocess import Popen

from geckordp.actors.root import RootActor
from geckordp.firefox import Firefox
from geckordp.profile import FirefoxProfile, ProfileManager
from geckordp.rdp_client import RDPClient
from geckordp.settings import GECKORDP, log

# NOTE: enable debug logging by default
GECKORDP.DEBUG = 1
GECKORDP.DEBUG_REQUEST = 1
GECKORDP.DEBUG_RESPONSE = 1


def main(
    profile_name: str,
    host: str = "localhost",
    port: int = 6000,
    # NOTE: optionally clone any existing profile before mutate.
    clone_existing_profile: bool = True,
    restore_from_last_session: bool = True,
    always_spawn_browser: bool = True,
) -> None:

    # clone default profile to 'geckordp'
    pm = ProfileManager()
    profile: FirefoxProfile = pm.get_profile_by_name(profile_name)

    # make a new profile if none exists by given name
    if profile is None:
        profile: FirefoxProfile = pm.create(profile_name)

    # Clone from the target profile instead of mutating it?
    # In the case where the cloned profile already exists (by
    # having a `.geckordp` suffix in the name) load that
    # (previously cloned) profile for mutation B)
    elif clone_existing_profile:

        clone_name: str = f"{profile_name}.geckordp"
        profile: FirefoxProfile = pm.get_profile_by_name(clone_name)

        # only clone if no clone already exists
        if not profile:
            profile: FirefoxProfile = pm.clone(
                profile_name,
                clone_name,
            )

    # apply low-level setts to enable RDP ctl over TCP
    # (among many other things!)
    profile.set_required_configs()

    # load the last tab set state from any prior session?
    if restore_from_last_session:
        # https://kb.mozillazine.org/Browser.startup.page#3
        profile.set_config("browser.startup.page", 3)
        profile.set_config("browser.sessionstore.resume_from_crash", True)
        profile.set_config("browser.sessionstore.restore_on_demand", True)
        profile.set_config("browser.sessionstore.restore_tabs_lazily", True)
        profile.set_config("toolkit.startup.max_resumed_crashes", 1)

    # create client and connect to firefox
    # NOTE: by default this starts a few bg worker threads!
    client = RDPClient(
        timeout_sec=0.5,
        executor_workers=1,
    )
    resp: dict | None = client.connect(host, port)
    if resp is None:
        if always_spawn_browser:
            # NOTE: if no firefox process can be contacted at the (host,
            # port) socket address, start firefox with specified profile
            # and RDP addr.
            proc: Popen = Firefox.start(
                "https://example.com/",
                port,
                profile.name,
                # append_args=["-headless"],
            )
            log(f"Firefox started with pid={proc.pid}")
            resp: dict | None = client.connect(
                host,
                port,
                # timeout_sec=120,
            )
            if resp is None:
                raise RuntimeError(
                    f"Could not connect to firefox instance localhost@{port}!?"
                )
        else:
            raise RuntimeError(f"No browser listening on RDP socket @ {(host, port)}!?")

    log(f"Connected to browser @ {(host, port)} -> {resp}")

    # initialize root
    root = RootActor(client)

    # get a list of tabs
    tabs: list[dict] = root.list_tabs()
    json_tabs: str = json.dumps(tabs, indent=2)
    print(f"TABS ARE:\n" f"{json_tabs}")

    # NOTE: We block here due to bg threads that were spawned in the RDPClient?
    # TODO: probably be more explicit about the concurrency here
    # since it's a bit confusing what is actually going on ;)
    # uncomment for debug/introspection if needed
    # import pdbp; pdbp.set_trace()


if __name__ == "__main__":
    # Use a project-relevant profile name if user does NOT pass
    # one as the first CLI argument.
    profile_name: str = "geckordp"

    from sys import argv

    if len(argv) > 1:
        profile_name: str = str(argv[1])

    main(profile_name)
```
Tokens:
Raw