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 fornpm 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 / method | Type | Description |
|---|---|---|
container | HTMLElement | Mounted DOM container. |
blockId | string | Active instance ID bound in capabilityEngine. |
getProps() | Record<string, any> | Latest persisted block.props object. |
getOutput(port) | any | Latest value emitted on port by useBlockOutput. |
setInput(port, value) | void | Updates upstream port value and flushes React re-render. |
rerender(next) | void | Updates { props?, surface?, isReadOnly? } on the mounted instance. |
unmount() | void | Unmounts the React root, unbinds capabilityEngine, and runs blockResources.disposeAll(blockId). |
Mock context helpers
resolveBlockDefaultProps(properties, overrides?)— computes initialpropsfrom adefinition.propertiesschema map without mounting React.createMockBlock(overrides?)— returns a plainBaseBlockrecord ({ id, type, content, props }) for low-level unit tests.createMockPages()— returns a sample dictionary ofPageDatarecords (Record<string, PageData>) for document/workspace tests.createMockRuntimeContext(blockOverrides?, onUpdateSpy?)— creates a mockOrbixBlockInstanceContextValueobject for custom React wrapper tests.TestRunnerandexpect— lightweight assertion runner for browser-embedded block self-tests where Vitest is not present.
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 anddark/lightclasses todocument.documentElement.