Testing with Sentinel

Cache Behavior in Tests

Sentinel uses a global cache that persists across tests. This is usually fine because:

• Type metadata is deterministic
• Cache hits return identical data
• No side effects from cached metadata

Test Isolation

If you need cache isolation, use the testing helpers by running with the testing build tag:

import (
    "testing"

    "github.com/zoobz-io/sentinel"
    sentineltest "github.com/zoobz-io/sentinel/testing"
)

func TestSomething(t *testing.T) {
    sentineltest.ResetCache(t)
    metadata := sentinel.Inspect[MyType]()
    // ...
}

Run tests with -tags testing to enable the helpers:

go test -tags testing ./...
# or use the Makefile
make test

The Reset() function and testing helpers are only available when building with -tags testing. This prevents accidental cache clearing in production.

Testing Metadata Extraction

func TestUserMetadata(t *testing.T) {
    metadata := sentinel.Inspect[User]()

    if metadata.TypeName != "User" {
        t.Errorf("expected User, got %s", metadata.TypeName)
    }

    if len(metadata.Fields) != 3 {
        t.Errorf("expected 3 fields, got %d", len(metadata.Fields))
    }
}

Testing Relationships

func TestUserRelationships(t *testing.T) {
    metadata := sentinel.Scan[User]()

    var hasProfile bool
    for _, rel := range metadata.Relationships {
        if strings.HasSuffix(rel.To, ".Profile") && rel.Kind == "reference" {
            hasProfile = true
        }
    }

    if !hasProfile {
        t.Error("expected relationship to Profile")
    }
}

Testing Tag Extraction

func TestCustomTags(t *testing.T) {
    sentinel.Tag("custom")

    type Tagged struct {
        Field string `custom:"value"`
    }

    metadata := sentinel.Inspect[Tagged]()

    if metadata.Fields[0].Tags["custom"] != "value" {
        t.Error("custom tag not extracted")
    }
}

Benchmarking

Run benchmarks to verify performance:

make bench
# or
go test -bench=. -benchmem ./testing/benchmarks/

Expected performance:

• Cache hit: ~80ns, 0 allocations
• Concurrent access: ~40ns per operation

Next Steps

• Troubleshooting — common issues and fixes
• API Reference — complete function documentation