Generate with AI

Why Glubean is AI-native

Your IDE agent is one of the main ways to author Glubean work. It can read your repo, write TypeScript contracts, compose workflows, add raw test() checks, run them through MCP or the CLI, inspect structured failures, and repair the source or the check.

Most API tools were built for humans clicking buttons. AI agents cannot rely on that workflow. They need source files, stable project context, executable evidence, and machine-readable failures. Glubean is built around those surfaces.

The AI closed-loop is already real today:

1. Skill — tells the AI how to author Glubean behavior assets (SDK patterns, project conventions, rules)
2. MCP server — gives the AI tools to discover, run, and inspect tests without leaving the chat
3. Schema inference — large API responses are summarized as JSON Schema, so AI understands the shape without reading megabytes of data
4. Structured failures — when a test fails, AI sees exactly which assertion failed with expected vs actual, not a wall of text

With the right project context — ideally API source code in the same workspace, or an up-to-date OpenAPI spec, plus the skill (which bundles SDK reference docs) — the loop becomes practical: describe the behavior → AI writes a contract, workflow, or raw test() → MCP runs it → AI reads structured failures → fixes and reruns → loop until green. In practice, quality depends heavily on how much context is available. Even without perfect setup, agent-authored checks are a strong starting point that you refine, not write from scratch.

Setup

npx skills add glubean/skill   # teach your agent Glubean patterns
npx glubean config mcp         # connect MCP tools for run/discover/inspect

After this, your AI tool (Claude Code, Cursor, Codex) can discover tests, run them, and read results — all through structured APIs.

One sentence to a working behavior asset

No Postman collection. No complex config. Just your AI and one sentence.

Ask for the right asset:

• Contract — when the behavior should become executable API truth and project into specs, docs, reports, and agent context.
• Workflow — when multiple contract cases form one durable lifecycle promise.
• Raw test() — when you need full TypeScript freedom for diagnostics, custom setup, migration slices, or behavior that does not fit the contract model.

Real example: GitHub repos as a raw test()

Inside a Glubean project, open your AI assistant and type:

please create github repo list tests in the explore folder

That’s it. The AI reads package.json, the SDK types, and your project layout, then generates a working test file:

import { configure, test } from "@glubean/sdk";
 
const { http: github } = configure({
  http: {
    prefixUrl: "https://api.github.com",
    headers: {
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      Authorization: "Bearer {{GITHUB_TOKEN}}",
    },
  },
});
 
export const listUserRepos = test(
  { id: "github-list-repos", name: "GET GitHub List Repos", tags: ["explore"] },
  async (ctx) => {
    const username = ctx.vars.require("GITHUB_USERNAME");
    const res = await github.get(`users/${username}/repos`, {
      searchParams: { per_page: "5", sort: "updated" },
    });
    const data = await res.json<unknown>();
 
    ctx.expect(res).toHaveStatus(200);
    ctx.assert(Array.isArray(data), "GitHub response should be an array", {
      actual: Array.isArray(data) ? "array" : typeof data,
      expected: "array",
    });
    const repos = data as Array<Record<string, unknown>>;
    ctx.expect(repos.length).toBeGreaterThan(0);
 
    const summary = repos.map((repo) => ({
      name: repo.name,
      stars: repo.stargazers_count,
      language: repo.language,
      updated_at: repo.updated_at,
    }));
 
    ctx.log("Repos", summary);
  },
);

Click ▶ in the gutter. Done.

Notice what the AI figured out on its own — no hand-holding needed:

• configure() for a shared GitHub HTTP client
• ctx.vars.require("GITHUB_USERNAME") for runtime config
• {{GITHUB_TOKEN}} for a secret stored outside source
• Proper GitHub API headers and versioning
• Status + type + length assertions
• Structured logging with ctx.log

Try it with any API

The prompt doesn’t need to be fancy. Just say what you want:

• “create tests for the JSONPlaceholder API — create a post, fetch it, delete it”
• “test the OpenWeatherMap current weather endpoint”
• “hit the Stripe prices list API, use secrets for the key”
• “test HackerNews — fetch top 5 story IDs, then fetch each title”

And if you have any document that describes your API — a markdown file, a plain text spec, a JSON example, internal wiki notes, even a Slack message with endpoints listed — just drop it into the project and point the AI at it. There’s no required format. If it describes request structure, AI can turn it into the right Glubean asset: a contract, workflow, or raw test().

Multi-step workflows

For API flows that span multiple calls — create, verify, update, cleanup — ask for a workflow() when the flow is durable business behavior composed from contract cases.

When you need custom runtime logic instead, ask for a builder-style raw test():

create a checkout builder-style test: create a cart, add an item, complete checkout, then clean up

The AI generates a step chain:

import { test } from "@glubean/sdk";
import { http } from "./configure.ts";
 
export const checkout = test("checkout-flow")
  .meta({ tags: ["e2e"] })
  .step("create cart", async ({ expect }) => {
    const cart = await http.post("carts").json<{ id: string }>();
    expect(cart.id).toBeDefined();
    return { cartId: cart.id };
  })
  .step("add item", async ({ expect }, { cartId }) => {
    await http.post(`carts/${cartId}/items`, {
      json: { productId: "product-123" },
    });
    const cart = await http.get(`carts/${cartId}`).json<{ items: unknown[] }>();
    expect(cart.items).toHaveLength(1);
    return { cartId };
  })
  .step("checkout", async ({ expect }, { cartId }) => {
    const order = await http
      .post(`carts/${cartId}/checkout`)
      .json<{ status: string }>();
    expect(order.status).toBe("completed");
    return { cartId };
  })
  .teardown(async (_ctx, state) => {
    if (state?.cartId) await http.delete(`carts/${state.cartId}`);
  });

Each step receives state from the previous step, and .teardown() runs even if a step fails, so temporary test data has an explicit cleanup path.

The raw test() API is still the full TypeScript escape hatch. Contracts and workflows sit on top of the same execution model, but add structure when the behavior should become a reusable product asset.

Level up: add context for better results

The examples above use a short prompt once a Glubean project exists. For your own APIs, adding context dramatically improves accuracy:

• API source code in the same workspace — the best context is the actual implementation. Put your test project alongside your API repo in the same VS Code workspace and AI can read routes, handlers, validation rules, and response shapes directly from source. This beats any spec because source code is always up to date
• OpenAPI spec in context/ — when you can’t share source code, an OpenAPI spec is the next best option. AI knows your routes and response shapes, though specs can drift from reality
• Skill + MCP (set up above) — AI follows your conventions, runs tests, and fixes failures in the same chat turn
• Skill references (bundled with glubean/skill) — AI reads SDK patterns and uses advanced features like test.pick, configure(), and auth helpers

With all three, generated tests typically run on first try instead of needing 2-3 rounds of manual fixes.

From exploration to CI

When you’re using an optional explore/ draft lane and you’re happy with a test:

1. Move the file from explore/ to tests/.
2. Add deeper assertions or schema validation if needed.
3. Run in CI with npm test, npx glubean ci run, or your project’s package script — same file, zero migration.

The file you explored with today catches regressions in CI tomorrow.

AI Closed-Loop in Action

Here’s what the full loop looks like in practice — one chat session, no manual editing:

1. You: “/glubean write a smoke contract for the users API”
2. AI reads the Glubean skill and your project layout, writes a contract, workflow, or raw test with configure(), assertions, and proper environment variables.
3. AI calls MCP glubean_run_local_file — executes the test and gets a structured result back.
4. Result: 1 failed — expected 200, got 401.
5. AI reads the failure, recognizes the auth issue, and adds an Authorization header through configure() using a {{API_TOKEN}} placeholder.
6. AI reruns via MCP — result: 1 passed.
7. AI: “Done. Test passes against staging. Want me to add boundary tests for 404 and 422?”

No copy-pasting error messages. No switching between terminal and editor. The AI reads structured results, understands what went wrong, and fixes it — all in one conversation turn.

What’s next?

• Quick Start — install the extension and create your first project
• Migrate from Postman / OpenAPI — convert existing collections with AI
• Writing Tests — snippets and data-driven patterns for manual authoring