Mutation - Extractbase Docs

Defines all available mutations to interact with and manipulate web pages. Mutations typically perform actions like clicking elements, typing text, navigating, or changing browser settings. Most mutations return a Boolean indicating success.

Definition

object Mutation {
  page(
    url: URL
    content: String
    options: PageOptions
  ): Page!
  act(
    action: String!
    variables: JSONObject
    options: ActOptions
  ): Boolean!
  addCookies(
    options: [CookieOptions]!
  ): Boolean!
  addInitScript(
    options: AddInitScriptOptions!
  ): Boolean!
  addScriptTag(
    options: AddScriptTagOptions!
  ): Boolean!
  addStyleTag(
    options: AddStyleTagOptions!
  ): Boolean!
  blur(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: TimeoutOptions
  ): Boolean!
  check(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: CheckOptions
  ): Boolean!
  clear(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: ClearOptions
  ): Boolean!
  clearCookies(
    options: ClearCookiesOptions!
  ): Boolean!
  clearPermissions: Boolean!
  click(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: ClickOptions
  ): Boolean!
  dragAndDrop(
    source: ElementOptions!
    target: ElementOptions!
    options: DragAndDropOptions
  ): Boolean!
  emulateMedia(
    options: EmulateMediaOptions!
  ): Boolean!
  evaluate(
    functionOrPredicate: String!
    arg: JSON
  ): JSON!
  events: Events
  extract(
    instruction: String!
    schema: JSONObject!
    options: ExtractOptions
  ): JSON!
  fill(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    value: String!
    options: FillOptions
  ): Boolean!
  focus(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: TimeoutOptions
  ): Boolean!
  goBack(
    options: WaitForOptions
  ): Boolean!
  goForward(
    options: WaitForOptions
  ): Boolean!
  grantPermissions(
    permissions: [Permission]!
    options: GrantPermissionsOptions
  ): Boolean!
  highlight(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
  ): Boolean!
  hover(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: HoverOptions
  ): Boolean!
  pressKey(
    key: String!
    options: PressKeyOptions
  ): Boolean!
  type(
    text: String!
    options: TypeOptions
  ): Boolean!
  observe(
    instruction: String!
    options: ObserveOptions
  ): [Observe]!
  reload(
    options: WaitForOptions
  ): Boolean!
  scrollIntoView(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: TimeoutOptions
  ): Boolean!
  selectOption(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    values: [SelectValueOptions]!
    options: SelectOptionOptions
  ): Boolean!
  selectText(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: SelectTextOptions
  ): Boolean!
  setExtraHTTPHeaders(
    headers: Headers!
  ): Boolean!
  setGeolocation(
    options: GeolocationOptions!
  ): Boolean!
  setInputFiles(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    files: [InputFileOptions]!
  ): Boolean!
  setOffline(
    enabled: Boolean!
  ): Boolean!
  setViewport(
    viewport: ViewportOptions!
  ): Boolean!
  tap(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: TapOptions
  ): Boolean!
  touch(
    target: PointOptions!
  ): Boolean!
  uncheck(
    selector: String
    text: String
    role: ARIARole
    label: String
    placeholder: String
    altText: String
    title: String
    testId: String
    filter: ElementFilterOptions
    options: CheckOptions
  ): Boolean!
  waitForEvent(
    event: PageEvent
    options: TimeoutOptions
  ): Boolean!
  waitForFunction(
    functionOrPredicate: String!
    arg: JSON
    options: WaitForFunctionOptions
  ): Boolean!
  waitForLoadState(
    state: LoadState!
    options: TimeoutOptions
  ): Boolean!
  waitForRequest(
    urlOrPredicate: String!
    options: TimeoutOptions
  ): Boolean!
  waitForResponse(
    urlOrPredicate: String!
    options: TimeoutOptions
  ): Boolean!
  waitForURL(
    urlOrPredicate: String!
    options: WaitForOptions
  ): Boolean!
}

Fields

`page`

Page! Accesses a page by navigating to a URL, loading HTML content, or returning the current page. This is the primary entry point for interacting with web pages, so you may want to create a page as the first step in your query or mutation.

If url is provided, navigates to that URL.
If content is provided, creates a new page with that HTML content.
If neither url nor content is provided, returns the currently active page, if any.

Page options can be specified to configure aspects like viewport, user agent, headers, etc.

Examples

query {
  page(
    url: "https://example.com",
    options: { userAgent: "MyCustomBrowser/1.0" }
  ) {
    content
  }
}

Arguments

url: URL - The URL to navigate the page to. If specified, the browser will attempt to load this URL. Example: "https://example.com"
content: String - HTML content to set for the page. If specified, a new page is created with this content. This is useful for testing static HTML snippets or pages constructed on-the-fly. Example: "<html><body><h1>Test Page</h1></body></html>"
options: PageOptions - Options to configure the page’s behavior and environment. These include settings for viewport, user agent, geolocation, HTTP headers, JavaScript enablement, and more. See PageOptions for detailed configuration.

`act`

Boolean! Allows execution of a predefined sequence of actions on the current page. This is a powerful feature for orchestrating complex interactions. Example: act(action: "login", variables: { username: "user", password: "password" })

Arguments

action: String! - The name of the action sequence to execute.
variables: JSONObject - A JSON object containing variables to be used within the action sequence.
options: ActOptions - Options to control the execution of the action sequence.

`addCookies`

Boolean! Adds an array of cookies to the current browser context. All cookies must specify a name, value, domain, and path. Returns true if cookies were successfully added.

Arguments

options: [CookieOptions]! - An array of cookie objects to add. See CookieOptions for details.

`addInitScript`

Boolean! Adds a script that will be executed when new documents are created within the page. This is useful for modifying the JavaScript environment of the page. Example: addInitScript(options: { content: "window.customVar = 123;" }) Returns true if the script was successfully scheduled.

Arguments

options: AddInitScriptOptions! - Options specifying the script content.

`addScriptTag`

Boolean! Adds a <script> tag into the page with the desired content or URL. Can be used to inject custom JavaScript into the current document. Example: addScriptTag(options: { content: "console.log('Injected');" }) or addScriptTag(options: { url: "https://example.com/script.js" }) Returns true if the script tag was successfully added.

Arguments

options: AddScriptTagOptions! - Options for the script tag, such as content, URL, or ID.

`addStyleTag`

Boolean! Adds a <style> tag into the page with the desired content or URL. Can be used to inject custom CSS to alter the page’s appearance. Example: addStyleTag(options: { content: "body { background-color: blue; }" }) Returns true if the style tag was successfully added.

Arguments

options: AddStyleTagOptions! - Options for the style tag, such as content or URL.

`blur`

Boolean! Removes focus from the specified element. The element is identified using one of the provided selector strategies. Example: blur(selector: "#myInput") Returns true if the blur action was successful.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: TimeoutOptions - Options to control the timeout for the operation.

`check`

Boolean! Checks a checkbox or radio button. The element is identified using one of the provided selector strategies. Example: check(selector: "input[type='checkbox']") Returns true if the element was successfully checked.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: CheckOptions - Options for the check action, like forcing the action or setting a timeout.

`clear`

Boolean! Clears the value of an input field or textarea. The element is identified using one of the provided selector strategies. Example: clear(selector: "#searchField") Returns true if the element’s content was successfully cleared.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: ClearOptions - Options for the clear action, such as forcing the action or setting a timeout.

`clearCookies`

Boolean! Clears all browser cookies for the current context, or specific cookies if options are provided. Returns true if cookies were successfully cleared.

Arguments

options: ClearCookiesOptions! - Options to specify which cookies to clear (by domain, name, or path). If not provided, all cookies are cleared.

`clearPermissions`

Boolean! Clears all previously granted permissions for the current browser context. Returns true if permissions were successfully cleared.

`click`

Boolean! Clicks an element on the page. The element is identified using one of the provided selector strategies. Example: click(selector: "button.submit") Returns true if the click action was successful.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: ClickOptions - Options for the click action, such as button type, click count, delay, or modifiers.

`dragAndDrop`

Boolean! Performs a drag-and-drop operation from a source element to a target element. Both source and target elements are identified using selector strategies. Example: dragAndDrop(source: { selector: "#item-to-drag" }, target: { selector: "#drop-zone" }) Returns true if the drag-and-drop was successful.

Arguments

source: ElementOptions! - Selector options for the source element to drag.
target: ElementOptions! - Selector options for the target element to drop onto.
options: DragAndDropOptions - Options for the drag-and-drop operation, like force or specific positions.

`emulateMedia`

Boolean! Emulates various media features like color scheme, contrast, or print media type. Useful for testing how a page adapts to different user preferences or output formats. Example: emulateMedia(options: { media: PRINT }) Returns true if media emulation was successfully applied.

Arguments

options: EmulateMediaOptions! - Options specifying the media features to emulate.

`evaluate`

JSON! Executes a JavaScript function or predicate within the page’s context and returns the result. The function receives ‘arg’ as its first argument. Example: evaluate(functionOrPredicate: "() => document.title") Example with argument: evaluate(functionOrPredicate: "selector => document.querySelector(selector).innerText", arg: "#myElement") Returns the JSON representation of the function’s return value.

Arguments

functionOrPredicate: String! - A string containing the JavaScript function or predicate to execute. Example: "() => ({ width: window.innerWidth, height: window.innerHeight })" Example: "element => element.tagName" (if an element is the context)
arg: JSON - An optional JSON serializable argument to pass to the function.

`events`

Events Snapshot of events that occurred during the operation, such as console messages, network requests, and field executions. To get real-time updates, use subscriptions instead.

`extract`

JSON! Extracts structured data from the page based on a natural language instruction and a JSON schema. This uses AI to understand the instruction and locate the relevant information. Example:

extract(instruction: "Extract the product name and price", schema: { type: "object", properties: { name: { type: "string" }, price: { type: "number" } } })

Returns the extracted data as a JSON object.

Arguments

instruction: String! - A natural language instruction describing what data to extract. Example: "Get the user's name and email from the profile page."
schema: JSONObject! - A JSON schema defining the structure of the data to be extracted. Example: { "type": "object", "properties": { "productName": { "type": "string" }, "price": { "type": "number" } } }
options: ExtractOptions - Options for the extraction process, like specifying a root selector or timeout.

`fill`

Boolean! Fills an input field or textarea with the specified value. The element is identified using one of the provided selector strategies. Example: fill(selector: "#email", value: "test@example.com") Returns true if the element was successfully filled.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
value: String! - The value to fill into the input field.
options: FillOptions - Options for the fill action, such as forcing the action or setting a timeout.

`focus`

Boolean! Focuses the specified element on the page. The element is identified using one of the provided selector strategies. Example: focus(selector: "input[type='text']") Returns true if the element was successfully focused.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: TimeoutOptions - Options to control the timeout for the operation.

`goBack`

Boolean! Navigates the browser to the previous page in the session history. Example: goBack(options: { waitUntil: LOAD }) Returns true if the navigation was successful.

Arguments

options: WaitForOptions - Options for waiting for the navigation to complete, such as timeout or lifecycle event.

`goForward`

Boolean! Navigates the browser to the next page in the session history. Example: goForward(options: { timeout: 5000 }) Returns true if the navigation was successful.

Arguments

options: WaitForOptions - Options for waiting for the navigation to complete, such as timeout or lifecycle event.

`grantPermissions`

Boolean! Grants specified browser permissions to the current origin or a specific origin. Example: grantPermissions(permissions: [CAMERA, MICROPHONE]) Returns true if permissions were successfully granted.

Arguments

permissions: [Permission]! - An array of permissions to grant. See the Permission enum for available values.
options: GrantPermissionsOptions - Options for granting permissions, such as specifying the origin.

`highlight`

Boolean! Highlights the specified element on the page, typically by drawing a box around it. Useful for debugging or visual confirmation of element selection. Example: highlight(selector: "div.important-notice") Returns true if the element was successfully highlighted.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.

`hover`

Boolean! Hovers the mouse cursor over the specified element. The element is identified using one of the provided selector strategies. Example: hover(selector: "ul.menu > li:first-child") Returns true if the hover action was successful.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: HoverOptions - Options for the hover action, such as modifiers, position, or timeout.

`pressKey`

Boolean! Simulates pressing a single key on the keyboard. Accepts key names from KeyboardEvent.key like “Enter”, “Backspace”, “ArrowLeft”, or single characters like “a”, “5”. Example: pressKey(key: "Enter") Returns true if the key press was successful.

Arguments

key: String! - The key to press. For a list of possible keys, refer to MDN documentation on KeyboardEvent.key. Examples: "a", "Enter", "F1", "Control", "Shift+A" (modifiers are handled by ‘options’ or within the key string for some systems). For combinations like Ctrl+C, usually use individual presses or type for text.
options: PressKeyOptions - Options for the key press, such as delay.

`type`

Boolean! Simulates typing text into the currently focused element or the page. This is like multiple key presses for each character in the text. Example: type(text: "Hello, world!") Returns true if the text was successfully typed.

Arguments

text: String! - The text to type.
options: TypeOptions - Options for typing, such as inter-character delay.

`observe`

[Observe]! Observes the page for changes based on a natural language instruction and returns a list of observed interactions. This is an AI-driven feature that can identify and describe user interface elements and their behaviors. Example: observe(instruction: "Identify all interactive elements in the header.") Returns an array of Observe objects, each describing an observed element or interaction.

Arguments

instruction: String! - A natural language instruction describing what to observe on the page. Example: "Find all buttons and links in the navigation bar."
options: ObserveOptions - Options for the observation process, like DOM settle timeout.

`reload`

Boolean! Reloads the current page. Example: reload(options: { waitUntil: NETWORK_IDLE }) Returns true if the page reload was successful.

Arguments

options: WaitForOptions - Options for waiting for the reload to complete, such as timeout or lifecycle event.

`scrollIntoView`

Boolean! Scrolls the specified element into the viewport if it’s not already visible. The element is identified using one of the provided selector strategies. Example: scrollIntoView(selector: "footer") Returns true if the scroll action was successful.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: TimeoutOptions - Options to control the timeout for the operation.

`selectOption`

Boolean! Selects one or more options in a <select> element. The element is identified using one of the provided selector strategies. Options can be selected by value, label, or index. Example: selectOption(selector: "#country", values: [{ value: "US" }]) Returns true if the options were successfully selected.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
values: [SelectValueOptions]! - An array of option values to select. Options can be specified by value, label, or index.
options: SelectOptionOptions - Options for the select action, such as forcing the action or setting a timeout.

`selectText`

Boolean! Selects text within an input field, textarea, or contenteditable element. The element is identified using one of the provided selector strategies. If no range is specified, all text is selected. Example: selectText(selector: "#myInput") Returns true if the text was successfully selected.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: SelectTextOptions - Options for the text selection, such as forcing the action or setting a timeout. Note: Specific range selection is not exposed here; it typically selects all text in the matched element.

`setExtraHTTPHeaders`

Boolean! Sets additional HTTP headers that will be sent with all subsequent requests from the page. Pass an empty object to clear previously set extra headers. Example: setExtraHTTPHeaders(headers: { "X-Custom-Header": "MyValue" }) Returns true if the headers were successfully set.

Arguments

headers: Headers! - A JSON object representing the headers to set. Keys are header names, values are header values.

`setGeolocation`

Boolean! Sets the geolocation of the browser context. Example: setGeolocation(options: { latitude: 37.7749, longitude: -122.4194, accuracy: 100 }) Returns true if the geolocation was successfully set.

Arguments

options: GeolocationOptions! - Options specifying the latitude, longitude, and optionally accuracy of the geolocation.

`setInputFiles`

Boolean! Sets files for a file input element (<input type="file">). The element is identified using one of the provided selector strategies. Can be used to simulate file uploads. Example:

setInputFiles(selector: "input[type='file']", files: [{ name: "file.txt", mimeType: "text/plain", data: "SGVsbG8gd29ybGQ=" }])

The data field should be Base64 encoded content of the file. Returns true if the files were successfully set.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
files: [InputFileOptions]! - An array of file objects to set for the input. Each file needs a name, mimeType, and base64 encoded data.

`setOffline`

Boolean! Sets the browser context to offline or online mode. Example: setOffline(enabled: true) Returns true if the offline status was successfully set.

Arguments

enabled: Boolean! - Whether to enable (true) or disable (false) offline mode.

`setViewport`

Boolean! Sets the viewport size for the current page. Example: setViewport(viewport: { width: 1280, height: 720 }) Returns true if the viewport was successfully set.

Arguments

viewport: ViewportOptions! - The viewport dimensions (width and height) to set.

`tap`

Boolean! Performs a tap (touch click) on an element. Primarily for touch-enabled devices or emulation. The element is identified using one of the provided selector strategies. Example: tap(selector: "button.mobile-menu") Returns true if the tap action was successful.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: TapOptions - Options for the tap action, such as modifiers, position, or timeout.

`touch`

Boolean! Performs a touch action at a specific point on the screen. This is a low-level touch event. For interacting with elements, prefer tap. Example: touch(target: { x: 100, y: 200 }) Returns true if the touch action was successful.

Arguments

target: PointOptions! - The target coordinates (x, y) for the touch action.

`uncheck`

Boolean! Unchecks a checkbox or radio button. The element is identified using one of the provided selector strategies. Example: uncheck(selector: "input[name='subscribe']") Returns true if the element was successfully unchecked.

Arguments

selector: String - The CSS selector for the element. Example: "#username" for <input id="username" />.
text: String - Finds an element by its text content. Example: "Login" for <button>Login</button>.
role: ARIARole - Finds an element by its ARIA role. Example: "button" for <div role="button">Submit</div>.
label: String - Finds an element by its ARIA label. Example: "Search button" for <button aria-label="Search button"><svg/></button>.
placeholder: String - Finds an element by its placeholder text. Example: "Enter your email" for <input placeholder="Enter your email" />.
altText: String - Finds an element by its image alt text. Example: "Company logo" for <img alt="Company logo" src="..." />.
title: String - Finds an element by its title attribute. Example: "Close dialog" for <span title="Close dialog">X</span>.
testId: String - Finds an element by its data-testid attribute. Example: "submit-button" for <button data-testid="submit-button">Go</button>.
filter: ElementFilterOptions - Advanced filtering options for the element.
options: CheckOptions - Options for the uncheck action, similar to check options.

`waitForEvent`

Boolean! Waits for a specific page event to occur, such as LOAD, REQUEST, or CONSOLE. Example: waitForEvent(event: LOAD, options: { timeout: 10000 }) Returns true if the event occurred within the timeout.

Arguments

event: PageEvent - The page event to wait for. See the PageEvent enum for available values.
options: TimeoutOptions - Options for waiting, such as timeout.

`waitForFunction`

Boolean! Waits for a JavaScript function or predicate to return a truthy value when executed in the page’s context. Example: waitForFunction(functionOrPredicate: "() => window.myAppInitialized === true") Returns true if the function returns truthy within the timeout.

Arguments

functionOrPredicate: String! - A string containing the JavaScript function or predicate to evaluate. It should return a truthy value when the condition is met. Example: "() => document.querySelector('#dynamicElement') !== null"
arg: JSON - An optional JSON serializable argument to pass to the function.
options: WaitForFunctionOptions - Options for waiting, such as polling interval and timeout.

`waitForLoadState`

Boolean! Waits for the page to reach a specific load state, such as DOM_CONTENT_LOADED or NETWORK_IDLE. Example: waitForLoadState(state: NETWORK_IDLE) Returns true if the load state was reached within the timeout.

Arguments

state: LoadState! - The load state to wait for. See the LoadState enum for available values.
options: TimeoutOptions - Options for waiting, such as timeout.

`waitForRequest`

Boolean! Waits for a network request matching a URL or predicate to occur. Example: waitForRequest(urlOrPredicate: "**/api/data") Returns true if a matching request occurred within the timeout.

Arguments

urlOrPredicate: String! - A URL string, glob pattern, or JavaScript predicate string to match against request URLs. Example: "https://example.com/resource.js" or "**/*.css"
options: TimeoutOptions - Options for waiting, such as timeout.

`waitForResponse`

Boolean! Waits for a network response matching a URL or predicate to occur. Example: waitForResponse(urlOrPredicate: "https://api.example.com/user") Returns true if a matching response occurred within the timeout.

Arguments

urlOrPredicate: String! - A URL string, glob pattern, or JavaScript predicate string to match against response URLs. Example: "https://example.com/data.json"
options: TimeoutOptions - Options for waiting, such as timeout.

`waitForURL`

Boolean! Waits for the page’s URL to match a specific string, glob pattern, or predicate. Useful for waiting for navigations or redirects to complete. Example: waitForURL(urlOrPredicate: "**/profile/**", options: { waitUntil: LOAD }) Returns true if the URL matches within the timeout and wait conditions.

Arguments

urlOrPredicate: String! - A URL string, glob pattern, or JavaScript predicate string to match against the page URL. Example: "https://example.com/dashboard" or "**/login?success=true"
options: WaitForOptions - Options for waiting, such as timeout and lifecycle event to wait for.

Queries

Page Queries

AI Mutations

Browser Mutations

Subscriptions

Objects

Inputs

Enums

Directives

​Definition

​Fields

​page

​Examples

​Arguments

​act

​Arguments

​addCookies

​Arguments

​addInitScript

​Arguments

​addScriptTag

​Arguments

​addStyleTag

​Arguments

​blur

​Arguments

​check

​Arguments

​clear

​Arguments

​clearCookies

​Arguments

​clearPermissions

​click

​Arguments

​dragAndDrop

​Arguments

​emulateMedia

​Arguments

​evaluate

​Arguments

​events

​extract

​Arguments

​fill

​Arguments

​focus

​Arguments

​goBack

​Arguments

​goForward

​Arguments

​grantPermissions

​Arguments

​highlight

​Arguments

​hover

​Arguments

​pressKey

​Arguments

​type

​Arguments

​observe

​Arguments

​reload

​Arguments

​scrollIntoView

​Arguments

​selectOption

​Arguments

​selectText

​Arguments

​setExtraHTTPHeaders

​Arguments

​setGeolocation

​Arguments

​setInputFiles

​Arguments

​setOffline

​Arguments

Definition

Fields

`page`

Examples

Arguments

`act`

Arguments

`addCookies`

Arguments

`addInitScript`

Arguments

`addScriptTag`

Arguments

`addStyleTag`

Arguments

`blur`

Arguments

`check`

Arguments

`clear`

Arguments

`clearCookies`

Arguments

`clearPermissions`

`click`

Arguments

`dragAndDrop`

Arguments

`emulateMedia`

Arguments

`evaluate`

Arguments

`events`

`extract`

Arguments

`fill`

Arguments

`focus`

Arguments

`goBack`

Arguments

`goForward`

Arguments

`grantPermissions`

Arguments

`highlight`

Arguments

`hover`

Arguments

`pressKey`

Arguments

`type`

Arguments

`observe`

Arguments

`reload`

Arguments

`scrollIntoView`

Arguments

`selectOption`

Arguments

`selectText`

Arguments

`setExtraHTTPHeaders`

Arguments

`setGeolocation`

Arguments

`setInputFiles`

Arguments

`setOffline`

Arguments

`setViewport`

Arguments

`tap`

Arguments

`touch`

Arguments

`uncheck`

Arguments

`waitForEvent`