@cool-ai/beach-a2ui-test

Test utility for packages that build A2UI surfaces. Parses a SurfaceCommand[] stream and exposes a typed view for assertions — no raw message JSON in your tests.

Home: cool-ai.org · Documentation: cool-ai.org/docs

Install

npm install --save-dev @cool-ai/beach-a2ui-test

No peer dependencies. Works with any test framework.

Usage

import { surfaceOf } from '@cool-ai/beach-a2ui-test';
import { productCard } from '@cool-ai/beach-a2ui-patterns';

const cmds = productCard({
  surfaceId: 'order-123',
  title: 'Your Order',
  items: [{ label: 'Flight LHR-FCO', amount: '£299' }],
  total: { label: 'Total', amount: '£299' },
});

const s = surfaceOf(cmds, 'order-123');

s.surfaceId   // 'order-123'
s.catalogId   // 'https://a2ui.org/specification/v0_9/basic_catalog.json'

s.find('Card')              // first Card node in the tree, or undefined
s.findAll('Text')           // every Text node, depth-first
s.toJSON()                  // serialisable snapshot for toMatchSnapshot()

API

surfaceOf(commands, surfaceId?)

Extracts a single surface from a SurfaceCommand[] (or any unknown[]) stream.

• commands — the array returned by a surface builder.
• surfaceId — when provided, selects the surface with that id. When omitted, selects the first surface found.
• Throws if no matching createSurface message exists.

Returns a SurfaceView:

| Member | Description | |---|---| | surfaceId | The id from the createSurface message. | | catalogId | The catalog id from the createSurface message. | | components | The raw components array from the first matching updateComponents message. | | find(type) | Depth-first search for the first component whose component field equals type. Walks children arrays and singular child references. Returns undefined if not found. | | findAll(type) | Collects every matching component across the tree, depth-first. | | toJSON() | Returns { surfaceId, catalogId, components } — suitable for snapshot assertions. |

find and findAll walk inline-nested trees (the format used by pattern helpers). They do not resolve keyed id references.