BQL Language Basics

Learning a new language can be intimidating, but mastering BQL doesn't have to be difficult. This guide provides a straightforward overview of how to write BQL with clear examples.

BQL Script Structure

A BQL script is one mutation block containing one or more actions. Actions run in order, top to bottom. Each action has a name, optional arguments that configure it, and response fields that define what data it returns.

mutation ScriptName {
  goto(url: "https://example.com", waitUntil: domContentLoaded) {
    status
  }
  text(selector: "h1") {
    text
  }
  screenshot(type: png) {
    base64
  }
}

• goto, text, and screenshot are the action names.
• url, waitUntil, selector, and type are arguments. They configure how the action runs.
• status, text, and base64 are response fields. They define what data gets returned.

Find all available actions, arguments, and response fields in the BQL API Reference or the Built-in Documentation in the IDE.

Aliases

Because a BQL script is a single mutation block, every action name must be unique. If you use the same action twice, BQL cannot distinguish them in the response.

This fails:

mutation LoginForm {
  goto(url: "https://practicetestautomation.com/practice-test-login/") {
    status
  }
  type(selector: "#username", text: "student") {
    time
  }
  type(selector: "#password", text: "Password123") {  # ❌ duplicate action name
    time
  }
  click(selector: "#submit") {
    time
  }
}

Fix it by prefixing each duplicate action with an alias:

mutation LoginForm {
  goto(url: "https://practicetestautomation.com/practice-test-login/") {
    status
  }
  typeUsername: type(selector: "#username", text: "student") {
    time
  }
  typePassword: type(selector: "#password", text: "Password123") {
    time
  }
  click(selector: "#submit") {
    time
  }
}

Aliases also become the keys in the JSON response, making the result easier to parse.

For GraphQL readers

In GraphQL terms, each action is a mutation field on the root mutation type. Aliases are required because GraphQL does not allow duplicate field names within the same selection set.

Core Actions

Action	What it does	Returns
goto	Navigate to a URL	status, time
click	Click an element	x, y, time
type	Type text into an element	time, selector
select	Select an option from a dropdown	value, selector
text	Extract visible text from an element	text
html	Extract raw HTML from an element	html
screenshot	Capture a screenshot	base64
solve	Solve a CAPTCHA	found, solved, time

For the full list of available actions and their arguments, see the BQL API Reference.

Next Steps

BrowserQL simplifies web automation with intuitive commands and a structure that's easy to learn. Explore these key areas to build more sophisticated automations:

Conditional Logic

Learn how to create "do A or do B" workflows that adapt to different page conditions

Waiting for Things

Master the art of waiting for elements, navigation events, and network responses

Exporting Scripts

Convert your BQL queries to code in multiple programming languages for integration