Test DSL

The functions and types a browser check spec file uses, imported from @blopai/test.

import { agentTest, describe } from "@blopai/test";

describe("auth", () => {
  agentTest("login with valid credentials", async ({ agent }) => {
    await agent.goto("/login");
    await agent.goal("Sign in as qa@example.com and verify the dashboard heading appears.");
  });
});

DSL functions

Function	Purpose
describe(name, fn)	Named scope; nested names join with >, as in auth > login with valid credentials
agentTest(name, handler)	Register a check; the handler receives a BlopAgentTestContext
defineAgentTest(test)	Validate and return a BlopAgentTest object

agent.goto() and agent.goal() do not act when called: they queue steps the agent works through when the check runs. A spec can combine registered agentTest checks with exported objects: default (one check or an array), tests, or any other exported array of BlopAgentTest. Registered checks come first, and an object exported twice runs once.

DSL types

Type	Shape
BlopAgent	goto(url): queue a navigation, relative to baseUrl; goal(text): queue a natural-language goal
BlopAgentTestContext	{ agent: BlopAgent; baseUrl?: string }
BlopAgentTestHandler	(context) => void | Promise<void>
BlopAgentTest	{ name: string; goal: string; baseUrl?: string; timeoutMs?: number }; name and goal must be non-empty, timeoutMs a positive integer
BlopAgentStep	{ type: "goto"; url } or { type: "goal"; goal }, one queued step