What is SpecGuardian?
SpecGuardian is a Go testing tool for checking whether an implementation follows a formal FizzBee specification. It turns FizzBee state-exploration results into generated tests that compare the application's observed state with states permitted by the spec. Tests can run an action normally or with an error injected before a supported I/O call. It is intended for developers verifying AI-generated or hand-written Go implementations, and complements unit and integration tests with a specification-based check.
SpecGuardian Features:
Generated Go Tests: SpecGuardian converts FizzBee exploration results into Go tests for checking an implementation against the states allowed by its specification.
State Comparison: Tests observe the application's resulting state and compare it with states permitted by the FizzBee spec.
I/O Failure Injection: Generated tests can inject an error immediately before a supported I/O call to check the state left by a failure.
Test Configuration: A specguardian.yml file configures state observation, comparison, and providers used by the tests.
Action-Level Testing: The current test generation scope covers one FizzBee Action invocation at a time.
Project Setup: The init command prepares project files from FizzBee output, after which developers connect the generated tests to their application.
SpecGuardian Benefits:
Catch Ordering Bugs: A test can expose an incorrect operation sequence even when the faulty implementation reaches the same final state on successful runs.
Check Failure Behavior: Developers can see whether partial work after an I/O error leaves data in a combination the specification forbids.
Independent Expectations: Expected states come from a FizzBee spec defined separately from the implementation, giving teams a distinct correctness check.
Broader State Checks: Teams can assess the resulting application state rather than relying only on assertions about individual functions.
Test AI Code: The specification-based check helps developers verify that AI-generated Go code follows the system behavior they modeled.
Use Cases:
Cache-Aside Writes: Check that a cache-aside write updates the database and invalidates the cache in the order required by the spec.
Database Write Failures: Test whether a failed database write after another operation leaves the cache and database in an allowed state.
Idempotent Requests: Generate conformance tests for a Go implementation of an idempotent request workflow modeled in FizzBee.
Go Project Conformance: Add specification-based checks to a Go module by generating tests from its FizzBee model and connecting them to application code.
Iceberg Implementation: Use the included Iceberg example as a reference for testing the apache/iceberg-go implementation against a specification.

