Testing & CI

Use BAP workflows for deterministic browser assertions in CI pipelines with bap run.

Workflow Files

BAP workflows are YAML files that define deterministic browser test sequences:

name: login-test
description: Verify login flow works end-to-end

steps:
  - navigate: https://myapp.com/login
  - fill:
      selector: label:Email
      value: [e-mail]
  - fill:
      selector: label:Password
      value: testpass123
  - click: role:button:Sign In
  - assert:
      url: contains:/dashboard
  - assert:
      element: text:Welcome back

Running Workflows

# Run a workflow file
bap run tests/login.yaml

# Run with options
bap run tests/login.yaml --headless --timeout=30000

# Run all workflows in a directory
bap run tests/

Assertions

Workflows support several assertion types:

Assertion	Description	Example
url	Check current URL	url: contains:/dashboard
element	Verify element exists	element: text:Welcome
title	Check page title	title: contains:Dashboard
screenshot	Take screenshot for visual review	screenshot: login-result.png

URL Assertions

# Exact match
- assert:
    url: https://myapp.com/dashboard

# Contains
- assert:
    url: contains:/dashboard

# Regex
- assert:
    url: matches:^https://myapp\.com/(dashboard|home)

Element Assertions

# Element exists
- assert:
    element: text:Welcome back

# Element with specific role
- assert:
    element: role:heading:Dashboard

# Element is visible
- assert:
    element: testid:user-avatar
    state: visible

CI Integration

GitHub Actions

name: Browser Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install BAP CLI
        run: npm install -g @browseragentprotocol/cli

      - name: Install browsers
        run: npx playwright install chromium

      - name: Run browser tests
        run: bap run tests/ --headless

Capturing Screenshots on Failure

steps:
  - navigate: https://myapp.com/login
  - fill:
      selector: label:Email
      value: [e-mail]
  - click: role:button:Sign In
  - assert:
      url: contains:/dashboard
  - screenshot: test-result.png

Screenshots are saved to the .bap/ directory by default.

Workflow with Extraction Validation

Combine workflows with extract to validate page content:

name: product-page-test
steps:
  - navigate: https://myapp.com/products
  - extract:
      fields: name,price
      list: product
  - assert:
      extracted:
        minItems: 5

Programmatic Testing

For integration with existing test frameworks, use the TypeScript SDK:

import { describe, it, expect } from "vitest";
import { createClient, role, label } from "@browseragentprotocol/client";

describe("Login flow", () => {
  it("should login and reach dashboard", async () => {
    const client = await createClient("ws://localhost:9222");
    await client.launch({ browser: "chromium", headless: true });
    await client.createPage({ url: "https://myapp.com/login" });

    await client.act({
      steps: [
        { action: "action/fill", params: { selector: label("Email"), value: "[e-mail]" } },
        { action: "action/fill", params: { selector: label("Password"), value: "testpass123" } },
        { action: "action/click", params: { selector: role("button", "Sign In") } },
      ],
    });

    const obs = await client.observe({ includeMetadata: true });
    expect(obs.metadata?.url).toContain("/dashboard");

    await client.close();
  });
});

Tracing Failed Tests

When a test fails, use bap trace to inspect what happened:

# List recent sessions
bap trace --sessions

# View trace for a session
bap trace --session=cli-9222

# Generate an HTML timeline replay
bap trace --session=cli-9222 --replay

The replay generates a self-contained HTML file with a timeline viewer showing every request, its timing, and result summary.