Unit Tests

This guide explains how to test Poe apps using createPoeAppTestHarness. The harness creates multi-client test scenarios using the child app architecture — each createClient() call exercises the full production code path (AppsKernel → HostKernelRpc → nonce routing → PostMessageEnvironment → createPoe).

Basic Setup — Store Tests

import { test, expect } from "bun:test";
import { createPoeAppTestHarness } from "poe-tiles-sdk/v1/test-utils.js";
import { myBackendConfig } from "./synced-store/backend-config";
import type { MySchema } from "./synced-store/schema";

test("mutation round-trip", async () => {
  const harness = createPoeAppTestHarness<MySchema>({
    store: { backendConfig: myBackendConfig },
  });
  const { store } = await harness.createClient({ userId: "alice" });

  const { confirmed } = await store.mutate.setValue({
    key: "greeting",
    value: "hello",
  });
  await confirmed;

  const result = await store.query((tx) => tx.table("data").get("greeting"));
  expect(result).toBe("hello");

  harness.dispose();
});

createClient() returns { Poe, store, dispose } where Poe is the full production API and store is the typed SyncedStoreClient (already synced with server data).

Basic Setup — Bot Streaming Tests

import { test, expect } from "bun:test";
import {
  createPoeAppTestHarness,
  textResponses,
} from "poe-tiles-sdk/v1/test-utils.js";

test("stream bot response", async () => {
  const harness = createPoeAppTestHarness({
    getBotResponse: textResponses(["Hello ", "World!"]),
  });
  const { Poe } = await harness.createClient();

  const chunks = [];
  for await (const chunk of Poe.stream({
    botName: "Claude-3.5-Sonnet",
    prompts: "Hi",
  })) {
    chunks.push(chunk);
  }

  expect(chunks).toHaveLength(2);
  expect(chunks[0].text).toBe("Hello ");
  expect(chunks[1].text).toBe("World!");

  harness.dispose();
});

Multi-Client Testing

Multiple clients can share the same store instance.

Simple case: second client created after the first mutation

test("multi-user sync", async () => {
  const harness = createPoeAppTestHarness<MySchema>({
    store: { backendConfig: myBackendConfig },
  });

  const alice = await harness.createClient({ userId: "alice" });
  await alice.store.mutate.setValue({ key: "k1", value: "from alice" });

  // bob's bootstrap pull picks up alice's mutation automatically.
  const bob = await harness.createClient({ userId: "bob" });
  const result = await bob.store.query((tx) => tx.table("data").get("k1"));
  expect(result).toBe("from alice");

  harness.dispose();
});

Pre-existing clients with sequential mutations: use waitFor*

If both clients exist before the mutations and you need them to observe each other's state in order, the second client's optimistic pass races the first client's server confirmation. Use one of the waitFor* helpers from poe-tiles-sdk/v1/test-utils.js to gate on the propagated state:

Helper	Use when
waitForKeyExists(client, { table, key })	A row needs to appear before the next step
waitForValue(client, { table, key, value })	A row needs to deep-equal a specific value
waitForKeyMatch(client, { table, key, match })	A row needs to satisfy a predicate (most flexible)
waitForKeyDeleted(client, { table, key })	A row needs to disappear
waitForAllClients([...], { queryFn })	Multiple clients need to converge to the same truthy state
waitFor(client, { queryFn })	A general query needs to return truthy

Each takes an optional { timeoutMs, description } and emits a descriptive timeout error on failure. Source: packages/synced-store-client/test-utils/wait-for.ts.

import {
  createPoeAppTestHarness,
  waitForKeyExists,
  waitForKeyMatch,
} from "poe-tiles-sdk/v1/test-utils.js";

test("two pre-existing clients merge edits", async () => {
  const harness = createPoeAppTestHarness<MySchema>({
    store: { backendConfig: myBackendConfig },
  });

  const { store: alice } = await harness.createClient({ userId: "alice" });
  const { store: bob } = await harness.createClient({ userId: "bob" });

  await alice.mutate.setTodo({ id: "t1", text: "Buy milk", completed: false });

  // biome-ignore lint/suspicious/noExplicitAny: waitFor* generic constraints reject schema-inferred store types
  await waitForKeyExists(bob as any, { table: "items", key: "t1" });

  await bob.mutate.setTodo({ id: "t1", completed: true });

  // biome-ignore lint/suspicious/noExplicitAny: waitFor* generic constraints reject schema-inferred store types
  await waitForKeyMatch(alice as any, {
    table: "items",
    key: "t1",
    match: (t) => (t as { completed: boolean }).completed === true,
  });

  expect(await alice.query((tx) => tx.table("items").get("t1"))).toMatchObject({
    text: "Buy milk",
    completed: true,
    createdBy: "alice",
  });

  harness.dispose();
});

Don't hand-roll a await { confirmed } = mutate.X(); await confirmed; await waitForServerData() pattern — it lacks the timeout/description infrastructure these helpers provide, and the pattern doesn't generalize to predicate-based waits.

Happy-dom UI tests: never setTimeout(resolve, N) to wait for propagation

Don't paper over UI propagation timing with a hardcoded await new Promise(r => setTimeout(r, 50)) — slow CI, GC pauses, or any scheduler hiccup turns a 50ms cushion into a flake. Bundles also lint-fail on setTimeout in tests.

Use waitFor* from poe-tiles-sdk/v1/test-utils.js. waitFor* is subscription-based, not polling-based — internally it does both a client.subscribe(queryFn, ...) AND an immediate client.query(queryFn) so the predicate gets a synchronous first look at current state. There's still a UI-side gotcha to know about:

• Subscribe's "initial fire" is async (microtask), not synchronous. mountApp(root, store) returns before its registered subscribe has invoked its callback. If the data the UI needs is already in the store, waitFor's immediate client.query can resolve waitFor before mountApp's subscribe callback has had a chance to update the DOM. Asserting on the DOM right after await waitFor(...) then races.
• Fix: force a real store change after mounting so both subscribes fire in order. Issue a no-op mutation, then waitFor on a predicate that combines store state AND the DOM. Total wait is bounded by the mutation roundtrip — no setTimeout.

import { waitFor } from "poe-tiles-sdk/v1/test-utils.js";

const root = document.createElement("div");
mountApp(root, store);

// Force a store change so mountApp's subscribe fires AFTER the test's
// subscribe is set up. Pick any cheap mutation already in your schema
// (e.g. re-record the current score) — the goal is propagation, not a
// real state change.
await (await store.mutate.someCheapMutation({})).confirmed;

// biome-ignore lint/suspicious/noExplicitAny: waitFor's generic constraints reject schema-inferred store types
await waitFor(store as any, {
  queryFn: async (tx) => {
    const row = (await tx.table("players").get("alice")) as
      | { bestScore: number }
      | undefined;
    return (
      row?.bestScore === 11 &&
      root.querySelector("#best")?.textContent === "11"
    );
  },
  description: "HUD #best to reflect alice's bestScore=11",
});

If your app has no convenient cheap mutation, add one — the cost is one mutation per UI test, the gain is a bounded, deterministic wait.

Vitest browser mode: when happy-dom can't fake the web API

happy-dom is fine for DOM, layout, and timers, but it has no WebGL, no OffscreenCanvas, no AudioWorklet, and other web APIs that the in-memory harness can't reliably stub. For those, run the same UI flow in real Chromium via Vitest browser mode and connect each client to a real TestServer (HTTP + WebSocket) via createPoeAppBrowserTestHarness.

// vitest.browser.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({
  test: {
    include: ["ui/**/*.test.browser.{ts,tsx}"],
    globalSetup: ["./tests/global-setup.browser.ts"],
    browser: {
      enabled: true,
      provider: "playwright",
      instances: [{ browser: "chromium" }],
      headless: true,
    },
    coverage: {
      enabled: true,
      provider: "v8",
      reporter: ["lcov"],
      reportsDirectory: "./coverage/browser",
    },
  },
});

// tests/global-setup.browser.ts — starts TestServer once, exposes ports
import { TestServer } from "poe-tiles-sdk/v1/test-utils/playwright.js";
import type { TestProject } from "vitest/node";

declare module "vitest" {
  export interface ProvidedContext {
    syncPort: number;
    appTypeId: string;
  }
}

export default async function setup(project: TestProject) {
  const server = new TestServer();
  await server.start();
  await server.registerApp({
    typeId: "my-app",
    content: { type: "directory", dir: "./dist" },
  });
  project.provide("syncPort", server.syncPort);
  project.provide("appTypeId", "my-app");
  return () => server.close();
}

// ui/App.test.browser.tsx
import { afterEach, beforeEach, describe, expect, test, inject } from "vitest";
import { createPoeAppBrowserTestHarness } from "poe-tiles-sdk/v1/test-utils/browser.js";
import { appMutators } from "../client";
import { mountApp } from "./App";

describe("real WebGL", () => {
  let harness: ReturnType<typeof createPoeAppBrowserTestHarness>;
  beforeEach(() => {
    harness = createPoeAppBrowserTestHarness({
      storeTypeId: inject("appTypeId"),
      instanceId: `test-${crypto.randomUUID()}`,
      syncWsUrl: `ws://localhost:${inject("syncPort")}`,
      mutators: appMutators,
      schemaVersion: 1, // match your app's schemaVersion
    });
  });
  afterEach(() => harness.dispose());

  test("renders scene graph", async () => {
    const { store } = await harness.createClient({ userId: "alice" });
    const root = document.createElement("div");
    document.body.appendChild(root);
    const game = mountApp(root, store);
    // Drive store.mutate / store.query, assert against scene-graph debug, etc.
    game?.stop();
  });
});

When to reach for it:

• Real WebGL / Three.js scene-graph assertions (happy-dom returns null from getContext("webgl")).
• Audio / OffscreenCanvas / clipboard / pointer-capture flows.
• Anywhere a fake DOM diverges from real browser behavior in a way that hides bugs.

Otherwise prefer the in-memory + happy-dom harness — it runs in ~50 ms per test vs ~1.5 s for browser mode. Only use browser-mode coverage where the real API is the point. Add new browser tests under *.test.browser.tsx so they don't run under bun test. See e2e-tests.md for the TestServer API reference.

Response Helpers

The harness provides convenience helpers for common bot response patterns:

Helper	Description
textResponse("Hello")	Single text event
textResponses(["a", "b"])	Multiple text events
sseResponses([...])	Raw SSEEvent array
sequentialResponses([[...], [...]])	Different responses per call
errorResponse("msg")	Throws an error

Custom Response Handler

For full control, pass an async generator that receives the request params:

const harness = createPoeAppTestHarness({
  getBotResponse: async function* (params) {
    if (params.botName === "Claude") {
      yield { event: "text", data: { text: "I'm Claude" } };
    } else {
      yield { event: "error", data: { text: "Unknown bot" } };
    }
  },
});

Sequential Responses (Tool Loops)

sequentialResponses is useful for testing Poe.call() with tools, where the bot makes a tool call on the first request and gives a final answer on the second:

import { sequentialResponses } from "poe-tiles-sdk/v1/test-utils.js";

test("tool call loop", async () => {
  const harness = createPoeAppTestHarness({
    getBotResponse: sequentialResponses([
      // First call: bot requests a tool
      [
        {
          event: "json",
          data: {
            choices: [{
              delta: {
                tool_calls: [{
                  id: "call_1",
                  function: {
                    name: "get_weather",
                    arguments: '{"city":"Tokyo"}',
                  },
                }],
              },
            }],
          },
        },
      ],
      // Second call: bot gives final answer
      [{ event: "text", data: { text: "It's sunny in Tokyo!" } }],
    ]),
  });
  const { Poe } = await harness.createClient();

  const weatherTool = Poe.createTool({
    name: "get_weather",
    description: "Get weather",
    parameters: {
      type: "object",
      properties: { city: { type: "string" } },
    },
    run: async (input) => `Weather in ${input.city}: 72F sunny`,
  });

  const events = [];
  for await (const event of Poe.call({
    botName: "bot",
    prompts: "What's the weather in Tokyo?",
    tools: [weatherTool],
  })) {
    events.push(event);
  }

  expect(events.filter((e) => e.type === "tool_call")).toHaveLength(1);
  expect(events.filter((e) => e.type === "tool_result")).toHaveLength(1);
});

Request Capture

Every bot query, model list, and app list request is captured in harness.requests:

for await (const _ of Poe.stream({ botName: "bot", prompts: "Hi" })) {}

expect(harness.requests).toHaveLength(1);
expect(harness.getRequests("getBotResponse")).toHaveLength(1);

Cross-App Testing with otherStores

Use otherStores to register additional store backends for cross-app testing. Each key is a storeTypeId. In your app code, call Poe.externalStore({ storeTypeId, instanceId }) to get a read-only handle for querying another store's data:

test("read from external store", async () => {
  const harness = createPoeAppTestHarness({
    store: {
      storeTypeId: "chat",
      backendConfig: { mutators: chatMutators },
    },
    otherStores: {
      manager: {
        backendConfig: { mutators: managerMutators },
      },
    },
  });
  const { Poe, store } = await harness.createClient();

  // Mutations can trigger ctx.mutateExternal() to write to other stores
  await store.mutate.sendMessage({ id: "msg-1", text: "hello" });

  // Read from the external store
  const external = Poe.externalStore({
    storeTypeId: "manager",
    instanceId: "test-instance",
  });
  await external.waitForBootstrap();
  // Query the external store's data (read-only)...

  harness.dispose();
});

Controlled Flush (Cache Testing)

Use createControlledClient() to control when server data arrives — useful for testing cached data behavior:

const { store, transport } = await harness.createControlledClient();

// Store is set up but NOT synced — server data hasn't arrived
// Do assertions on cached/empty state here...

// Now flush to let server data through
await transport.flushUntil(store.waitForServerData());

// Server data has arrived

Swapping Handlers Mid-Test

All handlers can be replaced at any point:

harness.setBotResponseHandler(textResponse("new response"));
harness.setListModelsData([createTestModel({ id: "claude-4" })]);
harness.setListAppsData([{ id: "app-1", handle: "my-app", ... }]);
harness.setPlatformCaller(() => createMockPlatformCaller({ ... }));

Options Reference

createPoeAppTestHarness Options

Option	Default	Description
apiHarness	new ApiTestServer()	IApiTestHarness instance — override with a custom implementation
getBotResponse	Empty text response	Bot response handler (async generator)
store	—	Omit to skip store. { backendConfig: { mutators: {} } } for defaults.
store.storeTypeId	"test"	Store type ID for registration
store.backendConfig	(required)	Server-side backend config (mutators, actions, schema)
otherStores	—	Additional store backends keyed by storeTypeId for cross-app testing
listModels	[]	Initial models for Poe.listModels()
listApps	[]	Initial apps for Poe.tiles.list() and Poe.tiles.get()
openProps	null	JSON data for Poe.getOpenProps()
createPlatformCaller	Mock	Custom platform caller factory for actions

createClient() Result

Property	Description
Poe	Full production Poe API (stream, call, listModels, etc.)
store	Typed SyncedStoreClient (already synced with server data)
dispose()	Clean up this client's resources

createControlledClient() Result

Same as createClient() plus:

Property	Description
transport	QueuedTransport for manual flush control

Harness Methods

Method	Description
harness.createClient(opts?)	Create a connected client with server data loaded
harness.createControlledClient(opts?)	Create a client with manual flush control
harness.removeUser({ userId, removedBy? })	Fire the onRemoveUser system mutator on the test backend (default removedBy: "system"). Useful for testing mid-game disconnect flows that client.dispose() doesn't exercise.
harness.setBotResponseHandler(handler)	Replace bot response handler
harness.setListModelsData(models)	Replace models list
harness.setListAppsData(apps)	Replace apps list
harness.setPlatformCaller(factory)	Replace platform caller factory
harness.requests	All captured requests
harness.getRequests(method)	Filter captured requests by method
harness.multiAppHarness	The underlying multi-app harness (advanced)
harness.dispose()	Clean up all resources