Rijad Zuzo
102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
# Feature slice: tests, quality, and performance evidence
|
|
|
|
The project uses deterministic headless scenarios, GUT unit tests, formatting/
|
|
lint checks, and reviewed benchmark ledgers. Tests are part of the architecture:
|
|
they prove authority boundaries, conservation, migration, parity, and
|
|
deterministic continuation.
|
|
|
|
## Quality gate
|
|
|
|
Run from the repository root:
|
|
|
|
```bash
|
|
./tools/quality.sh --changed # fast iteration
|
|
./tools/quality.sh # full gate before commit
|
|
git diff --check
|
|
```
|
|
|
|
The gate currently runs Godot 4.7 platform/import checks, `gdformat`,
|
|
`gdlint`, headless project checks, standalone scenarios, GUT, and a dedicated
|
|
Compatibility presentation smoke. It uses an isolated Godot profile under
|
|
`logs/quality/godot_profile`. On macOS, Godot's certificate-store diagnostic,
|
|
Terrain3D interpolation deprecation, and the exact known dummy-shader exit
|
|
diagnostic are classified by the gate; new error classes must not be hidden.
|
|
|
|
## Scenario families
|
|
|
|
| Concern | Representative tests |
|
|
| --- | --- |
|
|
| Definitions and packs | `content_catalog_test`, `simulation_definitions_test`, `test_activity_content_catalog_contract` |
|
|
| Targets and interaction parity | `world_target_registry_test`, `context_scoped_world_targets_test`, `resource_node_player_parity_test`, `test_activity_action_command_service` |
|
|
| Economy and resources | `food_storage_loop_test`, `resource_regrowth_test`, `animal_food_delivery_test` |
|
|
| Animals and enemies | `animal_definition_contract_test`, `animal_pair_vertical_slice_test`, `test_combatant_factory`, `conflict_war_system_test` |
|
|
| Events and social facts | `test_world_event_store`, `test_social_foundations`, `witnessed_knowledge_consequence_test`, `relationship_consequence_test` |
|
|
| Situations and dialogue | `test_situation_system`, `emergent_jajce_slice_test`, `conversation_domain_test`, `dialogue_manager_conversation_presenter_test`, `dialogue_mode_controller_test` |
|
|
| Save/migration | `test_emergent_state_validation`, `simulation_state_serialization_test`, `save_slot_persistence_test`, `test_commitment_lifecycle_service` |
|
|
| Regional records | `test_regional_world_state`, `test_regional_scheduler`, `test_regional_caravan_service`, `test_regional_chunked_persistence`, `test_regional_chunked_file_store` |
|
|
| Presentation | `jajce_world_scaffold_test`, `jajce_presentation_quality_test`, `jajce_runtime_integration_test`, `test_presentation_relevance_policy`, `creature_visual_path_retry_test` |
|
|
|
|
When a change affects state, target selection, saves, navigation reachability,
|
|
player/NPC parity, deterministic continuation, or a fact-representing UI,
|
|
extend a scenario rather than relying on a parser/lint pass.
|
|
|
|
## Benchmark runners
|
|
|
|
```bash
|
|
# local simulation population/history fixture
|
|
godot --headless --path "$PWD" \
|
|
--script res://tools/benchmark_simulation_scaling.gd
|
|
|
|
# loaded finite-resource spatial discovery
|
|
godot --headless --path "$PWD" \
|
|
--script res://tools/benchmark_loaded_resource_discovery.gd
|
|
|
|
# regional records and scheduler (20 caravans / 50k cohorts)
|
|
godot --headless --path "$PWD" \
|
|
--script res://tools/benchmark_regional_scale.gd
|
|
```
|
|
|
|
Reviewed reports live in `docs/benchmarks/` beside machine-readable JSON. A
|
|
benchmark must record seed, Godot version, host label, workload/schema ID,
|
|
sample count, warmup, simulated ticks, checksums, and exclusions. Structural
|
|
headless measurements cannot be presented as rendered frame-time claims.
|
|
|
|
## Determinism and conservation checklist
|
|
|
|
For a new system, add tests for:
|
|
|
|
- same seed/run produces the same canonical checksum;
|
|
- save/load at the important boundary continues identically;
|
|
- execution budgets `{1, 8, unlimited}` preserve order and result where a
|
|
scheduler is involved;
|
|
- loaded, unloaded, and load/unload presentation produce identical authority;
|
|
- people, cargo, inventory, storage, unique items, and event IDs conserve;
|
|
- stale offers, duplicate IDs, unknown definitions, forged facts, and scope
|
|
mismatches fail without partial mutation;
|
|
- important identities remain pinned through relevance/aggregation decisions.
|
|
|
|
## Current evidence and gaps
|
|
|
|
The current full suite passes 154/154 tests with 2,047 assertions. Baseline 03
|
|
measures 600 full-fidelity data-only NPC/combatant records at about 90.6 ticks/s
|
|
on the reviewed development host. The regional baseline proves the target
|
|
record counts and scheduler parity. Neither measures a complete regional
|
|
economy or weak-PC rendering.
|
|
|
|
The next performance evidence should capture High and Low at a fixed gameplay
|
|
camera on a named weak-PC reference: p50/p95/p99 CPU/GPU frame time, draw calls,
|
|
primitives, memory/VRAM, active detailed visuals, and navigation queue depth.
|
|
Keep those measurements in a reviewed ledger instead of adding brittle hardware
|
|
limits to CI.
|
|
|
|
## Test authoring conventions
|
|
|
|
- Use stable IDs and fixed seeds.
|
|
- Prefer exact assertions over prose or frame timing.
|
|
- Make test fixtures isolate duplicate stable-ID registries and world scopes.
|
|
- Use fake presenters for semantic dialogue; reserve plugin/parser tests for the
|
|
adapter boundary.
|
|
- Keep benchmark fixtures independent of production managers unless the test is
|
|
explicitly an integration proof.
|
|
- Run focused tests while editing, then the full gate before committing.
|