Session Replay with BQL (Beta)

info

Session Replay is a Beta feature available for all users.

The Session Replay feature in BrowserQL allows you to record browser sessions and later replay them for debugging and analysis. When using BQL, session recording is controlled through connection parameters and provides seamless integration with GraphQL mutations.

This feature is particularly useful for:

• Debugging complex BQL automation workflows
• Creating visual documentation of GraphQL-based browser automation
• Troubleshooting BQL mutations with recorded evidence

Prerequisites

Before using Session Replay with BQL, make sure you have:

1. A Browserless account with Session Replay access
2. A browserless API key
3. Access to the BQL endpoint
4. Understanding of GraphQL mutation syntax

Recording a Session with BQL

Connection String Configuration

To enable session recording with BQL, add the replay=true parameter to your connection string:

wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&replay=true

Basic Recording Example

BrowserQL

mutation RecordSession {
  goto(url: "https://www.example.com") {
    status
    time
  }
  
  click(selector: "button.example") {
    time
    x
    y
  }
  
  type(selector: "input[name='search']", text: "browserless") {
    time
  }
  
  waitForSelector(selector: ".search-results") {
    time
  }
}

JavaScript

import fetch from 'node-fetch';

const API_KEY = "YOUR_API_TOKEN_HERE";
const BQL_ENDPOINT = "https://production-sfo.browserless.io/chromium/bql?replay=true";

const recordingQuery = `
mutation RecordSession {
  goto(url: "https://www.example.com") {
    status
    time
  }
  
  click(selector: "button.example") {
    time
    x
    y
  }
  
  type(selector: "input[name='search']", text: "browserless") {
    time
  }
  
  waitForSelector(selector: ".search-results") {
    time
  }
}`;

const recordSession = async () => {
  const response = await fetch(BQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ query: recordingQuery })
  });

  const result = await response.json();
  console.log('Recording Result:', JSON.stringify(result, null, 2));
  
  // Session recording automatically stops when the BQL query completes
  console.log('Session recorded successfully');
};

recordSession().catch(console.error);

Python

import requests
import json

API_KEY = "YOUR_API_TOKEN_HERE"
BQL_ENDPOINT = "https://production-sfo.browserless.io/chromium/bql?replay=true"

recording_query = """
mutation RecordSession {
  goto(url: "https://www.example.com") {
    status
    time
  }
  
  click(selector: "button.example") {
    time
    x
    y
  }
  
  type(selector: "input[name='search']", text: "browserless") {
    time
  }
  
  waitForSelector(selector: ".search-results") {
    time
  }
}
"""

def record_session():
    response = requests.post(
        BQL_ENDPOINT,
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {API_KEY}'
        },
        json={'query': recording_query}
    )
    
    result = response.json()
    print('Recording Result:', json.dumps(result, indent=2))
    
    # Session recording automatically stops when the BQL query completes
    print('Session recorded successfully')

if __name__ == "__main__":
    record_session()

Advanced Recording with Session Management

For more complex workflows, combine session recording with BQL session management:

BrowserQL

mutation AdvancedRecording {
  goto(url: "https://app.example.com/login") {
    status
    time
  }
  
  type(selector: "#username", text: "user@example.com") {
    time
  }
  
  type(selector: "#password", text: "password123") {
    time
  }
  
  click(selector: "#login-button") {
    time
    x
    y
  }
  
  waitForSelector(selector: ".dashboard") {
    time
  }
  
  # Navigate through multiple pages
  click(selector: ".nav-reports") {
    time
  }
  
  waitForSelector(selector: ".reports-table") {
    time
  }
  
  # Extract data for verification
  querySelector(selector: ".user-profile .name") {
    text
  }
}

JavaScript

const advancedQuery = `
mutation AdvancedRecording {
  goto(url: "https://app.example.com/login") {
    status
    time
  }
  
  type(selector: "#username", text: "user@example.com") {
    time
  }
  
  type(selector: "#password", text: "password123") {
    time
  }
  
  click(selector: "#login-button") {
    time
    x
    y
  }
  
  waitForSelector(selector: ".dashboard") {
    time
  }
  
  click(selector: ".nav-reports") {
    time
  }
  
  waitForSelector(selector: ".reports-table") {
    time
  }
  
  querySelector(selector: ".user-profile .name") {
    text
  }
}`;

const recordAdvancedSession = async () => {
  const response = await fetch(
    "https://production-sfo.browserless.io/chromium/bql?replay=true&timeout=300000",
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({ query: advancedQuery })
    }
  );

  const result = await response.json();
  console.log('Advanced Recording Result:', JSON.stringify(result, null, 2));
};