Testing Nexus State
Test Nexus State stores, subscriptions, and lifecycle behavior.
Nexus State has four useful testing layers.
1. Application Unit Tests
For general createMockNexus() setup and React provider examples, see the
application testing guide. This page covers the parts
specific to Nexus State.
For Nexus State app code, prefer registering the real provider from createNexusStore(...) with a shared createStoreToken<Store>(...) token instead of hand-writing wire service objects:
const mock = createMockNexus();
const { provider, store } = createNexusStore(counterStore, creator, {
snapshot: (local) => ({ count: local.count }),
expose: ["increment"],
});
mock.nexus.configure({
providers: [provider],
endpoint: {
meta: { context: "background" },
},
});
const remote = await connectNexusStore(mock.nexus, counterStore, {
target: { context: "background" },
});
expect(store.getState()).toEqual(remote.getState());This verifies application collaboration with the store service contract. It does not verify real cross-runtime message delivery, browser extension behavior, disconnect timing, or adapter lifecycle semantics.
2. Store Runtime Tests
Use focused Nexus State runtime tests when you want to verify:
- host runtime behavior
- version ordering
- handshake semantics
- disconnect classification
- action acknowledgement behavior
- fixed publication windows and bounded pending snapshots
- explicit snapshot projections and action allowlists
- source-store survival after binding destruction
Current examples live in:
packages/core/src/state/bind-store.test.tspackages/core/src/state/bind-store.creation.test.tspackages/core/src/state/bind-store.actions.test.tspackages/core/src/state/connect-store.test.tspackages/core/src/state/remote-store.test.tspackages/core/src/state/protocol.test.tspackages/core/src/state/errors.test.ts
3. React Binding Tests
Use React tests when you want to verify:
- remote store scope wiring
useRemoteStore()acquisition and cleanup semantics- explicit lifecycle selection through
useStoreStatus/Scope.useStatus reconnectKeychanges and stablereconnect()commands- disposal of a pending acquisition that resolves after a newer request
- scope sharing, including shared reconnect controls
- selector fallback behavior
- fallback plus an acquisition error and null status after a failed replacement
- fallback during cross-target handoff until the replacement is ready
- unchanged data/status selections and actions-only consumers do not rerender on snapshots
Current examples live in:
packages/react/src/react.test.tsxpackages/react/src/create-remote-store-scope.test.tsxpackages/react/src/use-store-status.test.tsxpackages/react/integration/react.integration.test.tsxfor real handles consumed by Zustandpackages/react/integration/render-isolation.integration.test.tsxfor render counts across separate publications and disconnect
4. Multi-Context Integration Tests
This is the most important level for Nexus State cross-context correctness.
Use integration tests when you need to prove:
- one context hosts the store
- multiple isolated contexts connect to it
- updates fan out correctly
- a disconnected context stops receiving updates
- host-side cleanup removes remote resources and subscriptions left by disconnected clients
- reconnect paths create new
RemoteStorehandles instead of reusing terminal handles - connection session changes require a new
RemoteStorehandle
Use React binding tests for hook replacement behavior. Use real multi-context integration tests for restart, transport, and connection session behavior.
Current examples live in:
packages/core/integration/state/lifecycle-and-cleanup.integration.test.tspackages/core/integration/state/background-restart.integration.test.tspackages/core/integration/state/protocol-and-errors.integration.test.tspackages/core/integration/state/targeting-and-handoff.integration.test.tspackages/core/integration/state/callback-lifecycle.integration.test.ts
A Small Example Test
For app-level Nexus State testing, the most useful assertion pattern is usually:
const remote = await connectNexusStore(nexus, counterStore, options);
expect(remote.getState().count).toBe(0);
await remote.actions.increment(1);
expect(remote.getState().count).toBe(1);
expect(remote.getStatus().type).toBe("ready");Then add the failure-mode assertion you care about, for example:
await expect(remote.actions.increment(1)).rejects.toMatchObject({
name: "NexusStoreDisconnectedError",
});This is one common failure assertion, not the only one. Depending on the path you are testing, you may also assert protocol-oriented or connect-oriented errors.
Recommended Strategy
When adding new Nexus State behavior:
- start with
createMockNexus()when the behavior only needs a Nexus API seam - add a focused state/runtime test when behavior depends on state internals
- add a React test if the behavior affects hooks
- add or extend multi-context integration tests only for user-visible cross-context semantics
Good Integration Questions
Ask questions like:
- Does every connected client converge to the same state?
- Does a disconnected client stop receiving snapshots?
- Do surviving clients continue to progress after one context is torn down?
- Does the disconnected handle reject actions explicitly?
- After session replacement, does the app rebuild with a new handle instead of relying on silent healing?
Those questions are more valuable than testing internal bookkeeping alone.