Test your block
Write fast unit tests with renderBlock and Vitest, verify read-only mode and capabilities, and preview in the standalone dev harness.
@orbixdocs/sdk/testing provides renderBlock, a lightweight test harness for Vitest + jsdom that mounts your BlockDefinition inside a real OrbixBlockInstanceContext, wires default properties and block graph ports, and exposes helpers to inspect state and outputs without launching a browser.
Local installation note
Until @orbixdocs/sdk@3.0.0 is published to the public npm registry, install the local tarball built from packages/sdk (npm run build:sdk && cd packages/sdk && npm pack) in standalone test projects. See Develop and debug.
Unit testing state, ports, and read-only mode
Add // @vitest-environment jsdom at the top of your test file (or set test.environment = 'jsdom' in vite.config.ts):
// @vitest-environment jsdom
import {
defineBlock,
useOrbixState,
useBlockInput,
useBlockOutput,
type BlockRenderProps,
} from '@orbixdocs/sdk';
import { renderBlock } from '@orbixdocs/sdk/testing';
const MultiplierBlock = defineBlock<{ label?: string }>({
manifest: {
id: 'acme.multiplier',
name: 'Multiplier',
version: '1.0.0',
sdk: '^3.0.0',
},
properties: {
label: { type: 'string', default: 'Result' },
},
component(props: BlockRenderProps<{ label?: string }>) {
const [state, setState] = useOrbixState<{ count: number }>(props, { count: 2 });
const factor = useBlockInput<number>('factor', 3);
const total = state.count * factor;
useBlockOutput('total', total);
return (
<div>
<span data-testid="summary">
{props.props?.label}: {total}
</span>
<button
type="button"
disabled={props.isReadOnly}
onClick={() => setState((prev) => ({ count: prev.count + 1 }))}
>
Increment
</button>
</div>
);
},
});
export function runMultiplierAssertions() {
const harness = renderBlock(MultiplierBlock, {
inputs: { factor: 5 },
isReadOnly: false,
});
// 1. Default prop ('Result') + initial count (2) * input factor (5) = 10
console.assert(harness.getOutput('total') === 10);
// 2. Click Increment -> count (3) * 5 = 15
harness.container.querySelector('button')?.click();
console.assert(harness.getOutput('total') === 15);
// 3. Push a new upstream port value -> 3 * 10 = 30
harness.setInput('factor', 10);
console.assert(harness.getOutput('total') === 30);
// 4. Switch to read-only and verify button disables and state cannot mutate
harness.rerender({ isReadOnly: true });
const btn = harness.container.querySelector('button');
console.assert(btn?.disabled === true);
harness.unmount();
}What renderBlock returns
| Member | Description |
|---|---|
container | HTMLElement holding the rendered block DOM. |
blockId | Mounted block instance ID (defaults to a generated test ID unless passed in options). |
getProps() | Returns the latest block.props record after any useOrbixState or onChange updates. |
getOutput(port) | Reads the latest value emitted by useBlockOutput(port, ...) on this block. |
setInput(port, value) | Pushes a new value into useBlockInput(port, ...) and flushes React updates synchronously. |
rerender(next) | Re-renders the same instance with updated { props?, surface?, isReadOnly? }. |
unmount() | Unmounts the React root, unbinds the instance, and runs blockResources disposers. |
Testing capability denials
Remember that Block Studio's Preview grants authorPreview: true, whereas placed document blocks run at the community tier. Use renderBlock (which binds instances with preview: false) or capabilityEngine directly to verify that your manifest.capabilities grants everything your block needs — and that missing capabilities are handled cleanly:
import {
capabilityEngine,
SecurityCapabilityError,
} from '@orbixdocs/sdk';
capabilityEngine.registerManifest('acme.read-only-outline', {
id: 'acme.read-only-outline',
name: 'Read-Only Outline',
version: '1.0.0',
capabilities: {
document: ['read'],
},
});
capabilityEngine.bindInstance('test-inst-1', {
type: 'acme.read-only-outline',
preview: false,
});
// 'read' succeeds
capabilityEngine.verifyDocument('read', 'test-inst-1');
// 'write' throws SecurityCapabilityError with .capability === 'document:write'
try {
capabilityEngine.verifyDocument('write', 'test-inst-1');
} catch (err) {
if (err instanceof SecurityCapabilityError) {
console.assert(err.capability === 'document:write');
}
} finally {
capabilityEngine.unbindInstance('test-inst-1');
}Visual testing with mountBlockDevHarness
To inspect themes, surfaces (block, fullpage, sidebar_panel), read-only mode, and side-by-side team vs personal state in a standalone browser tab, mount your block with mountBlockDevHarness from @orbixdocs/sdk/dev:
import { defineBlock } from '@orbixdocs/sdk';
import { mountBlockDevHarness } from '@orbixdocs/sdk/dev';
const CounterBlock = defineBlock({
manifest: {
id: 'acme.dev-counter',
name: 'Dev Counter',
version: '1.0.0',
sdk: '^3.0.0',
},
component: () => <div>Preview ready</div>,
});
mountBlockDevHarness(CounterBlock, '#root', {
initialTheme: 'obsidian',
initialSurface: 'block',
initialDualCollaborator: true,
initialInspectorOpen: true,
});