{"id":9370,"library":"trio-chrome-devtools-protocol","title":"Trio Chrome DevTools Protocol","description":"Trio Chrome DevTools Protocol (Trio CDP) is a Python library that enables remote control of any web browser implementing the Chrome DevTools Protocol. It leverages Trio for asynchronous I/O and `python-chrome-devtools-protocol` for type wrappers. The library handles WebSocket negotiation and session management, allowing transparent multiplexing of commands, responses, and events over a single connection. The current version is 0.6.0, released in April 2020, with ongoing maintenance evident through recent GitHub activity.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/hyperiongray/python-chrome-devtools-protocol","tags":["trio","chrome","devtools","cdp","browser automation","async"],"install":[{"cmd":"pip install trio-chrome-devtools-protocol","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Provides Python type wrappers for CDP commands and events, foundational for this library's functionality.","package":"python-chrome-devtools-protocol","optional":false},{"reason":"The asynchronous I/O framework used by this library for network operations.","package":"trio","optional":false},{"reason":"Required Python version.","package":"Python","version":">=3.7,<4.0","optional":false}],"imports":[{"note":"The primary entry point for establishing a connection to a Chrome DevTools Protocol endpoint.","symbol":"open_cdp","correct":"from trio_cdp import open_cdp"},{"note":"Used for more control over discovering the WebSocket URL from Chrome's HTTP endpoint.","symbol":"find_chrome_debugger_url","correct":"from trio_cdp import find_chrome_debugger_url"},{"note":"Provides commands and events related to page actions, e.g., navigation, loading events.","symbol":"page","correct":"from trio_cdp import page"},{"note":"Provides commands for interacting with the Document Object Model.","symbol":"dom","correct":"from trio_cdp import dom"}],"quickstart":{"code":"import trio\nfrom trio_cdp import open_cdp, page, dom\n\nasync def main():\n    # Ensure Chrome is running with --remote-debugging-port=9222\n    cdp_url = 'http://localhost:9222'\n    target_url = 'https://www.example.com'\n\n    try:\n        async with open_cdp(cdp_url) as conn:\n            # Find the first available target (usually a browser tab).\n            # Note: target domain imports are typically implicitly available on 'conn.target'\n            targets = await conn.target.get_targets()\n            if not targets:\n                print('No targets found. Is Chrome running and a page open?')\n                return\n            target_id = targets[0].id\n\n            # Create a new session with the chosen target.\n            async with conn.open_session(target_id) as session:\n                # Enable page-level events to wait for navigation completion.\n                async with session.page_enable():\n                    async with session.wait_for(page.LoadEventFired):\n                        await session.execute(page.navigate(target_url))\n\n                print(f\"Navigated to: {target_url}\")\n\n                # Extract the page title.\n                root_node = await session.execute(dom.get_document())\n                title_node_id = await session.execute(dom.query_selector(root_node.node_id, 'title'))\n                if title_node_id:\n                    html = await session.execute(dom.get_outer_html(title_node_id))\n                    print(f\"Page Title HTML: {html}\")\n                else:\n                    print(\"Could not find title element.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Make sure Chrome is running with '--remote-debugging-port=9222'.\")\n\nif __name__ == '__main__':\n    trio.run(main)","lang":"python","description":"This quickstart connects to a headless Chrome instance (assumed to be running on `http://localhost:9222`), navigates to a specified URL, waits for the page to load, and then extracts the HTML content of the page's title element. It demonstrates basic connection, session management, navigation, and DOM interaction using Trio's async capabilities. Before running, ensure Chrome is launched with `--remote-debugging-port=9222`."},"warnings":[{"fix":"Pin your browser version (e.g., Chrome, Chromium) to a specific, known-compatible version with the library. Regularly check for updates to `trio-chrome-devtools-protocol` and `python-chrome-devtools-protocol` and consult their changelogs when upgrading browser or library versions.","message":"The Chrome DevTools Protocol itself is subject to frequent changes, especially the 'tip-of-tree' version. As `trio-chrome-devtools-protocol` relies on `python-chrome-devtools-protocol` (which generates its types from CDP), changes in the underlying protocol can lead to API mismatches or breakage if the library is not updated to match the browser's CDP version.","severity":"breaking","affected_versions":"All versions"},{"fix":"Always start your Chrome/Chromium instance with `--remote-debugging-port=<port_number>`. For automation, consider using a dedicated headless instance.","message":"Chrome/Chromium must be launched with the `--remote-debugging-port` flag (e.g., `--remote-debugging-port=9222`) for `trio-chrome-devtools-protocol` to connect. Without this, the browser will not expose the DevTools Protocol endpoint, leading to connection failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Call the appropriate `_enable()` method for the domain from which you expect events (e.g., `await session.page_enable()` for `page` events) at the beginning of your session or before the relevant actions.","message":"To receive events (e.g., `page.LoadEventFired`, `network.RequestWillBeSent`), you must explicitly enable the corresponding CDP domain using methods like `session.page_enable()` or `session.network_enable()` before the event occurs. Events are not enabled by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your main application entry point uses `trio.run()` to start the event loop, and all `await` calls are within `async def` functions managed by Trio.","message":"As `trio-chrome-devtools-protocol` is built on Trio, all asynchronous operations must be executed within a Trio event loop. Attempting to call `async` functions outside `trio.run()` or a `trio.lowlevel.checkpoint()` context will result in runtime errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Identify and refactor synchronous blocking calls. If they are unavoidable, consider running them in a separate thread using `trio.to_thread.run_sync()` or moving them to a separate process.","cause":"This usually indicates that a long-running, CPU-bound synchronous operation is blocking the Trio event loop, preventing it from yielding control.","error":"trio.TooSlowError: checkpoint timed out"},{"fix":"Verify that Chrome is running and launched with the `--remote-debugging-port=9222` (or your chosen port) flag. Also, ensure no firewall or sandbox restrictions are preventing access to the port or the temporary files Chrome creates for debugging.","cause":"The library failed to locate the file indicating the active DevTools port for a running Chrome instance. This often happens if Chrome is not running with remote debugging enabled or if the `--autoConnect` feature (if used via a wrapper) cannot find the debug port file.","error":"Error: Could not find DevToolsActivePort"},{"error":"ProtocolError: <Domain.Method> timed out"},{"fix":"Check if the Chrome instance is still running and the target tab is open. Ensure stable network connectivity. Review browser logs for crashes or relevant errors. If running in a containerized environment, ensure proper port forwarding and network access. Restarting Chrome with remote debugging might resolve transient issues.","cause":"A network-level issue where the WebSocket connection to Chrome was dropped. This can be due to Chrome crashing, closing the tab/browser, an unstable network, or stricter sandbox/firewall settings.","error":"The socket connection was closed unexpectedly"},{"fix":"Verify that the browser version you are using is compatible with the `trio-chrome-devtools-protocol` and `python-chrome-devtools-protocol` versions you have installed. Consult the CDP documentation or `python-chrome-devtools-protocol` source to confirm method existence and spelling for your browser's protocol version.","cause":"The command you are trying to execute is not supported by the connected browser's Chrome DevTools Protocol version, or the method name is misspelled.","error":"ProtocolError: Method '<Domain.Method>' not found"}]}