Browser Automation

Control headless browsers on InstaVM for web scraping, testing, and automated workflows.

Quick start

Python

from instavm import InstaVM

client = InstaVM("your_api_key")

with client.browser.create_session() as session:
    session.navigate("https://example.com")
    screenshot = session.screenshot()
    print(f"Screenshot: {len(screenshot)} chars (base64)")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

const session = await client.browser.createSession();
await session.navigate('https://example.com');
const screenshot = await session.screenshot();
console.log(`Screenshot: ${screenshot.length} chars (base64)`);
await session.close();

Navigation

Python

session.navigate("https://example.com", wait_timeout=30000)

JavaScript

await session.navigate('https://example.com', { waitTimeout: 30000 });

Form interaction

Fill and submit forms:

Python

with client.browser.create_session() as session:
    session.navigate("https://example.com/login")
    session.fill("input[name='email']", "user@example.com")
    session.fill("input[name='password']", "password123")
    session.click("button[type='submit']")
    session.wait_for("visible", selector=".dashboard")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
const session = await client.browser.createSession();

await session.navigate('https://example.com/login');
await session.fill("input[name='email']", 'user@example.com');
await session.fill("input[name='password']", 'password123');
await session.click("button[type='submit']");
await session.waitFor('visible', { selector: '.dashboard' });
await session.close();

Screenshots

Python

# Full page
full = session.screenshot(full_page=True)

# Clipped region
clipped = session.screenshot(
    full_page=False,
    clip={"x": 0, "y": 0, "width": 800, "height": 600}
)

JavaScript

// Full page
const full = await session.screenshot({ fullPage: true });

// Clipped region
const clipped = await session.screenshot({
  fullPage: false,
  clip: { x: 0, y: 0, width: 800, height: 600 },
});

Data extraction

Extract structured data from pages:

Python

with client.browser.create_session() as session:
    session.navigate("https://news.ycombinator.com")
    session.wait_for("load")

    posts = session.extract_elements(
        selector=".titleline > a",
        attributes=["href", "text"]
    )

    for post in posts[:5]:
        print(f"{post['text']}: {post['href']}")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
const session = await client.browser.createSession();

await session.navigate('https://news.ycombinator.com');
await session.waitFor('load');

const posts = await session.extractElements('.titleline > a', ['href', 'text']);

for (const post of posts.slice(0, 5)) {
  console.log(`${post.text}: ${post.href}`);
}
await session.close();

Scrolling and waiting

Python

# Scroll to load more content
session.scroll(y=1000)

# Wait for element to appear
session.wait_for("visible", selector="div.content", timeout=5000)

# Wait for page load
session.wait_for("load", timeout=30000)

JavaScript

// Scroll to load more content
await session.scroll({ y: 1000 });

// Wait for element to appear
await session.waitFor('visible', { selector: 'div.content', timeout: 5000 });

// Wait for page load
await session.waitFor('load', { timeout: 30000 });

Multi-page workflows

Python

with client.browser.create_session() as session:
    # Page 1: Search
    session.navigate("https://example.com")
    session.fill("input#search", "instavm")
    session.click("button[type='submit']")
    session.wait_for("visible", selector=".results")

    # Page 2: Click first result
    session.click(".results a:first-child")
    session.wait_for("load")

    # Extract content
    content = session.extract_elements("article", ["text"])
    print(content[0]["text"])

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
const session = await client.browser.createSession();

// Page 1: Search
await session.navigate('https://example.com');
await session.fill('input#search', 'instavm');
await session.click("button[type='submit']");
await session.waitFor('visible', { selector: '.results' });

// Page 2: Click first result
await session.click('.results a:first-child');
await session.waitFor('load');

// Extract content
const content = await session.extractElements('article', ['text']);
console.log(content[0].text);
await session.close();

Error handling

Python

from instavm import (
    InstaVM,
    ElementNotFoundError,
    BrowserTimeoutError,
    BrowserNavigationError
)

try:
    session.click("button.nonexistent")
except ElementNotFoundError as e:
    print(f"Element not found: {e}")
except BrowserTimeoutError as e:
    print(f"Timed out: {e}")
except BrowserNavigationError as e:
    print(f"Navigation failed: {e}")

JavaScript

import { InstaVM, ElementNotFoundError, BrowserTimeoutError, BrowserNavigationError } from 'instavm';

try {
  await session.click('button.nonexistent');
} catch (error) {
  if (error instanceof ElementNotFoundError) {
    console.log(`Element not found: ${error.message}`);
  } else if (error instanceof BrowserTimeoutError) {
    console.log(`Timed out: ${error.message}`);
  } else if (error instanceof BrowserNavigationError) {
    console.log(`Navigation failed: ${error.message}`);
  }
}

Viewport configuration

Python

session = client.browser.create_session(
    viewport_width=1920,
    viewport_height=1080,
)

JavaScript

const session = await client.browser.createSession({
  viewportWidth: 1920,
  viewportHeight: 1080,
});

await session.navigate('https://example.com');
const elements = await session.extractElements('h1', ['text']);
console.log(elements);
await session.close();

Next steps

• Python SDK: Browser Automation -- full method reference
• TypeScript SDK -- browser API in TypeScript
• REST API: Browser -- API endpoints