Skip to content

garethpaul/poe-games-procedural-dungeons / .claude/skills/synced-store

synced-store

Verified

Build apps that USE synced-store for real-time multiplayer state. PROACTIVELY load when: designing a new Poe tile's state/schema (even before any file exists), discussing how to hide, gate, or restrict visibility of data to specific users or to the server, writing schema.ts/mutators/*.ts/client-config.ts/backend-config.ts for a Poe tile, using createPoeTileTestHarness, calling store.subscribe/store.mutate, or wiring entry.tsx with setupStore.

references/testing-actions.md

View on GitHub
<!-- owner: jyoung-q -->
# Testing: Actions

Actions are server-only operations that appear on the store client as `store.action.<name>(...)`. Testing them with `createPoeTileTestHarness` works the same as testing mutators — the harness runs the action's server handler in-process.

```typescript
test("execute actions", async () => {
  const harness = createPoeTileTestHarness<MySchema>({
    store: { backendConfig: myBackendConfig },
  });
  const { store } = await harness.createClient({ userId: "alice" });

  const result = await store.action.bulkSet({
    items: [
      { key: "a", value: 1 },
      { key: "b", value: 2 },
    ],
  });

  expect(result.count).toBe(2);

  harness.dispose();
});
```

## Awaiting Mutators That Enqueue Actions

When a mutator calls `ctx.enqueueAction("foo", input)` to fire follow-up
work after commit (e.g. a state-machine `setReady` mutator that enqueues
`tryAdvancePhase` once everyone is ready), tests can't observe the action's
effects by simply awaiting the mutator's `confirmed` promise — `enqueueAction`
runs the handler **after** the mutation commits, in a separate task, and the
public test harness has no API to wait for that queue to drain.

**Don't** use `setTimeout` / `setImmediate` / `sleep` to "wait long enough" —
the test lint rules flag them, and `tick()` (which is the recommended
substitute) only yields one event-loop turn, so it can't reliably drain
the multi-hop `enqueueAction → action → mutator` chain either. Reach
for the deterministic `store.action.<name>(...)` call below instead.

**Do** call the action directly via `store.action.<name>(input)` after the
mutator. Actions are idempotent gate-checks by convention (read state, decide
whether to advance, no-op if conditions aren't met), so calling them in a test
is safe and produces the same observable effect as the production
`enqueueAction` path. The action call returns when the action and any
mutators it dispatches have been processed:

```typescript
// Production code (mutator):
//   setReady: async (ctx, input) => {
//     await ctx.table("players").set({ itemKey: ctx.userId, value: { ready: input.ready } });
//     ctx.enqueueAction("tryAdvancePhase", {});  // fire-and-forget after commit
//   }
//
// Production action `tryAdvancePhase` reads the players table and, if all are
// ready, calls a mutator that flips the phase.

// Test:
type TileStoreClient = InferSyncedStoreClient<TileSchema>;

async function readyAndAdvance(store: TileStoreClient): Promise<void> {
  await (await store.mutate.setReady({ ready: true })).confirmed;
  await store.action.tryAdvancePhase({});  // waits for action + dispatched mutators
}

test("two players ready -> phase advances", async () => {
  const harness = createPoeTileTestHarness<TileSchema>({
    store: { backendConfig: tileBackendConfig },
  });
  const { store: alice } = await harness.createClient({ userId: "alice" });
  const { store: bob } = await harness.createClient({ userId: "bob" });

  await readyAndAdvance(alice);
  expect(await alice.query((tx) => tx.table("game").get("phase"))).toBe("lobby");

  await readyAndAdvance(bob);
  expect(await alice.query((tx) => tx.table("game").get("phase"))).toBe("playing");
});
```

The action runs the same handler in-process whether triggered by `enqueueAction`
in production or by `store.action.X(...)` in a test. As long as the action
guards on phase/precondition checks and is safe to call multiple times, this
gives you a deterministic test without any sleep/poll/flakiness.

## Actions That Call Platform Services

If your action or discouraged idempotent/read-only guarded server-side mutator calls [platform capabilities](platform.md), wire a mock platform caller:

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

const harness = createPoeTileTestHarness<MySchema>({
  store: {
    backendConfig: myBackendConfig,
    createPlatformCaller: () => createMockPlatformCaller(),
  },
});
```

The mock returns deterministic responses for all platform calls — no real API keys, no network.

## Cached/Empty State Before Server Data Arrives

Use `createControlledClient()` when you need to observe the client before the initial server pull completes — useful for testing cold-start UI states:

```typescript
test("test cached state before server data", async () => {
  const { store, transport } = await harness.createControlledClient();

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

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

  // Server data has arrived — assert on synced state
});
```

See [testing-network-control.md](testing-network-control.md) for the full controlled-client API.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall