Skip to content

15. E2E Testing — Verifying the Whole System with a Client

Guide Home | Previous: 14. Picking a Sample — Start with the Example Closest to Your Problem | Next: 16. Options — Setting List And Defaults

View in another language — C#/.NET · C++ · Java · Kotlin · Node/TypeScript

This chapter has no spec document that owns its contract. That's because it covers how to build tests in your own system. What each sample verifies is defined by the common sample document. The connector's formal API surface is owned by the per-language Stream Connector public contract. This chapter covers how to build E2E tests in your own system.

0. Where E2E Testing Is Needed

No matter how tightly you write handler unit tests, some things stay unverified: whether registration actually took effect, whether routing between two nodes is correct, whether a push reaches other participants in the room. These can only be verified by starting real processes and checking over a real connection.

At this point, teams usually implement a separate test-only client, rewriting the code to open a socket, assemble frames, and wait for a response for every scenario. ZLink doesn't need that work. The client library your real users use is itself the verification tool. An E2E test comes down to just this much code.

// A real connection
await client.connect(signal);
// A real request
const auth = await client.request(authenticateReq(actorId))
  .submit<AuthenticateRes>(signal);
// Confirms a real push arrived
const push = await other.waitFor<PlayerJoinedNotify>(
  PacketNames.playerJoinedNotify).submit(signal);
zlinkStreamAssert.ensure(
  push.payload.actorId === auth.player.actorId, 'join push actor mismatch.');

Because the connector itself provides the wait functions verification needs, like WaitFor, you don't implement a separate test harness. Every sample in this repository is verified this way.

Distinguish what E2E does and doesn't cover. E2E confirms things like registration, routing, push, and lifecycle — items that only surface when multiple processes run together. Branches or calculations inside a handler are far faster and more precise to verify with a unit test, so they don't belong in E2E.

1. The Libraries Used for Verification

The two libraries used for verification don't overlap in role.

Zlink.HttpClient Zlink.Stream.Connector
What it verifies The management/gateway HTTP API A STREAM server node
When to use it Things that finish with a single request-response exchange, like creating a room, querying, or admin commands Things that require a live connection, including confirmation of server-initiated pushes
Representative call Post(...).Body(...).Fetch<T>() connect · request · WaitFor · ExpectNone

Most scenarios chain the two together — create a target over HTTP, then connect to STREAM using the endpoint returned in that response.

// Step 1 -- create a room through the gateway API.
const api = ZLinkHttpClient.create(options.apiUrl).timeout(options.httpTimeout).build();
// fetch returns the deserialized body as-is.
const room = await api.post('/games')
  .body(createGameHttpReq(options.gameName))
  .fetch<CreateGameHttpRes>();

// Step 2 -- open a real-time connection to the endpoint the response gave us.
const client = zlinkStreamConnectorFactory.create({
  endpoint: room.playEndpoints[0],
  connectTimeoutMs: options.streamTimeoutMs,
  requestTimeoutMs: options.streamTimeoutMs,
  // Console scenarios use the automatic pump.
  dispatchMode: ZlinkStreamDispatchMode.Immediate
});

When dispatchMode is Immediate, the connector handles receiving on its own, so the scenario code never runs a separate pump. Environments that must pump manually to match a frame loop, like a game engine, are covered by the Stream Connector guide.

Each library's guide covers its full usage.

  • The HTTP Client guide — request construction, body, auth/TLS, retry, and error handling, across 13 chapters
  • The Stream Connector guide — per-runtime integration (Unity, Godot). Server-side STREAM registration is covered by 09-stream.

2. Verification Functions and Usage

Most scenarios are expressed with the verification functions the connector provides.

What's verified Function used
Send a request and check the response Request(req) — the response type is specified on the terminal
Confirm a push the server sends first arrives WaitFor<TNotify>()
Confirm a push does not arrive ExpectNone<TNotify>().Within(window)
Confirm pushes arrive in a fixed order WaitForSequence<TNotify>().Expect(...).Expect(...)
Confirm a request fails expectFailure(...)

The terminal call follows the language — .NET uses Async, C++ uses async, Java/Node use submit, and Kotlin uses await (Async Execution Policy).

Value comparison uses Ensure(condition, message). The message is required, and on failure the scenario ends with an exception carrying that message.

Confirming a Push Arrives

Specify a condition with where(...) to wait for the first message matching that condition. Other, nonmatching pushes may arrive without affecting the scenario.

const joined = await client1.waitFor<PlayerJoinedNotify>(PacketNames.playerJoinedNotify)
  .where((message) => message.payload.actorId === options.oActorId)
  .submit(signal);
zlinkStreamAssert.ensure(joined.payload.mark === TicTacToeMarks.O, 'joined mark mismatch.');

Confirming a Push Doesn't Arrive

You can't confirm something never arrives without an observation window, so within(...) must be specified. Omitting it is an error.

// The player who just joined shouldn't receive their own join notification.
await client2.expectNone<PlayerJoinedNotify>(PacketNames.playerJoinedNotify)
  .within(250)
  .run(signal);

Confirming Push Order

In a flow where state changes in stages, the contract isn't whether something arrives but its order.

const statusSequence = await customer
  .waitForSequence<DeliveryStatusNotify>(PacketNames.deliveryStatusNotify)
  .expect((message) => matchesStatus(message, deliveryId, DeliveryStatus.Assigned))
  .expect((message) => matchesStatus(message, deliveryId, DeliveryStatus.Accepted))
  .expect((message) => matchesStatus(message, deliveryId, DeliveryStatus.PickedUp))
  .expect((message) => matchesStatus(message, deliveryId, DeliveryStatus.Delivered))
  .timeout(customer.options.waitTimeoutMs)
  .submit(signal);

Confirming a Request Fails

Whether a request with no permission or an out-of-order request gets rejected is also part of the contract. Verifying only the success path leaves this path unverified.

// Can't open a conversation before authenticating.
await zlinkStreamAssert.expectFailure(
  () => agent.request(openConversationReq('unauthenticated'))
    .submit<OpenConversationRes>(signal),
  ZlinkStreamErrorCode.RemoteError
);

3. How to Handle Waiting for a Message

Most E2E flakiness has the same cause. You act first, then start waiting, and miss a push that arrived in between.

Reverse the order. Register the wait first, then run the action that triggers that push.

// Register the wait first -- don't await it yet.
const statusSequencePromise = customer
  .waitForSequence<DeliveryStatusNotify>(PacketNames.deliveryStatusNotify)
  .expect((message) => matchesStatus(message, deliveryId, DeliveryStatus.Assigned))
  .timeout(customer.options.waitTimeoutMs)
  .submit(signal);

// Then run the action that triggers the push.
const created = await http.post('/deliveries')
  .body(createDeliveryReq(deliveryId, 'customer-1', 'Kitchen 12', 'Customer Lobby'))
  .fetch<CreateDeliveryRes>();

// Receive the result last.
const statusSequence = await statusSequencePromise;

If multiple clients need to confirm the same event, register a wait for each and receive them together with Task.WhenAll.

// Bingo -- once both players have joined the room starts, and both clients get the same push.
const client1Started = client1
  .waitFor<BingoGameStartedNotify>(PacketNames.gameStartedNotify).submit(signal);
const client2Started = client2
  .waitFor<BingoGameStartedNotify>(PacketNames.gameStartedNotify).submit(signal);

await Promise.all([client1Started, client2Started]);

Don't use Sleep to line up timing. Express every wait through the timeout on WaitFor/ExpectNone/WaitForSequence. Sleep fails on slow hardware and wastes time on fast hardware.

4. A Complete Scenario Example

The TicTacToe sample is the shortest. Create a room over HTTP → both players connect and authenticate → confirm the join push → make a move → confirm the opponent observes that move, in that order.

async function run(options: TicTacToeClientOptions, signal: AbortSignal): Promise<void> {
  // 1. Create a room through the gateway API and get the endpoint to connect to.
  const api = ZLinkHttpClient.create(options.apiUrl).timeout(options.httpTimeout).build();
  const room = await api.post('/games')
    .body(createGameHttpReq(options.gameName))
    .fetch<CreateGameHttpRes>();
  zlinkStreamAssert.ensure(room.playEndpoints.length >= 2, 'play endpoints are missing.');

  // 2. Connect the two players to different Play nodes -- this verifies routing between nodes.
  const client1 = createStreamClient(room.playEndpoints[0], options);
  const client2 = createStreamClient(room.playEndpoints[1], options);

  // 3. Whoever connects first authenticates and enters the empty room.
  await client1.connect(signal);
  await client1.request(authenticateReq(options.xActorId)).submit<AuthenticateRes>(signal);
  // Register wait -> send -> receive (see §3)
  const join1 = await joinGame(client1, room.roomId, signal);
  zlinkStreamAssert.ensure(
    join1.state.status === TicTacToeGameStatuses.WaitingForPlayers,
    'room should wait for the second player.');

  // Being alone in the room, their own join notification shouldn't come back to them.
  await client1.expectNone<PlayerJoinedNotify>(PacketNames.playerJoinedNotify).within(250).run(signal);

  // 4. Once the second player joins, the room starts.
  await client2.connect(signal);
  await client2.request(authenticateReq(options.oActorId)).submit<AuthenticateRes>(signal);
  const join2 = await joinGame(client2, room.roomId, signal);
  zlinkStreamAssert.ensure(
    join2.state.status === TicTacToeGameStatuses.InProgress, 'room should start with two players.');

  // 5. Making a move -- the response and the push delivered to the opponent should point to the same state.
  const move = await client1.request(placeMarkReq(0)).submit<PlaceMarkRes>(signal);
  const sawMove = await client2.waitFor<GameStateNotify>(PacketNames.gameStateNotify)
    .where((message) => message.payload.state.lastMoveCell === 0)
    .submit(signal);
  zlinkStreamAssert.ensure(sawMove.payload.state.board === move.state.board, 'board state mismatch.');
}

Choose verification points by this rule. Don't just check a request's own response — also check whether another client observes the same fact. Making the result that actually reaches the user, not server-internal state, the contract, is the point of E2E.

5. Verifying with Multiple Clients

A single scenario can create several clients. Splitting roles verifies contracts a single client can't confirm.

  • Two players — whether one's action reaches the other, and conversely, that it doesn't reach themselves
  • A spectator — whether a notification reaches a non-participant connection, and conversely, that a participant-only notification doesn't
  • Two connected to different nodes — whether routing and location resolution between nodes actually work
// The join completion arrives as a client push -- register the wait before the one-way send.
async function joinGame(
  connector: ZlinkStreamConnector, roomId: string, signal: AbortSignal): Promise<JoinGameNotify> {
  const completion = connector.waitFor<JoinGameNotify>(PacketNames.joinGameNotify).submit(signal);
  await connector.send(joinGameMsg(roomId)).submit();
  return (await completion).payload;
}

The Bingo sample uses this composition as-is — it brings together two players and one spectator, and even confirms the win notification is delivered only to the spectator.

6. Run Scripts and Success Criteria

The run script is responsible for starting the server, running the client, and cleaning up afterward.

# For Node, a runner script performs the same procedure instead of shell.
node "${SCRIPT_DIR}/../run-sample.mjs" "${SCRIPT_DIR}/Runner/sample-runner.mjs"

# sample-runner.mjs is responsible for starting the server, waiting for the port,
# running the client, and cleaning up.
# The success criterion is the same as the other languages -- the client's exit code.

The script follows these rules.

  • The client's exit code is the success criterion. Under set -e, if the client exits with an exception, the script fails at that point too. No separate judgment logic is implemented.
  • Wait on a condition, not sleep. Server startup is confirmed by whether the port is open; async post-processing, by whether a specific line appeared in the log.
  • Clean up with trap so that a scenario failing partway through doesn't leave started processes, temp directories, or containers behind to affect the next run.

Even if the client passes, also check that the server logs have no errors. Sometimes the client observes normal behavior while the server records a dispatch error.

if grep -R -q "dispatch-error" "${LOG_DIR}"; then
  echo "Unexpected dispatch-error in sample logs." >&2
  exit 1
fi

7. Common Problems

  • A push isn't received, causing intermittent failure → check that the wait was registered before the action (§3). Starting the wait afterward misses a push that arrived in between.
  • ExpectNone ends in an error → within(...) wasn't specified. You can't confirm something never arrives without an observation window, so the window is required explicitly.
  • WaitFor returns a different message → you waited on type alone, with no condition. Narrow it with where(...) to the event this scenario is actually waiting for.
  • It passes locally but fails only in CI → check for remaining timing dependencies implemented with sleep. Express every wait through a wait function with an explicit timeout.
  • The client passes but the server log has an error → the script doesn't check server logs for errors (§6).
  • It connects but the push never arrives → in an environment that needs manual pumping, like engine integration, dispatch wasn't run (see the Stream Connector guide).