Core Concepts
Glubean connects source-authored API promises to team-readable evidence.
Verification project
A Glubean project is usually a dedicated verification project: a Node workspace whose job is to test real services from the outside.
This is different from app-local unit testing. Vite, Jest, and Vitest usually live inside the application repo and test functions, components, or modules. Glubean tests usually call running HTTP services, browser flows, contracts, and load plans. They need their own environments, secrets, upload settings, target IDs, contract projections, and CI gates.
That separation is heavier than dropping a unit test into an app repo, but it is worth it when the goal is end-to-end API evidence that developers, agents, QA, product, and support can all read.
Contract
A contract describes what an API promises, and the runnable contract case is
itself a test. In code, contracts are protocol adapters under the shared
contract.* model, not only HTTP.
Today, the built-in contract surfaces include:
contract.http.with()for HTTP endpoint promisescontract.browser.with()for browser journeys that should be replayable, reviewable, and tied to API evidence
The plugin system can add more contract protocols. First-party plugins already cover GraphQL and gRPC, and teams can add their own protocol adapters when their domain needs a different contract shape.
Use contracts when the promise should be both checked at runtime and projected for humans. Contracts can also be deferred, deprecated, projected into OpenAPI or other protocol-shaped docs, and linked to the runs that prove or break them. In the webapp, synced contracts appear as Specifications.
Run
A run is one execution of Glubean work: functional tests, contracts, browser checks, or load plans. Runs happen locally or in CI. When uploaded, they become Cloud evidence.
Target
A Target is where uploaded runs accumulate. It represents a system under test, such as staging, production, or a service implementation. Targets show health, history, failures, endpoint trends, and performance.
Evidence
Evidence is the structured output of a run: requests, responses, assertions, steps, traces, metrics, artifacts, and load data. Glubean keeps this structured so humans and agents can inspect it without guessing from raw logs.
The authoring model
Glubean has several primitives because API verification has several jobs.
| Primitive | What it means | Best for |
|---|---|---|
test() | A raw TypeScript runtime check. | One-off behavior, setup/teardown, diagnostics, browser-adjacent flows, or checks that do not need projection. |
contract.http.with() | An executable HTTP endpoint promise. | Method/path/status/schema/business-rule promises that run as tests and become Specifications/docs. |
contract.browser.with() | An executable browser journey promise. | Login, checkout, dashboard, or other UI journeys that need replayable browser evidence. |
workflow() | A lifecycle across contract cases. | Multi-step promises such as signup, checkout, webhook delivery, retry, or cancellation. |
loadScenario() | A concurrency workload. | p95, throughput, error rate, and SLA gates under pressure. |
| Contract plugins | More protocol adapters. | GraphQL, gRPC, or team-defined protocols that should join the same contract/evidence model. |
Contracts are built on the same runner and evidence model as test(). Use
contract.* when the behavior should be easy to review, project, and join to
future runs. Use test() directly when raw TypeScript is the clearest way to
produce honest runtime evidence.
Specification
A Specification is the webapp view of synced contracts. It is the primary path when API truth is authored in the repo.
API and Portal
An API is the webapp’s writer-facing document layer: an OpenAPI base plus an overlay for prose, examples, naming, grouping, and publishing state. The base can come from a Specification projection, an imported OpenAPI document, or early design work in the browser.
A Portal publishes APIs and shared pages for readers. Use Portals when the same API knowledge needs to become a stable human-facing site for customers, partners, QA, support, or internal teams.
Explore
Explore is where non-developers and agents can send requests, build flows, and validate responses against contracts from the browser.
Agent
Glubean uses “agent” in two ways.
Your IDE coding agent is the agent you choose in Cursor, Claude Code, Codex, or another local tool. It works with source code, the Glubean skill, MCP, the CLI, and your verification project.
The Glubean webapp Agent is built into the webapp. It reads the current page and the structured data behind it: Targets, runs, failures, Specifications, Explore requests, APIs, Portals, reports, and performance history. It is for explaining the current surface, helping non-developers debug, assisting writing, drafting test ideas from webapp context, and interpreting failures.
When the task requires source context, use the IDE plane. When the task starts from Cloud evidence or a webapp view, use the webapp Agent.