First steps

This page walks you from a blank project to a passing agent test in under five minutes. For installation, see Getting started → Installation.

Scaffold a test

$ bunx blop init

This creates tests/homepage.blop.ts:

import { agentTest, describe } from "blop";

describe("homepage", () => {
  agentTest("loads", async ({ agent }) => {
    await agent.goto("/");
    await agent.goal("Verify the homepage loads and the primary user action is visible.");
  });
});

agent.goto() and agent.goal() don’t run anything immediately — they build a numbered goal list the agent receives when the runner reaches the test.

Run it

$ bunx blop test --base-url http://localhost:3000

What happens:

Blop discovers any **/*.blop.ts spec under the current directory.
It launches a Playwright browser (Chromium by default).
The agent receives your goal and a curated set of browser tools.
The agent navigates, inspects, asserts, and finally calls finish_test.
Blop writes a structured run result to .blop/.

Output

After a run, the report directory (default: .blop/) contains:

File	Description
`.blop/results.json`	Structured `BlopRunResult` with every test outcome
`.blop/events.jsonl`	One agent event per line — useful for debugging
`.blop/report.xml`	JUnit-compatible XML for CI consumers
`.blop/screenshots/`	Screenshots captured during the run

See Reporters & output to choose a format and consume the result schema downstream.

Configure once

Drop a blop.config.ts at your project root to avoid passing flags every run:

import type { BlopConfig } from "blop";

export default {
  baseUrl: "http://localhost:3000",
  browser: "chromium",
  reporter: "all",
  include: ["tests/**/*.blop.ts"],
} satisfies BlopConfig;

CLI flags always override config values. Full options live in Configuration.

Watch mode

While iterating on a spec:

$ bunx blop watch tests/

Reruns affected tests on file change. Polls every second. Press Ctrl+C to stop.

Next steps