Introduction

An intent-based agentic browser testing framework. Describe what to verify; an AI agent drives a real browser to figure out how.

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

Highlights

• CLI-first. blop init, blop test, blop watch, blop list, blop skills — one binary, every workflow.
• Intent over selectors. Goals stay readable when the UI changes. No brittle data-testid chains or manual click sequences.
• Real Playwright browser. Chromium, Firefox, or WebKit through controlled native tools — no script execution, no shell escapes.
• Reusable browser harness. Drive persistent CLI sessions, embed controlled tools, or run warm browser containers with @blopai/browser-harness.
• CI-native output. Every run writes results.json, an events.jsonl stream, JUnit XML, and screenshots into .blop/.
• Provider-agnostic. OpenAI, Anthropic, Google, Groq, xAI, OpenRouter, Mistral, Cerebras, NVIDIA via Khadim.
• Local-first, platform-ready. Run on your laptop today. The same result schema uploads to Blop Platform when you want hosted history.
• Configurable. blop.config.ts with full TypeScript types, or override per-run with CLI flags.

Installation

Install blop into your project:

$ bun add blop
# or
$ pnpm add blop
# or
$ npm install blop

Set your provider credentials:

$ export BLOP_AGENT_PROVIDER=openai
$ export BLOP_AGENT_MODEL=gpt-5
$ export BLOP_AGENT_API_KEY=sk-...

Then check out the first steps or read on for a brief overview.

Writing tests

A Blop test is a TypeScript file ending in .blop.ts that exports one or more agent tests:

import { agentTest, describe } from "blop";

describe("onboarding", () => {
  agentTest("user can create a project", async ({ agent }) => {
    await agent.goto("/");
    await agent.goal(`
      Sign in as the seeded user.
      Create a project called "Checkout QA".
      Verify the project appears in the dashboard.
    `);
  });
});

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

See the writing tests concept to get started.

Running tests

$ bunx blop init                       # scaffold a starter spec
$ bunx blop test --base-url http://localhost:3000
$ bunx blop watch tests/               # rerun on file change
$ bunx blop list                       # print discovered test names

What happens on a run:

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

See the CLI guide to get started.

Skills

Blop ships bundled SKILL.md files that teach the agent domain-specific patterns. Manage them with the blop skills command:

$ blop skills list                       # list bundled skills
$ blop skills view <name>                # view a skill's full content
$ blop skills check                      # validate all skills
$ blop skills improve <name>             # distill learnings into a skill

See the skills guide to learn more.

Configuration

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. See the configuration concept for every field.

Learn more

See the first steps or jump straight to the guides to start using blop.