Locators and actions

A locator describes how to find one or more elements inside an attached frame. Locators are chainable and lazy: nothing touches the page until you call an action. If you have used Playwright, you already know this model.

Locators run wherever attachFrame() attached the frame: in the FKN extension’s content script or in the cloud render proxy. Consent applies only to the extension backend. A cloud frame uses either an isolated or persistent cloud cookie jar, depending on syncCookies, and does not show extension prompts.

Locators and actions by execution backend

All APIs below are called from browser code. The columns show which backend performs the work.

API / feature	Extension	Cloud	Desktop
`Selectors (locator, getByRole, ...)`	Supported	Supported	Not available
`Read actions (textContent, ...)`	Supported	Supported	Not available
`Write actions (click, fill, hover)`	Supported	Supported	Not available
`videoElement()`	Supported	Not available	Not available

await 
const frame: Frame
frame
  .
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
        };
    };
}, {
    ...;
}>>
locator('.video-card')
  .
first: () => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
        };
    };
}, {
    ...;
}>>
first()
  .
getByText: (text: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
        };
    };
}, {
    ...;
}>>
getByText('Play')
  .
click: (options?: PositionOptions | undefined) => Promise<void>
click()

Selectors

Each selector returns a new locator, scoped to the previous step’s matches.

The frame root starts narrow: it offers locator(css), frameLocator(css) and owner(). The rest of the set below becomes available on element locators, from the first locator() onward; owner() stays a frame-locator selector.

Selector	Finds
`locator(css)`	elements matching a CSS selector
`getByRole(role)`	elements by ARIA role
`getByText(text)`	elements containing the given text
`getByTestId(id)`	elements by `data-testid`
`first()`	the first match of the current set
`nth(index)`	the n-th match of the current set
`frameLocator(css)`	descends into a child iframe matched by the selector
`owner()`	steps back up to the locator’s owning frame (frame locators only)

Actions

Actions are terminal: they resolve the chain against the live page and perform the operation. On the extension backend, each action is checked against a permission keyed to its capability and target. Severity-0 actions continue automatically; other actions prompt when no existing grant covers them. Cloud actions do not use extension consent.

Action	Does	Returns
`click()`	clicks the element	`Promise<void>`
`fill(value)`	sets an input’s value	`Promise<void>`
`hover()`	moves a faithful pointer over the element	`Promise<void>`
`textContent()`	reads the element’s text	`Promise<string \| null>`
`getAttribute(name)`	reads an attribute	`Promise<string \| null>`
`isVisible()`	whether the element is rendered and visible	`Promise<boolean>`
`exists()`	whether the element is present	`Promise<boolean>`
`count()`	how many elements match	`Promise<number>`
`videoElement()`	a remote handle to a `<video>` element (play, pause, seek, events); extension backend only	`Promise<RemoteVideoElement>`
`addStyleTag(options)`	injects safety-filtered CSS into the frame	`Promise<void>`

All actions accept an options object with:

timeout: how long to retry resolving the locator before failing. Waiting for the user’s consent never counts against the timeout.
reason: an app-supplied explanation shown on the consent prompt next to the request.

const 
const title: string
title = await 
const frame: Frame
frame
  .
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
        };
    };
}, {
    ...;
}>>
locator('h1')
  .
textContent: (_options?: LocatorOptions | undefined) => Promise<string>
textContent({ 
timeout?: number | undefined
timeout: 5_000, 
reason?: string | undefined
reason: 'Show the video title in your library' })

Reading is separate from acting

Reading page content (textContent, getAttribute) and acting on it (click, fill, hover) use distinct extension capabilities. Visibility, existence, and count checks are severity 0 and do not prompt. A user can grant content reading without granting page actions, and vice versa.

Try it

Drive an embedded page through the extension below: single actions (one consent each), an area grant that covers a region, and the on-device activity log. Needs the FKN extension installed; the demo picks it up automatically. For a demo that also runs without the extension, see attachFrame().

Locators, consent and the audit logOpen in new tab