Skip to main content

Integrate with Selenium

Aluvia integrates with Selenium by configuring the browser's proxy settings (via Selenium Options/capabilities). You point the browser at a proxy, and the browser sends traffic through that proxy.

By default, AluviaClient starts a local proxy on 127.0.0.1. You then configure Selenium to use that local proxy. This is the safest/cleanest integration because:

  • No proxy credentials are embedded in your test config (the SDK holds gateway credentials internally).
  • The SDK can do per-hostname routing (direct vs Aluvia) when running the local proxy.
import { Builder } from 'selenium-webdriver';
import chrome from 'selenium-webdriver/chrome';
import { AluviaClient } from '@aluvia/sdk';

const client = new AluviaClient({
  apiKey: process.env.ALUVIA_API_KEY!,
  connectionId: process.env.ALUVIA_CONNECTION_ID, // optional
});

const connection = await client.start();

const options = new chrome.Options().addArguments(
  connection.asSelenium(),
);

const driver = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(options)
  .build();

try {
  await driver.get('https://ipconfig.io/json');
} finally {
  await driver.quit();
  await connection.close();
}

Node.js: use the SDK API wrapper to fetch gateway proxy credentials​

If you don’t want to start the SDK’s local proxy process, you can call the Aluvia API directly via the SDK’s API wrapper (AluviaApi) to fetch the proxy username/password for an account connection, then configure Selenium with those credentials.

Important notes:

  • These calls use /account/... endpoints, so you must use an account API token.
  • The SDK’s gateway host is gateway.aluvia.io. You choose protocol/port (commonly http:8080 or https:8443).
  • Treat proxy credentials as secrets. Don’t log them.
import { Builder } from 'selenium-webdriver';
import chrome from 'selenium-webdriver/chrome';
import { AluviaApi } from '@aluvia/sdk';

const apiKey = process.env.ALUVIA_API_KEY!;
const connectionId = process.env.ALUVIA_CONNECTION_ID!;

const api = new AluviaApi({ apiKey });

const accountConn = await api.account.connections.get(connectionId);
if (!accountConn) {
  throw new Error('Connection config was not returned (HTTP 304 Not Modified)');
}

const username = accountConn.proxy_username;
const password = accountConn.proxy_password;
if (!username || !password) {
  throw new Error('API response missing proxy credentials (proxy_username/proxy_password)');
}

const server = 'http://gateway.aluvia.io:8080';

// Many Selenium setups require help (e.g. an auth-capable proxy helper/extension)
// to use username/password with a browser proxy. The snippet below encodes creds
// into the proxy URL for environments that support it.
const proxyUrl = new URL(server);
proxyUrl.username = username;
proxyUrl.password = password;

const options = new chrome.Options().addArguments(
  `--proxy-server=${proxyUrl.toString()}`,
);

const driver = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(options)
  .build();

try {
  await driver.get('https://ipconfig.io/json');
} finally {
  await driver.quit();
}

Raw HTTP examples (JavaScript / Python)​

These examples show how to:

  • send an HTTP request to GET /v1/account/connections/:id
  • extract proxy_username / proxy_password
  • configure Selenium with the resulting proxy settings
import { Builder } from 'selenium-webdriver';
import chrome from 'selenium-webdriver/chrome';

const apiKey = process.env.ALUVIA_API_KEY;
const connectionId = process.env.ALUVIA_CONNECTION_ID;

if (!apiKey || !connectionId) {
  throw new Error('Missing ALUVIA_API_KEY or ALUVIA_CONNECTION_ID');
}

const res = await fetch(`https://api.aluvia.io/v1/account/connections/${connectionId}`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    Accept: 'application/json',
  },
});

if (!res.ok) {
  throw new Error(`Aluvia API request failed (HTTP ${res.status})`);
}

const json = await res.json();
const data = json?.data ?? null;
if (!data) {
  throw new Error('Aluvia API response missing data envelope');
}

const username = data.proxy_username;
const password = data.proxy_password;
if (!username || !password) {
  throw new Error('Aluvia API response missing proxy_username/proxy_password');
}

const server = 'http://gateway.aluvia.io:8080';

const proxyUrl = new URL(server);
proxyUrl.username = username;
proxyUrl.password = password;

const options = new chrome.Options().addArguments(
  `--proxy-server=${proxyUrl.toString()}`,
);

const driver = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(options)
  .build();

try {
  await driver.get('https://ipconfig.io/json');
} finally {
  await driver.quit();
}