Acceptance tests

Required

An acceptance test turns one important promise of your design into a check the finished game must pass. The builder has to show that the check passes. The builder is the person, team or AI that turns your package into a game. You say what must be true, not how to program it.

A test is a heading that starts with AT- and a number, immediately followed by one JSON block marked test. Tests live in 05-build-plan.md, next to the build stage they belong to. Any explanation goes after the block. The numbers go up in document order, and a deleted test's number is never used again.

05-build-plan.md, under the heading AT-4: Alarm on sight

{
  "type": "scenario",
  "given": "a guard on patrol with the player inside its view cone",
  "when": "the player stays visible for alarm.spot_seconds",
  "then": ["the guard raises the alarm", "every other guard on the floor starts searching"],
  "diagnostics": ["visibility-timeline", "guard-state-after"]
}

Tests come in two kinds. A scenario is one situation. A general test is a promise about many cases. This one is a scenario. given is the starting situation, when is what happens, and then lists what must be true afterwards. Each can be one sentence or a list. diagnostics names the evidence a test run should keep, so a failure can be understood.

Names like alarm.spot_seconds inside a test are instructions for whoever runs it. The validator (the checking tool) does not check that they exist.

Most tests are scenarios. Write a general test when the promise is about many cases. The same stealth game generates its floors, and this promise is about all of them. scope says which cases, in your own words. holds says what must be true for all of them. seeds names the random sequences that generate the cases, so a failure can be reproduced.

05-build-plan.md, checking every generated floor of the same game

{
  "type": "general",
  "scope": "every floor generated at default tuning",
  "holds": "every guard's patrol route reaches every room on its floor",
  "seeds": ["patrol-routes-12"],
  "diagnostics": ["sample-seed", "floor-layout", "unreached-room"]
}

A general test can be checked over every case in its scope or over a sample. If the promise says "never" or "always", a sample is not enough. Only checking every case proves it. The builder's report of the build says which general tests were sampled. The What validation proves chapter explains that report.

Full rules: OpenGDD specification, §6.