Testing

The SDK ships an in-process Hono mock that mirrors the production lens, plus pre-baked vitest suites and zod schemas as the single source of truth. Boot the mock, run the suites, get a 30-second feedback loop: no live API, no shared state.

Why a test harness

Agents (and humans) need to know in seconds whether an edit broke the SDK / backend contract. Hitting api.cimplify.io from CI is too slow, too flaky, and too leaky. The SDK's mock is the oracle: it's implemented from the same shape contracts as the production lens (~99% parity) and runs in the same process as your tests.

The three suites

Suite	Catches	Runtime
`createBrandSuite`	Missing fields, placeholder copy, invalid email/locale/currency, seed mismatch	< 2 s
`createCartFlowSuite`	SDK / mock contract drift, add/dedupe/remove regressions	~ 5 s
`createContractSuite`	Outbound payload schema, inbound response schema, checkout shape	~ 3 s

Three-line tests

Templates wire each suite in three lines so the SDK owns the cases. When a new contract test ships, every storefront inherits it on bun update @cimplify/sdk.

__tests__/cart-flow.test.ts

import { createCartFlowSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";

createCartFlowSuite({ seed: brand.mock.seed, businessId: brand.mock.businessId });

Run it

bun run check          # typecheck + lint + all three suites (~15 s)
bun run check:brand    # the brand suite alone
bun run check:cart     # cart-flow alone
bun run check:contract # contract alone

What gets validated

Outbound: every cart.addItem body is safeParsed against AddItemPayloadSchema. Missing variant_id, naked productId, etc. fail the test with a precise field path.
Inbound: every cart response is assertCarted. display_attributes, malformed money, and missing pricing fields surface as structured issues.
Checkout: CheckoutResponseSchema verifies bill_token, order_id, optional client_secret, next_action.
Brand: BrandSchema covers identity, contact, hero, FAQ, policies, account copy, mock pairing.

Where each piece lives

Import	For
`@cimplify/sdk/testing`	Schemas, `assertX` helpers, `createTestClient`, fixtures
`@cimplify/sdk/testing/suite`	The three pre-baked vitest suites
`@cimplify/sdk/testing/msw`	MSW handlers wrapping the same mock; for component tests
`@cimplify/sdk/mock`	Programmatic mock for your own tooling

Test client createTestClient + fixtures
Suites Brand, cart-flow, contract
Schemas The zod registry and SchemaViolationError
MSW Same mock, MSW transport