Documentation

Configuration

Set defaults once in blop.config.ts and override per run.

Blop reads blop.config.ts (or .mts, .js, .mjs) from the project root. Every option is optional; the runner has sensible defaults.

A typical config

import type { BlopConfig } from "@blopai/cli";

export default {
  // Discovery
  include: ["tests/**/*.blop.ts"],
  exclude: ["tests/_**/*"],

  // App under test
  baseUrl: "http://localhost:3000",

  // Browser
  browser: "chromium",
  viewport: { width: 1280, height: 720 },
  headed: false,

  // Agent
  provider: "openrouter",
  model: "anthropic/claude-sonnet-4-6",
  maxSteps: 100,
  timeoutMs: 30_000,
  retries: 1,

  // Reporting
  reporter: "all",
  reportDir: ".blop",
} satisfies BlopConfig;

Discovery

Option	Default	What it does
`include`	`["*/.blop.ts", "*/.blop.tsx"]`	Glob patterns for spec files
`exclude`	`[]`	Glob patterns to skip
`cwd`	`process.cwd()`	Working directory for discovery

CLI patterns override include. Files under node_modules/, dist/, .blop/, or .git/ are always skipped.

App under test

Option	Default	What it does
`baseUrl`	(none)	Resolved against relative `agent.goto("/path")` calls
`browserContext`	(none)	Playwright `BrowserContextOptions` for cookies, auth, and storage

Use browserContext.storageState to seed an authenticated session.

Browser

Option	Default	What it does
`browser`	`"chromium"`	One of `chromium`, `firefox`, `webkit`
`viewport`	(Playwright default)	`{ width, height }`
`headed`	`false`	Show the browser window

Agent

Option	Default	What it does
`provider`	env `BLOP_AGENT_PROVIDER`	Provider name (default `openrouter`)
`model`	env `BLOP_AGENT_MODEL`	Model name
`apiKey`	env `BLOP_AGENT_API_KEY`	API key
`maxSteps`	`100`	Max agent tool calls before timeout
`timeoutMs`	(none)	Per-test wall-clock cap
`retries`	`0`	Re-run failed tests this many times

Reporting

Option	Default	What it does
`reporter`	`"all"`	One of `basic`, `json`, `junit`, `all`
`reportDir`	`".blop"`	Where to write artifacts
`verbose`	`false`	Stream agent events to stderr

Platform upload

Option	Env var	What it does
`platformUrl`	`BLOP_PLATFORM_URL`	Blop Platform ingest URL
`platformApiKey`	`BLOP_API_KEY`	Blop Platform API key

If both are set, the runner uploads the BlopRunResult after the run.

Precedence

When the same option is set in more than one place, later sources win:

Defaults baked into the runtime
blop.config.ts
Environment variables (BLOP_AGENT_*, provider-native keys)
CLI flags

So a CI run can pin --max-steps 75 without touching the config file.

Supported file names

Blop auto-discovers any of blop.config.ts, blop.config.mts, blop.config.js, or blop.config.mjs. Pass --config path/to/file.ts to point at a custom location.