go-specs

go-specs

Description

go-specs is a fast, deterministic BDD-style testing framework for Go. It provides an expressive DSL for writing readable tests while staying close to the standard library and avoiding reflection and allocation overhead. Suites run in a fixed order with no hidden concurrency, so test results are stable and reproducible.

Key features

• BDD-style API — Describe, When, It, BeforeEach, and AfterEach for structured specs
• Deterministic execution — Specs run in declaration order; no map iteration or nondeterministic scheduling
• Low overhead — Zero allocations on the assertion fast path; compiled execution plan
• Rich assertions — Expect(x).ToEqual(y), matchers (BeTrue, Equal, BeNil, etc.), and snapshot testing
• Combinatorial testing — Path builder for deterministic exploration of parameter spaces
• Lightweight mocking — Spies and argument matchers without heavy code generation

Installation

go get github.com/pablogore/go-specs

Basic example

package math_test

import (
	"testing"

	"github.com/pablogore/go-specs/specs"
)

func TestMath(t *testing.T) {
	specs.Describe(t, "math", func(s *specs.Spec) {
		s.It("adds numbers", func(ctx *specs.Context) {
			ctx.Expect(1 + 1).ToEqual(2)
		})
	})
}

Hooks example

Use BeforeEach and AfterEach for per-spec setup and teardown:

func TestMathWithHooks(t *testing.T) {
	specs.Describe(t, "math", func(s *specs.Spec) {
		s.BeforeEach(func(ctx *specs.Context) {
			// runs before each It
		})

		s.It("adds numbers", func(ctx *specs.Context) {
			ctx.Expect(add(1, 2)).ToEqual(3)
		})
	})
}

See examples/basic and examples/hooks for runnable examples.

Benchmarks

go-specs is built for low latency and zero allocations on the hot path. The tables below compare single-assertion cost, runner execution (1000 specs), hooks, matchers, and suite scaling against Testify and Gomega. Values are averaged from make bench-report (10 runs).

Assertions

Runner (1000 specs, one assertion per spec)

Hooks (100 specs, 5 nested BeforeEach + one assertion per spec)

Matcher (Expect().To(Equal) style)

Suite scaling (go-specs)

Why go-specs is fast

• Zero allocations — The assertion and runner hot paths allocate nothing on success (0 allocs/op above), reducing GC pressure.
• Compiled execution plan — Suites are compiled once into a fixed program; the runner executes steps via direct function dispatch instead of per-spec lookups or reflection.
• No reflection — Assertions use generics and direct comparison; the fast path avoids reflect.DeepEqual and runtime type switches.
• Sequential runner loop — The runner invokes spec and hook functions in a simple loop with direct calls; no matcher heap allocations or indirection on the hot path.

Reproducible benchmark suite: benchmarks/. From the repository root run make bench (quick) or make bench-report to generate a report in benchmarks/results/current.txt.

Architecture overview

go-specs compiles a spec tree (from Describe / It / BeforeEach / etc.) into an execution plan once. The runner then executes that plan in order: for each spec it runs before hooks, the spec body, and after hooks (LIFO). No maps or reflection are used at run time; the plan is a flat sequence of steps with direct function pointers. Parallel specs (ItParallel via the Builder) are grouped into a single step and run concurrently, then execution continues sequentially. The repository is a single Go module; packages include:

• specs — Core DSL, runner, context, and execution plan
• assert — Matcher implementations (Equal, BeTrue, BeNil, etc.)
• benchmarks — Benchmark suite (go-specs vs Testify vs Gomega)
• mock — Spies and argument matchers
• snapshots — Snapshot testing support
• examples — Example tests (basic, hooks, parallel, and more)

Running benchmarks

From the repository root:

Generate a report for the README or CI:

make bench-report

Compare before/after a change:

make bench-report
cp benchmarks/results/current.txt benchmarks/results/previous.txt
# ... make your changes ...
make bench-report
make bench-compare

Run by category (direct go test):

go test ./benchmarks -bench=BenchmarkAssertion -benchmem
go test ./benchmarks -bench=BenchmarkRunner -benchmem
go test ./benchmarks -bench=BenchmarkSuite_ -benchmem

See benchmarks/README.md for full benchmark layout and options.

Contributing

Contributions are welcome. Before submitting changes:

1. Run the test suite: go test ./... and go test -race ./...
2. Run the linter: go vet ./...
3. If you change performance-sensitive code, run: go test ./benchmarks -bench=. -benchmem

Please open an issue or discussion for larger changes so we can align on direction.

License

MIT License. See LICENSE for details.