Run Your First Check

Use this page for the Human/manual lane. If you are working agent-first, the shorter path is to ask your IDE agent:


Use the Glubean skill and add the first runnable API behavior check.

The goal is not to hand-install the SDK or runner. The Glubean CLI creates a runnable verification project, and the template brings the local dependencies it needs.

1. Create a runnable project


mkdir my-api-tests
cd my-api-tests
npx glubean init --no-interactive

The generated project is intentionally separate from your app. Glubean is end-to-end verification: it targets running services, browser journeys, and API behavior from the outside.

Expected shape:


my-api-tests/
├── contracts/
│   └── users.contract.ts
├── tests/
│   └── api.test.ts
├── .env
├── .env.secrets
├── GLUBEAN.md
├── package.json
└── glubean.yaml

The generated local profile runs both tests/ and contracts/. Use tests/ for raw test() checks and contracts/ for executable API promises. The template installs the SDK, runner, local CLI, and schema dependency before the command exits, so npm test should work immediately.

2. Run the generated examples


npm test

You can also call the CLI directly:


npx glubean run --profile local
npx glubean ci run

At this point you have the basic loop:


author behavior -> run it -> inspect evidence

3. Point it at your API

Put shared, non-secret config in .env:


BASE_URL=http://localhost:3000

Put secrets in .env.secrets:


API_TOKEN=your-local-token

Then update the generated files to target your service.

4. Author the first real asset

For behavior you want to reuse as source-of-truth, prefer a contract. A contract is a runnable example of API behavior: it runs as a check, produces evidence, and can later project into Specifications, docs, OpenAPI-shaped output, reports, and agent context.


import { contract, configure } from "@glubean/sdk";
import { z } from "zod";
 
const { http: api } = configure({
  http: {
    prefixUrl: "{{BASE_URL}}",
    headers: {
      Authorization: "Bearer {{API_TOKEN}}",
    },
  },
});
 
const health = contract.http.with("health", {
  client: api,
  tags: ["smoke"],
});
 
export const getHealth = health("get-health", {
  endpoint: "GET /health",
  feature: "System",
  description: "The service exposes a healthy runtime status",
  cases: {
    ok: {
      description: "A running service returns ok",
      expect: {
        status: 200,
        schema: z.object({
          status: z.literal("ok"),
        }),
      },
    },
  },
});

Raw test() is still first-class when you need full TypeScript control. Use it for setup-heavy checks, diagnostics, unusual flows, or behavior that does not need to become a projected contract.

5. Know what to inspect

Local run evidence: structured requests, responses, assertions, traces, and metrics
Stable source: contracts, workflows, and raw tests committed to git
Cloud evidence: uploaded runs grouped under a Target
Derived surfaces: Specifications, docs, reports, and agent context