Skip to main content
Version: v2

Advanced Options

BrowserQL offers advanced options allows developers to create dynamic, condition-based workflows, capture visual data, and interact programmatically with web pages. These options enhance the flexibility of web automation, making it possible to tackle complex scenarios with ease. Below, you’ll find detailed examples and use cases to help you with these advanced features.

Conditional Behaviors​

You can use if or ifnot mutations to trigger nested work branches based on specific conditions. A common use case for this is when a browser interaction receives a 403 code, indicating the need to use a verification or captcha-solving mutation.

The example below will only trigger the verify mutation when the goto returns a 403 code:

mutation ConditionalCase {
  goto(url: "https://www.browserless.io/", waitUntil: domContentLoaded) {
    status
  }
  if(response: {codes: 403}) {
    waitForTimeout(time: 2000) {
      time
    }
    verify(type: cloudflare) {
      solved
    }
  }
}

Now, a ifnot can be used to treat cases where the code isn't 403. For example, the code below retrieves the page's title when any other code is returned:

mutation ConditionalCase {
  goto(url: "https://www.browserless.io/", waitUntil: domContentLoaded) {
    status
  }
  if(response: {codes: 403}) {
    waitForTimeout(time: 2000) {
      time
    }
    verify(type: cloudflare) {
      solved
    }
  }
  
  ifnot(response: {codes: 403}) {
    title {
      title
    }
  }
}

This example opens up two different work branchs, one that will be triggered when a code 403 is received, and a second one to handle when any other code is returned.

Taking Screenshots​

BrowserQL can be used to take screenshots from any website. With the screenshot mutator, you can generate any image, and BQL will return a base64 encoded string of the new image.

For example, the code below takes a picture of https://example.com/, focusing on the middle section using the clip argument to define the image's size, and screen position.

mutation TakeScreenshot {
  goto(url: "https://example.com/") {
    status
  }
  screenshot(clip: {width: 720, height: 300, x: 150, y: 65}) {
    base64
  }
}
Available arguments

Refer to the Mutation Reference page for full details on the available arguments and response from the screenshot mutation.

Now, with the image's base64, you can use it, as exemplified below, replacing <PASTE_YOUR_BASE64_HERE> with your base64 string:

<!DOCTYPE html>
<html>
<head>
    <title>Base64 Image Viewer</title>
</head>
<body>
    <img src="data:image/png;base64,<PASTE_YOUR_BASE64_HERE>" alt="Base64 Image">
</body>
</html>

Generating PDFs​

Similarly to taking screenshots, there is the pdf mutation to generate PDFs. BQL will generate a base64 encoded string from any website.

mutation GetPDF {
  goto(url: "https://example.com/") {
    status
  }
  pdf {
    base64
  }
}
Available arguments

Refer to the Mutation Reference page for full details on the available arguments and response from the pdf mutation.

With the PDF's base64 string, you can generate the PDF file, or make it downloadable in your own site.

<!DOCTYPE html>
<html>
<head>
    <title>Base64 PDF Viewer</title>
</head>
<body>
    <iframe src="data:application/pdf;base64,<PASTE_YOUR_BASE64_HERE>" width="600" height="400"></iframe>
    <a href="data:application/pdf;base64,<PASTE_YOUR_BASE64_HERE>" download="document.pdf">Download PDF</a>
</body>
</html>