go-assert

go-assert

A lightweight, zero-dependency assertion framework for Go. It provides a flexible way to handle assertions in development, testing, and production using Go build tags.

Features

• Three Modes: Choose between panic, io.Writer logging, or no-op (zero overhead) using build tags.
• Comprehensive Testing API: Assertions for testing.T including equality, panic, delta, collections, and concurrency helpers.
• Type Safe: Leverages Go Generics (comparable and numeric constraints) for compile-time safety.
• Idiomatic: Clean, minimal, and follows Go's "less is more" philosophy.

Installation

go get github.com/Rafael24595/go-assert

Quick Start

1. Global Assertions (Runtime)

Configure the output once (optional) and use assertions anywhere in your code.

import (
	"os"

	assert "github.com/Rafael24595/go-assert/assert/runtime"
)

func main() {
    // Optional: Set a custom writer (only works once)
    assert.DefaultWriter(os.Stderr)

    val := 10
    assert.True(val > 5, "Value must be greater than 5")
    assert.Unreachable("This code should never execute")
}

2. Testing API

Use assertions directly with testing.T.

package main

import (
	"testing"

	assert "github.com/Rafael24595/go-assert/assert/test"
)

func TestCollections(t *testing.T) {
	assert.Equal(t, 4, 2+2)

	assert.GreaterThan(t, 3, "golang")

	assert.Size(t, 2, map[string]int{
		"go":   1,
		"rust": 2,
	})

	assert.Panic(t, func() {
		panic("boom")
	})
}

Packages

The project provides two independent assertion packages:

Runtime Assertions (assert/runtime)

Runtime assertions are controlled globally using Go build tags.

Available Assertions

Build Configurations

You can control how the package behaves globally by using -tags during compilation or testing:

Usage Examples:

# Run tests with panic on assertion failure
go test -tags g_ast_dbg ./...

# Build your app with logging assertions
go build -tags g_ast_wrt -o myapp .

Testing Assertions (assert/test)

The assert/test package provides helpers for testing.T.

Equality Assertions

Ordering Assertions

These assertions support both:

• numeric values
• measurable values (string, slice, array, map, chan)

Measurable values are compared using len(...).

Collection Assertions

Supported containers:

• string
• slice
• array
• map

Error Assertions

Panic Assertions

Concurrency Assertions

Advanced: Custom Assertions & Mocking

All testing helpers use the assert.T interface instead of a rigid *testing.T pointer. This allows you to build your own domain-specific assertions:

import (
    "testing"

    assert "github.com/Rafael24595/go-assert/assert/test"
)

func AssertValidUser(t assert.T, u User) {
    t.Helper()

    assert.NotEmpty(t, u.ID, "User ID should not be empty")
    assert.Inside(t, "@", u.Email, "User must have a valid email")
}

func TestUserCreation(t *testing.T) {
    u := User{ID: "123", Email: "gopher@golang.org"}
    
    AssertValidUser(t, u)
}

Why go-assert?

go-assert focuses on:

• zero-cost runtime assertions in production
• simple and idiomatic testing helpers
• minimal API surface
• no magic or reflection-heavy DSLs