Spec Guardian

At a glance

Spec Guardian is an Apache-2.0 Go tool that turns a FizzBee formal spec into conformance tests for your real code. FizzBee explores the states a spec allows; Spec Guardian generates Go tests that run one action normally and with an error injected just before each supported I/O call, then check the resulting database or cache state against those allowed states. It suits teams checking whether code, including AI-written code, matches a design they modeled.

Good fit

Go services where operation order and partial failure matter, such as cache invalidation, idempotent requests or table commits. The README's cache-aside example shows the payoff: deleting the cache before the database write passes on success but fails the generated test once the write fails, with a diff of the unexpected database and cache values.

Consider something else when

Your code is not in Go, you have no FizzBee spec and do not plan to write one, or you need to check sequences of several actions. Tests are generated for one FizzBee action invocation at a time. Ordinary unit and integration tests remain the simpler choice when there is no independent model of allowed states.

Start here

With Go and Docker Compose installed, clone the repository, cd spec-guardian/examples/tutorial_cache_aside_write, run docker compose up -d, then go test -count=1 -tags=specguardian ./conformance/.... It should pass. Swap the two calls in cache_aside.go as the README's diff shows and rerun to see the failure report, then follow the user guide to wire your own project.

Cost and requirements

Free and open source under Apache-2.0. You need Go 1.27 or later, FizzBee installed separately to explore your spec, and the stores your tests touch; the examples run PostgreSQL and Valkey through Docker Compose. The repository includes SQL, Valkey and DynamoDB providers, plus an error-as-crashed provider.

Limits to know

The project says it is under development and its public APIs or generated Go code may change. Generation is only half the job: you or an AI write the setup, action call and remaining state observation code in <role>_conformance_impl_test.go, and map model fields to stored data in specguardian.yml. Faults are injected only before supported I/O calls, listed in the guardian directory, which holds hooks for SQL, valkey-go and the AWS SDK for Go v2. A passing test shows conformance only to what the spec models.

Still unclear

• How much effort does the state-observation code take for a project whose storage is not SQL, Valkey or DynamoDB?