Harness - NexusTomorrow/server GitHub Wiki

How the test harness works as built, and why: the real server run in-process, headless clients that speak the client's protocol over real sockets, and scenarios that drive it the way an admin and a player would. The facts to look up are on Harness server and Harness scenarios; what's still to build is on Harness design.

How it fits together

The shape

flowchart TD
    S["A scenario"] -->|"account create, as the harness"| H["The real host, in-process"]
    S --> HC["Headless client"]
    HC -->|"STS, login, world: real sockets"| H
    H --> DB[("A fresh test database")]

It runs the real host. A scenario starts the same composition the server runs (Host), in the test process, on free loopback ports, against a fresh database, with a fake clock and its console off.

It sets up through the command layer. A scenario creates accounts and changes them as an admin would, through the command layer, never by reaching into an owner.

Its clients speak the client's protocol. A headless client's side of each message comes from the same declarations as the server's, so the two can't drift apart, and it talks over real sockets.

A stalled owner fails the scenario. On teardown the harness waits for every owner's queue to empty, so a scenario that leaves an owner stuck fails.

Why it's built this way

The checks that matter are the ones a real client would notice, and a scenario is the closest a test gets to one without the client: the same host, the same sockets and the same bytes. Expectations are written from what the client needs, never computed by the code under test.

Known edges

• Tick controls and the allocation gate need a map, so they arrive with step 3's second stage (Harness design).

Where the code lives

Piece	Path
The harness server, headless client and world session	Tests/NexusTomorrow.Harness/
The scenarios	Tests/NexusTomorrow.Harness.Tests/
Test databases and fakes shared by every test project	Tests/NexusTomorrow.Testing/