Language Basics

Many cases for gathering data or normalizing data across systems require you click, type and submit forms. All of these are staples of any web automation library and are supported by BrowserQL.

By default, BrowserQL takes care of waiting for these elements to be present in the document, visible to an end user, and scrolls to them in the viewport. You won't have to worry about writing code to handle those small nuanced situations.

This guide will help you to write a first BQL to interact with the browser, going through the following interactions:

• Clicking a Button
• Keyboard Typing
• HTML Content
• Retriving Text

Clicking a Button

To click the Free Trial link at the Browserless.io website, you need to navigate to the website with the goto mutation, and then use the click to select the <a> element. In the example below, we'll use the element's href to find the correct element on screen. Also, the visible flag specifies that this element must be visible to the user.

Clicking

mutation ClickButton {
  goto(url: "https://www.browserless.io/" waitUntil: firstContentfulPaint) {
    status
  }

  click(selector: "a[href=\"https://account.browserless.io/signup/email/?plan=starter\"]", visible: true) {
    x
    y
  }
}

Setting a Timeout

By default BrowserQL will automatically wait for elements to be present before interacting with them. You can limit the amount of time it will wait by setting a timeout argument. The following will limit the timeout to 10 seconds versus the default of 30 seconds:

mutation ClickButton {
  goto(url: "https://www.browserless.io/" waitUntil: firstContentfulPaint) {
    status
  }

  click(
    selector: "a[href=\"https://account.browserless.io/signup/email/?plan=starter\"]",
    visible: true
    timeout: 10000
  ) {
    x
    y
  }
}

Keyboard Typing

Typing is also supported, and works similarly to how the click query does. After navigating to a website, you need to specify the text you want to be typed, along with the selector, telling the query where it should type the content.

Typing

mutation TypeInteraction {
  goto(url: "https://www.google.com/" waitUntil: firstContentfulPaint) {
    status
  }

  type(
    text: "I'm a little teapot!"
    selector: "form textarea"
  ) {
    x
    y
  }
}

Setting a Delay

By default, BrowserQL will type a character at a time with a random interval of space between similar to a real user. If you wish to change this delay you can specify a delay argument which receives an array with a minimum and maximum delay time ([min, max]) in milliseconds.

mutation TypeInteraction {
  goto(url: "https://www.google.com/" waitUntil: firstContentfulPaint) {
    status
  }

  type(
    text: "I'm a little teapot!"
    selector: "form textarea"
    delay: [10, 50]
  ) {
    x
    y
  }
}

This means a delay between 10 and 50 milliseconds is chosen at random between keystrokes.

HTML Content

You can retrieve HTML content from any website with BrowserQL as well. Use the html mutation after navigating to the website.

HTML

mutation HTMLInteraction {
  goto(url: "https://www.browserless.io/" waitUntil: firstContentfulPaint) {
    status
  }

  html(
    visible: true
  ) {
    time
    html
  }
}

With Selector

You can set a selector to the html mutation to define what content you want to retrieve from the page. In the case below, we return the content from the h1 element with .heading-style-h1.margin-bottom.margin-large classes.

mutation HTMLInteraction {
  goto(url: "https://www.browserless.io/" waitUntil: firstContentfulPaint) {
    status
  }

  html(
    selector: "h1.heading-style-h1.margin-bottom.margin-large"
    visible: true
  ) {
    time
    html
  }
}

Retriving Text

To retrieve the text from a element in any website, you can use the text mutation, and add a selector argument to define which element to search for the text content.

Text

mutation TextInteraction {
  goto(url: "https://www.example.com/" waitUntil: firstContentfulPaint) {
    status
  }

  text(
    selector: "p"
    visible: true
  ) {
    time
    text
  }
}

Last element of its kind

mutation TextInteraction {
  goto(url: "https://www.example.com/" waitUntil: firstContentfulPaint) {
    status
  }

  text(
    selector: "p:last-of-type"
    visible: true
  ) {
    time
    text
  }
}

More interactions

You can also toggle check-boxes, radio-boxes and select elements as well with BrowserQL. Refer to the Editors built-in documentation for more details on those types of queries, or check them out in the BrowserQL Reference.