Skip to Content
OrbixDocs
Block SDK · Guides

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):

src/__tests__/block.test.tsx
// @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

MemberDescription
containerHTMLElement holding the rendered block DOM.
blockIdMounted 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:

src/__tests__/capabilities.test.ts
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:

src/dev.tsx
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,
});

On this page