Skip to main content
The Selenium driver provides WebDriver protocol support for browser automation.
Selenium sessions do not support AI agents (Stagehand, Browser-use) due to WebDriver protocol limitations.

​
Connect

import { selenium, By } from '@bctrl/sdk';

const session = await selenium.connect({
  apiKey: process.env.BCTRL_API_KEY
});

const driver = session.driver;

await driver.get('https://example.com');

await driver.navigate().back();
await driver.navigate().forward();
await driver.navigate().refresh();

const url = await driver.getCurrentUrl();
const title = await driver.getTitle();

​
Finding Elements

import { By } from '@bctrl/sdk';

// Single element
const button = await driver.findElement(By.css('button'));
const input = await driver.findElement(By.id('email'));
const link = await driver.findElement(By.linkText('Click here'));
const heading = await driver.findElement(By.tagName('h1'));
const form = await driver.findElement(By.name('login-form'));
const el = await driver.findElement(By.xpath('//button[@type="submit"]'));

// Multiple elements
const items = await driver.findElements(By.css('li'));

​
Actions

const button = await driver.findElement(By.css('button'));
await button.click();

const input = await driver.findElement(By.css('input'));
await input.sendKeys('Hello World');
await input.clear();

// Get text/attributes
const text = await button.getText();
const href = await link.getAttribute('href');
const value = await input.getAttribute('value');

​
Element State

const element = await driver.findElement(By.css('button'));

const isDisplayed = await element.isDisplayed();
const isEnabled = await element.isEnabled();
const isSelected = await element.isSelected();

​
Cookies

// Add cookie
await driver.manage().addCookie({
  name: 'session',
  value: 'abc123'
});

// Get cookies
const cookie = await driver.manage().getCookie('session');
const allCookies = await driver.manage().getCookies();

// Delete cookies
await driver.manage().deleteCookie('session');
await driver.manage().deleteAllCookies();

​
Window Management

// Size
await driver.manage().window().setRect({ width: 1920, height: 1080 });
const rect = await driver.manage().window().getRect();

// Maximize
await driver.manage().window().maximize();
await driver.manage().window().minimize();
await driver.manage().window().fullscreen();

​
Waiting

import { until } from '@bctrl/sdk';

// Wait for element
await driver.wait(until.elementLocated(By.css('button')), 10000);

// Wait for visibility
const button = await driver.findElement(By.css('button'));
await driver.wait(until.elementIsVisible(button), 10000);

// Wait for title
await driver.wait(until.titleContains('Dashboard'), 10000);

​
Execute Script

// Simple
const title = await driver.executeScript('return document.title');

// With arguments
const text = await driver.executeScript(
  'return arguments[0].textContent',
  element
);

// Async script
const result = await driver.executeAsyncScript(`
  const callback = arguments[arguments.length - 1];
  setTimeout(() => callback('done'), 1000);
`);

​
Full Example

import { selenium, By } from '@bctrl/sdk';

async function main() {
  const session = await selenium.connect({
    apiKey: process.env.BCTRL_API_KEY
  });

  const driver = session.driver;

  await driver.get('https://example.com/login');

  // Fill form
  const emailInput = await driver.findElement(By.id('email'));
  await emailInput.sendKeys('[email protected]');

  const passwordInput = await driver.findElement(By.id('password'));
  await passwordInput.sendKeys('password123');

  const submitButton = await driver.findElement(By.css('button[type="submit"]'));
  await submitButton.click();

  // Wait for redirect
  await driver.wait(async () => {
    const url = await driver.getCurrentUrl();
    return url.includes('/dashboard');
  }, 10000);

  console.log('Login successful!');

  await driver.quit();
}

main();