Overview

@artstesh/postboy-testing is a dedicated testing toolkit for applications built on top of @artstesh/postboy.
It gives you everything you need to write fast, readable, and isolated tests for event‑driven code — without setting up a real bus.

What it gives you

A fully compatible mock of PostboyService that records every message and subscription
Declarative assertions for fired events, subscriptions, and message payloads
Async helpers to wait for events, callback results, or silence
A BDD‑style API (given/then/waiter) that mirrors Arrange‑Act‑Assert
Two working modes — non‑strict (no registration required) and strict (explicit registry)
Automatic cleanup via world.dispose()

How it fits into your tests

Every test revolves around a single entry point: PostboyWorld.

Internally PostboyWorld wires together a mock bus, a history log, a waiter service, and expressive APIs for preparation and verification. You don’t create mocks manually — you just instantiate the world and use it.

import {PostboyWorld} from '@artstesh/postboy-testing';

let world: PostboyWorld;

beforeEach(() => {
  world = new PostboyWorld({strict: false});
});

afterEach(() => {
  world.dispose();
});

One place to arrange, act, and assert

PostboyWorld exposes five main properties that guide you through the test:

Property	Purpose
`world.postboy`	The mock bus — use it exactly like the real `PostboyService`
`world.given`	Prepare mock behaviour (events, callbacks, executors)
`world.waiter`	Wait for async messages or verify silence
`world.then`	Verify what happened (fired, not fired, subscriptions)
`world.history`	Directly inspect recorded messages and subscriptions

This design encourages a clear, three‑step rhythm in every test.

A minimal example

Imagine a service that fires an event after doing some work. A test with postboy-testing looks like this:

class MyService {
  constructor(private bus: PostboyService) {
  }

  run(): void {
    this.bus.fire(new TaskCompletedEvent());
  }
}

it('should fire TaskCompletedEvent', () => {
  const service = new MyService(world.postboy);
  //
  service.run();                           // Act
  //
  world.then
    .fired(TaskCompletedEvent)              // Assert
    .once();
});

No spies, no manual mocks, no brittle expect on internal details — just a clean description of what the system communicates.

What’s next?

Quick Start — set up your first test in under two minutes
Core Concepts — understand PostboyWorld, history, and the Arrange‑Act‑Assert flow
Recipes — copy‑paste patterns for callbacks, executors, async testing, and more

The testing library is designed to grow with your knowledge: start with the Quick Start, keep the API Reference handy, and reach for Recipes when you face common testing scenarios.

06 мая 2026