> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opslane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Runs: Real Chromium in Ephemeral Sandboxes

> Understand how Opslane uses a real Chromium browser to crawl your app, interact with flows, and detect regressions — without any test scripts from you.

A browser run is the core unit of work in Opslane. When a pull request triggers a test, Opslane provisions a fresh, isolated environment, launches a real Chromium browser inside it, and drives that browser through your deployed app to verify it works. The browser is not a screenshot tool — it clicks buttons, fills in forms, follows navigation, and exercises your app the way a real user would.

## What "real browser" means

Opslane uses a full Chromium-based browser, not a lightweight headless renderer. This distinction matters because many rendering and interaction issues only appear in a real browser context:

* JavaScript executes the same way it does for your users.
* CSS animations, transitions, and layout are resolved correctly.
* Network requests, cookies, and browser storage behave as expected.
* Third-party scripts, fonts, and embeds load normally.

<Info>
  Because Opslane uses a real browser, it catches the class of bugs that synthetic monitors and screenshot diffing tools miss — things like broken form submissions, JavaScript errors that prevent navigation, or race conditions in async UI flows.
</Info>

## Ephemeral sandboxes

Every browser run happens inside a sandboxed environment that is created fresh for that run and destroyed immediately after it completes.

<Steps>
  <Step title="Sandbox is provisioned">
    When a PR event fires, Opslane allocates a clean, isolated environment. No state carries over from any previous run or any other repository.
  </Step>

  <Step title="Chromium launches and navigates to your preview">
    The browser opens the deployed preview URL for the PR branch. Opslane begins from the root of your app and discovers pages from there.
  </Step>

  <Step title="The run executes">
    Opslane crawls pages, identifies interactive elements, and exercises flows. Screenshots and a full-session video are recorded throughout.
  </Step>

  <Step title="Sandbox is destroyed">
    When the run finishes, the sandbox and all its contents are permanently deleted. Your application code, credentials, and session data are never retained.
  </Step>
</Steps>

<Warning>
  Opslane never stores or persists your source code. The browser connects to your deployed preview URL over the network — your code never runs inside the sandbox itself.
</Warning>

## How Opslane decides what to test

Opslane does not read test scripts. Instead, it uses the live app to discover what to test:

<AccordionGroup>
  <Accordion title="Page crawling">
    Opslane starts at the root URL and follows links, navigation elements, and routes it discovers. This builds a map of the pages in your app.
  </Accordion>

  <Accordion title="Flow detection">
    On each page, Opslane identifies interactive elements — buttons, forms, links, dropdowns — and determines which ones represent meaningful user flows worth testing.
  </Accordion>

  <Accordion title="Interaction and assertion">
    Opslane interacts with detected flows: filling forms with representative inputs, clicking through multi-step sequences, and verifying that expected outcomes occur (page loads, state changes, no JavaScript errors).
  </Accordion>

  <Accordion title="Regression comparison">
    Results from the PR branch are compared against the baseline from your main branch. Differences that indicate broken behavior are flagged as regressions.
  </Accordion>
</AccordionGroup>

## What the browser does during a run

Inside the sandbox, the Chromium browser performs real interactions:

<CardGroup cols={2}>
  <Card title="Navigation" icon="compass">
    Follows links and routes to reach every reachable page in your app.
  </Card>

  <Card title="Form interaction" icon="pen-to-square">
    Fills in text fields, selects options, checks boxes, and submits forms to exercise input flows.
  </Card>

  <Card title="Click interaction" icon="computer-mouse">
    Clicks buttons, toggles, tabs, and other interactive controls to trigger state changes.
  </Card>

  <Card title="Assertion checking" icon="circle-check">
    Verifies that pages load successfully, expected elements are present, and no critical errors occur.
  </Card>
</CardGroup>

## Run duration and behavior expectations

Run duration depends on the size and complexity of your app. A typical run for a small-to-medium web app completes in a few minutes. Apps with many pages, complex flows, or slow preview deployments may take longer.

<Tip>
  If your preview deployment takes a while to become available after a PR is pushed, Opslane will wait for it to be ready before starting the browser run. You do not need to manually delay anything.
</Tip>

During a run, you will see a pending GitHub status check on the PR. Once the run completes — whether it passes or fails — the status check is updated and Opslane posts a comment with the full results.

## Framework compatibility

Because Opslane interacts with your app through a real browser at the network level, it works with any browser-based stack. There is nothing framework-specific to configure.

<Tabs>
  <Tab title="JavaScript frameworks">
    React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, Remix, Astro, and any other framework that produces a browser-accessible app.
  </Tab>

  <Tab title="Backend-rendered stacks">
    Rails, Django, Laravel, Phoenix, and any server-rendered stack where the output is HTML served to a browser.
  </Tab>

  <Tab title="Static sites">
    Gatsby, Eleventy, Hugo, Jekyll, and other static site generators deployed to a preview URL.
  </Tab>
</Tabs>