# Automation

> Use Window-only DOM helpers, inspect closed shadow roots, and dispatch trusted events with the automation capability.

Source: https://console.getchrovia.com/en/docs/sdk-automation

**Entitlement:** `automation`. **API:** `window.chrovia.automation`. No EP section is required. A Window context also needs [unrestrictedApi](https://console.getchrovia.com/en/docs/sdk-unrestricted-api); automation is not exposed in a Service Worker.

## Query and interact

Run this on a test page you control after its DOM is ready. It creates a closed shadow root and demonstrates explicit access through the SDK:

```js
const automation = window.chrovia?.automation;
if (!automation) {
  throw new Error('automation and unrestrictedApi are required');
}
const host = document.createElement('div');
document.body.append(host);
const shadow = host.attachShadow({ mode: 'closed' });
const button = document.createElement('button');
button.textContent = 'SDK test';
button.addEventListener('click', event => console.log(event.isTrusted));
shadow.append(button);
const root = automation.getShadowRoot(host);
const target = automation.querySelector(root, 'button');
if (target) {
  automation.dispatchTrustedEvent(target, new MouseEvent('click', { bubbles: true }));
}
```

The listener should receive an event with `isTrusted === true`. Without the helper, `host.shadowRoot` remains `null` because the root was created closed.

## Methods

| Method | Result |
| --- | --- |
| `getShadowRoot(element)` | ShadowRoot or `null`, including closed roots |
| `querySelector(selectors)` | First match in the current document or `null` |
| `querySelector(root, selectors)` | First match under an Element or ShadowRoot |
| `querySelectorAll(selectors)` | NodeList for the current document |
| `querySelectorAll(root, selectors)` | NodeList under the supplied root |
| `getBoundingClientRect(element)` | DOMRect for the element |
| `dispatchTrustedEvent(target, event)` | Boolean dispatch result |

These calls are synchronous. Invalid CSS selectors can throw. Queries do not automatically pierce every shadow root or iframe; obtain each root and query within it. A dispatch result is not confirmation that a form submitted or a network request succeeded.

## Limits and verification

Use ordinary DOM and browser automation tools for navigation and waiting. This domain has no `click()`, `type()`, or `launch()` method, and does not create a Node.js browser controller. Focus, input values, selection, and application event sequencing remain your responsibility.

A trusted event is not a blanket promise of native user activation or OS input. Test the actual page behavior. If the API is missing, check both entitlements and ensure the code runs in Window, not an extension background worker. See [API contexts](https://console.getchrovia.com/en/docs/sdk-javascript-api).