Skip to Content
OrbixDocs
Block SDK · Reference

Testing API

Reference for @orbixdocs/sdk/testing and @orbixdocs/sdk/dev.

@orbixdocs/sdk ships two development-only subpaths that are excluded from your production block bundle:

  • @orbixdocs/sdk/testing — DOM and headless unit test helpers for Vitest + jsdom.
  • @orbixdocs/sdk/dev — browser mock-host playground for npm run dev.

@orbixdocs/sdk/testing

renderBlock(definition, options?)

Mounts a BlockDefinition inside OrbixBlockInstanceContext, registers its manifest with capabilityEngine (preview: false), resolves default property values from definition.properties, and flushes React updates synchronously.

Prop

Type

Returns RenderBlockResult<TProps>:

Property / methodTypeDescription
containerHTMLElementMounted DOM container.
blockIdstringActive instance ID bound in capabilityEngine.
getProps()Record<string, any>Latest persisted block.props object.
getOutput(port)anyLatest value emitted on port by useBlockOutput.
setInput(port, value)voidUpdates upstream port value and flushes React re-render.
rerender(next)voidUpdates { props?, surface?, isReadOnly? } on the mounted instance.
unmount()voidUnmounts the React root, unbinds capabilityEngine, and runs blockResources.disposeAll(blockId).

Mock context helpers

  • resolveBlockDefaultProps(properties, overrides?) — computes initial props from a definition.properties schema map without mounting React.
  • createMockBlock(overrides?) — returns a plain BaseBlock record ({ id, type, content, props }) for low-level unit tests.
  • createMockPages() — returns a sample dictionary of PageData records (Record<string, PageData>) for document/workspace tests.
  • createMockRuntimeContext(blockOverrides?, onUpdateSpy?) — creates a mock OrbixBlockInstanceContextValue object for custom React wrapper tests.
  • TestRunner and expect — lightweight assertion runner for browser-embedded block self-tests where Vitest is not present.
src/__tests__/mock-helpers.test.tsx
import {
  defineBlock,
  type BlockRenderProps,
} from '@orbixdocs/sdk';
import {
  renderBlock,
  resolveBlockDefaultProps,
  createMockBlock,
  createMockPages,
} from '@orbixdocs/sdk/testing';

const Greeter = defineBlock<{ greeting?: string }>({
  manifest: {
    id: 'acme.greeter',
    name: 'Greeter',
    version: '1.0.0',
    sdk: '^3.0.0',
  },
  properties: {
    greeting: { type: 'string', default: 'Hello' },
  },
  component(props: BlockRenderProps<{ greeting?: string }>) {
    return <div>{props.props?.greeting}</div>;
  },
});

export function verifyTestingHelpers() {
  const defaults = resolveBlockDefaultProps(Greeter.properties);
  console.assert(defaults.greeting === 'Hello');

  const mockBlock = createMockBlock({ type: 'acme.greeter' });
  const pages = createMockPages();
  console.assert(Boolean(mockBlock.id) && Object.keys(pages).length > 0);

  const h = renderBlock(Greeter, { props: { greeting: 'Welcome' } });
  h.unmount();
}

@orbixdocs/sdk/dev

mountBlockDevHarness(definition, rootElement?, options?)

Mounts <BlockDevPlayground> into rootElement (CSS selector string such as '#root' or an HTMLElement; defaults to #root or a newly appended <div>), calls enableStandaloneBlockHarness(true), and returns { root, container, unmount }.

Prop

Type

Additional exports from @orbixdocs/sdk/dev:

  • <BlockDevPlayground definition={...} ... /> — React component form of the playground.
  • PLAYGROUND_THEMES — array of the 4 built-in playground theme presets (obsidian, paper, ivory, frost) and their 9 --orbix-* CSS variables.
  • applyPlaygroundTheme(themeId) — applies a preset's CSS variables and dark/light classes to document.documentElement.

On this page