kami
9734eec63c
Generated by per-group subagents covering all 52 modules across: core (18), infrastructure (10), apps (5), interfaces (3), plugins (7), testing (9) Documentation format: - AsciiDoc (.adoc) files in docs/modules/<group>/ - PlantUML (.puml) files in docs/diagrams/ - .adoc files reference diagrams via include:: directives Each doc covers: purpose, responsibilities, non-responsibilities, key types, event flow, integration points, invariants, PlantUML diagram, known issues, and open questions.
88 lines
3.3 KiB
Plaintext
88 lines
3.3 KiB
Plaintext
= test-contracts
|
|
|
|
== purpose
|
|
|
|
Contract tests that validate the behavioral guarantees of core domain types. Ensures that value objects, model classes, and domain interfaces conform to their documented contracts across serialization, equality, and behavior.
|
|
|
|
== responsibilities
|
|
|
|
* Validate `WorkflowGraph`, `StageId`, `TransitionId` construction and invariants
|
|
* Test `InferenceProvider` contract (routing, health check, caching)
|
|
* Test `ValidationReport` contract and serialization
|
|
* Test `ContextSnapshot` construction and serialization
|
|
* Test orchestration model types (`OrchestrationConfig`, `WorkflowResult`, `StageOutcome`, `RetryPolicy`)
|
|
* Provide concurrent testing utilities (`ConcurrencyRunner`, `DeterministicBarrier`)
|
|
|
|
== non-responsibilities
|
|
|
|
* Does not test full integration between modules
|
|
* Does not test infrastructure adapters
|
|
* Does not test UI or application layers
|
|
|
|
== key types (test utilities)
|
|
|
|
=== ConcurrencyRunner
|
|
* **kind**: object
|
|
* **purpose**: Runs a block concurrently across N threads for M iterations using a `CountDownLatch` for synchronized start. Used for concurrency safety contract tests.
|
|
|
|
=== DeterministicBarrier
|
|
* **kind**: class
|
|
* **purpose**: Thin wrapper over `java.util.concurrent.CyclicBarrier` for synchronizing test threads at known points.
|
|
|
|
=== WorkflowGraphTest
|
|
* **kind**: JUnit 5 test class
|
|
* **purpose**: Tests `WorkflowGraph` construction, stage lookup, transition validation, and serialization round-trips.
|
|
|
|
=== InferenceProviderContractTest
|
|
* **kind**: JUnit 5 test class
|
|
* **purpose**: Defines the contract that all `InferenceProvider` implementations must satisfy (request handling, health check, capability reporting).
|
|
|
|
=== DefaultInferenceRouterTest / DefaultInferenceRouterCacheTest
|
|
* **kind**: JUnit 5 test classes
|
|
* **purpose**: Tests routing strategy, provider selection, and cache invalidation behavior.
|
|
|
|
=== EventsTest
|
|
* **kind**: JUnit 5 test class
|
|
* **purpose**: Tests event payload construction, metadata, and serialization contracts.
|
|
|
|
== event flow
|
|
|
|
*inbound:* Constructed domain objects and serialized JSON strings.
|
|
|
|
*outbound:* Assertions on equality, serialization round-trips, exception types, and behavioral contracts.
|
|
|
|
== integration points
|
|
|
|
* `:core:transitions` — `WorkflowGraph`, `StageConfig`, `TransitionEdge`
|
|
* `:core:inference` — `InferenceProvider`, `DefaultInferenceRouter`, `ProviderHealth`
|
|
* `:core:validation` — `ValidationReport`, validation model types
|
|
* `:core:events` — event payload types, `EventMetadata`
|
|
* `:core:context` — `ContextSnapshot`
|
|
* `:core:kernel` — orchestration config and result types
|
|
|
|
== invariants
|
|
|
|
* All serializable types survive a JSON encode/decode round-trip without data loss
|
|
* `StageId` and `TransitionId` are valid when non-blank
|
|
* `InferenceProvider.healthCheck()` never throws for healthy providers
|
|
|
|
== PlantUML diagram
|
|
|
|
[plantuml, test-contracts, "png"]
|
|
----
|
|
include::../../diagrams/test-contracts.puml[]
|
|
----
|
|
|
|
|
|
|
|
|
|
== known issues
|
|
|
|
* `ConcurrencyRunner` does not assert on thread safety — it only provides concurrent execution scaffolding; the test must supply assertions
|
|
* `DeterministicBarrier` does not have a timeout — a stalled test thread will hang indefinitely
|
|
|
|
== open questions
|
|
|
|
* Should contract tests be parameterized to run against all implementations of each interface?
|
|
* Should JSON schema validation be added to serialization contract tests?
|