Configuration reference

blop.config.ts exports a default configuration object. For prose see Guides → Configuration.

Configuration shape

Every field is optional. The shape below lists fields currently passed from the configuration file into CLI browser runs. The programmatic runner accepts additional options.

type CliBrowserConfig = {
  // Discovery
  include?: string[];     // Glob patterns for spec discovery

  // App under test
  baseUrl?: string;

  // Browser
  browser?: BlopBrowserName;              // "chromium" | "camoufox" | "firefox" | "webkit"
  viewport?: { width: number; height: number };
  headed?: boolean;
  containerized?: boolean | { image?: string; containerName?: string };

  // Agent
  provider?: string;
  model?: string;
  apiKey?: string;
  maxSteps?: number;      // Optional hard cap; unlimited by default
  timeoutMs?: number;     // Per-test wall-clock cap
  retries?: number;       // Default: 0
  workers?: number;       // Default: 1

  // Reporting
  reporter?: BlopReporter; // "basic" | "json" | "junit" | "all" (default: "all")
  reportDir?: string;      // Default: ".blop"
  verbose?: boolean;       // Default: false
  captureStepScreenshots?: boolean;
  streamFrames?: boolean;
  frameIntervalMs?: number;

  // Platform
  platformUrl?: string;     // Or BLOP_INGEST_URL
  platformApiKey?: string;  // Or BLOP_INGEST_SECRET; BLOP_PROJECT_ID also required

  // OpenTelemetry — see /reference/environment#opentelemetry
  otelEndpoint?: string;                 // OTLP/HTTP base URL; enables export
  otelHeaders?: Record<string, string>;  // Merged over OTEL_EXPORTER_OTLP_HEADERS
  otelServiceName?: string;              // Default: "blop-runner"
  otelEnvironment?: string;              // deployment.environment.name
  otelPropagateToApp?: boolean;          // Default: false
  otelPropagateAllowlist?: string[];     // Hosts allowed to receive trace context
};

Supported file names

Blop auto-discovers any of:

• blop.config.ts
• blop.config.mts
• blop.config.js
• blop.config.mjs

Override with --config path/to/file.ts.

Precedence

Later sources win:

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

A config-file value is consulted before the environment, not after: the runner resolves flag ?? config first and only falls back to the environment when neither supplied a value. So setting a key in blop.config.ts makes the matching environment variable inert.

BlopBrowserName

type BlopBrowserName = "chromium" | "camoufox" | "firefox" | "webkit";

BlopReporter

type BlopReporter = "basic" | "json" | "junit" | "all";

Value	Files written
basic	results.json + events.jsonl
json	results.json + events.jsonl
junit	results.json + events.jsonl + report.xml
all	Same as junit