API reference

Docs versioning follows create-pleyn (the product entrypoint).

Package	Version
create-pleyn	0.1.0
htmx-contract	0.1.0

Public entry points of htmx-contract@0.1.0.

Import	Module
htmx-contract	./index.ts
htmx-contract/fixtures	./fixtures.ts
htmx-contract/inspect	./inspect.ts
htmx-contract/poll	./poll.ts
htmx-contract/rules	./rules.ts
htmx-contract/swap	./swap.ts

Primary entry (htmx-contract)

Symbol	Role
checkDocument(html, options?)	Is this rendered page self-consistent?
checkResponse(options)	Would this response, swapped into that page, do damage?
swapAndCheck(options)	Apply the modelled swap and return { html, violations }.
formatViolations(violations)	Human-readable violation text for test failures.
RULES	The rule list (also the docs sync source).

Assert on the DOM after the swap, not on the response body. The response body is not what the user ends up looking at.

Signatures

checkDocument(
  html: string,
  options?: { fragment?: boolean; knownIds?: Iterable<string> },
): Promise<Violation[]>

checkResponse(options: ResponseOptions): Promise<Violation[]>

swapAndCheck(options: ResponseOptions): Promise<SwapResult & { violations: Violation[] }>

formatViolations(violations: readonly Violation[]): string

ResponseOptions extends the swap input:

{
  page: string;
  response: string;
  headers?: Headers | Record<string, string>;
  status?: number;
  target?: string | null;
  swap?: string;           // default innerHTML
  allowErrorSwap?: boolean; // default true — matches apps that swap 4xx toasts
  knownIds?: Iterable<string>;
}

SwapResult: { html, swap, target, swapped, remainder }.

Subpath exports

Import	What you get
htmx-contract/swap	applySwap, MODELLED
htmx-contract/inspect	inspect, attributeOf, innerHtmlOf, outerHtmlOf, rootElement, withoutOob, BOUNDED_POLL_ATTR, …
htmx-contract/rules	RULES and the individual rule functions
htmx-contract/poll	pollAttributes(options), readAttempt(value)
htmx-contract/fixtures	Regression markup constants — see Fixtures

applySwap

Same options as checkResponse (minus knownIds). Returns the page after the modelled swap. Prefer swapAndCheck in tests so violations and the resulting DOM travel together.

inspect helpers

inspect(html) → a Snapshot (ids, fields, polls, OOB nodes, hx elements). attributeOf / innerHtmlOf / outerHtmlOf pull pieces out for assertions without a browser. withoutOob strips OOB nodes the way htmx does before the main swap.

pollAttributes

pollAttributes({
  url, target, attempt, maxAttempts,
  swap?, everyMs?, attemptParam?,
}): string | null

Returns the attribute string for one more attempt, or null when exhausted so the caller can render a terminal state. See Fixtures and the bounded-poll recipe.

Narrative usage: Usage.