@painda/testing

Testing real-time network interactions introduces flakiness due to unpredictable latency and non-deterministic event loops. @painda/testing offers headless server+client bootstrapping and deterministic message awaiters specifically designed for integration logic tests.

Installation

Usage in Integration Tests

We strongly recommend using waitForMessage and createTestEnv in Jest / Vitest environments over asserting state inside synchronous callbacks.

import { createTestEnv, waitForMessage, collectMessages } from "@painda/testing";
import { describe, it, expect } from "vitest";

describe("Room Broadcasts", () => {
  it("should push delta states down to connected players", async () => {
    const { server, client, cleanup } = await createTestEnv();
    
    // Arrange: Game Mock
    server.on("connection", (socket) => {
        socket.join("lobby");
        server.to("lobby").emit("system", "welcome!");
    });
    
    // Assert: Deterministic event listener wait
    const msg = await waitForMessage(client, "system");
    expect(msg.payload).toEqual("welcome!");

    cleanup();
  });
});

Core API

• createTestEnv(options): Starts a real server on a random port and attaches a single client automatically. Resolves when the connection is open.
• createTestClients(port, count): Attaches multiple disconnected mock-peers instantly.
• waitForMessage(client, type): Promise-based event listener yielding the payload explicitly.
• collectMessages(client, count): Awaits an exact count of events regardless of the type. Useful for heartbeat tests or network flooding simulations.
• waitFor(fn): Generic polling assertion for hidden internal back-end states.