Chromium Extension APIs Available in Automation Contexts

The MV2-to-MV3 migration is, at its core, one architectural change with a long tail of consequences: a persistent background page with a full DOM became a service worker with none. No window, no document, no XMLHttpRequest, no localStorage. Everything else flows from that. fetch replaces XMLHttpRequest; chrome.storage replaces localStorage. These aren't optional modernizations you can defer. They're the only paths that exist.

The termination behavior is where things actually get painful. Service workers die after roughly 30 seconds of inactivity, and any state sitting in global variables evaporates with them, silently, without ceremony. Extensions that store state in globals will lose it and often won't know they lost it. The fix is to design around chrome.storage and alarm-triggered wake-ups from the start, not bolt them on later. If you're porting an MV2 extension to MV3, this is the part that actually costs you time. Not because it's conceptually difficult, but because it requires rethinking state management from scratch rather than swapping a few API calls.

One more constraint that comes up constantly in automation setups: remotely hosted code is banned outright in MV3. Every line of JavaScript must be bundled inside the extension package. Any automation approach that tries to inject or update logic dynamically from a remote source gets blocked at the policy level before it ever reaches runtime.

In automation contexts, service worker termination is considerably more dangerous than in ordinary extensions, because there's no user gesture reliably available to re-trigger the worker. That's not a footnote. It's the central problem.

The Service Worker Termination Problem in Playwright and Puppeteer Automation

Playwright's documentation acknowledges this directly: Chrome MV3 service workers are automatically suspended after roughly 30 seconds of inactivity and restarted on demand. But what the documentation says and what you actually experience are two different things.

Playwright keeps the same Worker object alive across a suspension. No new serviceworker event fires when the worker restarts. Your automation code gets no clean signal that the context was destroyed and rebuilt. evaluate() calls issued during the restart window stall until the new context is ready, producing something that looks like a hang rather than an error.

The downstream consequence for test suites is non-determinism: results that vary based on timing, not logic. Intermittent failures that reproduce inconsistently, that you can't reliably demonstrate to someone else, and that leave you questioning whether the bug is in your code or in the infrastructure. That's the failure mode you most want to avoid, because it erodes trust in the entire test suite.

Externalizing shared state to chrome.storage and using chrome.alarms to keep the worker alive when continuous presence is required solves this. It's not elegant but it works. Puppeteer has the same underlying termination behavior; the specific APIs for observing worker lifecycle differ slightly from Playwright's, but the architectural problem and the solution are identical.

APIs That Work Reliably in Automation: The Core Set

chrome.scripting

The MV3 replacement for tabs.executeScript, and foundational to any extension-based automation that needs to touch page content. It injects scripts into page contexts, reads results back, and provides the primary bridge between the service worker and the live page. One hard requirement that surfaces at runtime rather than at manifest validation: the target URL must be declared in host_permissions. Without it, calls fail with a "Cannot access contents of url" error. The check happens when the call is made, not when the extension loads. You'll find out at the worst possible moment.

chrome.storage

The sanctioned persistence layer in MV3, and the most consequential architectural decision you'll make in any extension-based automation project. It survives service worker termination. It's readable and writable from the service worker context across restarts. Any state your automation needs to carry between steps belongs here, not in a global variable. As of Chrome 132, stored data is also inspectable and editable directly in DevTools, which cuts the feedback loop significantly when you're debugging automation state.

chrome.runtime

Retrieves the service worker, exposes manifest details, handles lifecycle events. Reliable in automation. Used for message passing between extension components: background service worker, content scripts, popup. When components of your extension need to coordinate during an automation run, chrome.runtime.sendMessage and its associated listeners are the durable path.

chrome.tabs and the activeTab Permission

chrome.tabs provides programmatic access to the browser's tab surface: querying, creating, updating, removing. The activeTab permission grants temporary elevated access to the currently active tab, but it's gated behind a qualifying user gesture. In automation, that constraint comes up regularly. Some activeTab-dependent calls require a simulated interaction to unlock access; skip this step and you get permission errors that are easy to misdiagnose, because the permission looks granted in the manifest and the failure message doesn't always tell you why.

chrome.webNavigation

Event notifications about navigation state. Useful for automation that needs to synchronize on page transitions without polling. Read-only; it doesn't intercept or modify traffic. For sequencing automation steps around navigation events, it's more reliable than time-based delays and considerably less fragile under variable network conditions.

chrome.userScripts (Chrome 135 and Later)

The userScripts.execute() method allows one-time script injection at an arbitrary moment without requiring permanent registration of a user script. Useful in automation scenarios that need ad-hoc injection outside the structured flow of chrome.scripting. Version gating applies: Chrome 135 or later only. Automation targeting older browser versions needs a fallback.

chrome.debugger: The API That Opens CDP to an Extension in the User's Live Browser

chrome.debugger is the most powerful extension API available to automation engineers, and it's the one that carries the most weight to ship responsibly. Attaching to a tab via chrome.debugger.attach({ tabId }, "1.3") and sending commands via sendCommand opens the full CDP surface from within an ordinary extension. What makes this worth the complexity: the extension operates with the user's real cookies, logins, and session state. External CDP connections through Puppeteer or Playwright, when controlling a separate browser instance, don't automatically carry that session context. For automation that needs to operate as a logged-in user, this structural difference is often the deciding factor.

The CDP domains accessible through chrome.debugger cover most serious automation requirements. The Accessibility domain provides the full accessibility tree, which is the practical alternative to the restricted chrome.automation API. The Page domain handles screenshots, PDF export, and navigation control. The DOM domain allows querying and modifying the live DOM, including shadow DOM and iframes. The Input domain sends mouse, keyboard, and touch events with precise coordinates. The Network domain enables intercepting, modifying, blocking, and mocking responses.

Three constraints require planning before you build on this. First, attach fails if DevTools is already open on the same tab. This happens constantly in local development, where someone has DevTools open while running an automated test, and the error message isn't always clear about why it failed. Second, a yellow banner reading "YourExtension started debugging this browser" appears and cannot be suppressed. It's a user transparency mechanism; it's not going away. Third, granting the debugger permission triggers prominent Chrome Web Store review warnings about access to the page debugger backend and all data on all websites. That affects user trust and the store review process in ways you need to weigh before you ship, not after.

An extension with debugger permission reaches most CDP domains and operates inside the user's real session. A full browser fork, the approach Playwright and Puppeteer typically take, reaches all CDP domains but starts from a fresh session. Which one you need depends entirely on whether real session access or complete CDP coverage is the actual constraint.

chrome.automation: What It Offers, and Why It Is Mostly Off-Limits Outside Chrome OS

chrome.automation exposes the accessibility tree for a tab or the desktop: names, roles, states, events, and actions on individual nodes. chrome.automation.getTree(tabId, callback) returns a tree with a placeholder root; the loadComplete event signals when it's fully populated. addTreeChangeObserver() listens for changes using filters, though listening to all changes carries a documented performance cost. getDesktop() provides the full desktop tree, currently supported on Chrome OS only.

The access restriction that makes this impractical for most automation is this: chrome.automation requires Chrome to be launched with --allowlisted-extension-id=your-extension-id. This flag doesn't appear in the standard developer documentation. You find it by reading the internal source definition. For any automation scenario where you don't control the Chrome launch flags, this API is simply unavailable.

The practical alternative is chrome.debugger with the Accessibility CDP domain. Accessibility.getFullAXTree provides equivalent tree access without the flag requirement. If you're building accessibility-dependent automation, route through chrome.debugger.

Network Interception in Extensions: declarativeNetRequest Versus the Deprecated Blocking webRequest

MV3 deprecated the blocking variant of chrome.webRequest, which had required proxying all network traffic through the extension process. The replacement is chrome.declarativeNetRequest. Extensions specify declarative rules; the browser applies them without the extension ever seeing request content. That's a deliberate privacy design decision, and it defines the hard boundary of what this API can do.

For automation, the implication is concrete. Blocking and redirecting requests is still possible through declarative rules. Inspecting request bodies or computing block decisions dynamically inside extension code is not. That class of dynamic network introspection requires the CDP Network domain via chrome.debugger. These two APIs are not substitutes. They solve different problems, and building architecture that conflates them produces systems that can't deliver what they promise.

declarativeNetRequest.testMatchOutcome can be called from the background service worker of an unpacked extension, or driven via Puppeteer in automated tests, to verify that declarative rules behave as intended without a full manual browser session. It's a targeted testing utility, not an interception mechanism.

chrome.webNavigation remains fully available for observing navigation events without modifying them. The webRequest deprecation doesn't touch it.

APIs That Are Conditionally Available or Scoped to Specific Extension Contexts

chrome.devtools.*

The chrome.devtools namespace, including chrome.devtools.inspectedWindow, chrome.devtools.network, chrome.devtools.performance, and chrome.devtools.recorder, is only available inside a DevTools panel extension. Not from the service worker. Not from content scripts. In automation contexts, these APIs are unreachable unless the automation itself loads a DevTools panel, which is a narrow configuration that requires explicit justification to pursue.

chrome.accessibilityFeatures

Manages Chrome's built-in accessibility settings. Requires accessibilityFeatures.read to get states and accessibilityFeatures.modify to change them; the two permissions are declared and granted independently. Available in the service worker context with appropriate permissions. The relevant automation use case is enabling or verifying accessibility settings before running accessibility-dependent tests, ensuring that browser configuration actually matches what the test suite assumes.

activeTab and User Gesture Gating

Several APIs unlocked through activeTab require a qualifying user gesture: a browser action click, a context menu interaction, or a keyboard shortcut. In automation, some of these calls are structurally unreachable without simulating the triggering interaction first. This is one of the more confounding failure modes, because the permission appears granted in the manifest yet the call still fails. The error message often doesn't point directly at the gesture requirement, which is why it consumes more debugging time than it deserves.

The General Pattern

The permissions and host_permissions arrays in the manifest are the first filter; the execution context, whether service worker, content script, or DevTools panel, is the second. When an API call fails in automation and the permissions look correct, the execution context is where to look next.

How CDP-Based Automation Tools Relate to the Extension API Surface

CDP is organized into domains: DOM, Debugger, Network, Input, Accessibility, Page, and others. Each domain defines commands and events, serialized as JSON over WebSocket. Puppeteer, Playwright, Selenium 4 via the HasDevTools interface, and agentic tools like playwright-mcp, browser-use, and chrome-devtools-mcp are all built on top of this architecture.

The session context distinction is the thing extension developers need to keep in focus. A direct CDP connection, the approach Puppeteer and Playwright use when controlling a fresh browser instance, provides broad CDP access but no pre-existing session state. An extension with the debugger permission gets most CDP domains and operates inside the user's real session, cookies and logins intact. The choice between these two approaches comes down to one question: is real-session access or complete CDP coverage the actual constraint for what you're building?

chrome-devtools-mcp, built by the Chrome team on CDP and Puppeteer, gives AI coding agents access to Chrome DevTools for automation, debugging, and performance analysis. Understanding where the extension API surface ends and where CDP tooling begins is now a practical skill, not an academic distinction.

One stability issue that gets underestimated: CDP makes no forward or backward compatibility guarantees. Browser version and CDP version must be aligned carefully; automation built on specific CDP domain commands can and does break on Chrome updates. Teams operating at scale should treat CDP version alignment as ongoing maintenance, not a one-time setup task.

In the RPA context, UiPath's ChromiumAPI routes Chromium automation through CDP, following the same domain-based model. The underlying constraints around session state, API stability, and domain availability apply regardless of which tool is driving the connection.