Droplet ORM
Guide
GitHub
Guide
GitHub
    • Introduction
    • Registry
    • Data Pools
    • Entities
    • Entity Fields
    • MySQL Indexes
    • Code Generation
    • Engine
    • Context
    • Schema Update
    • CRUD Operations
    • Transactions
    • Search
    • Elasticsearch
    • MySQL Queries
    • ClickHouse Queries
    • ClickHouse Schema
    • NATS and JetStream
    • Entity Change Events (CDC)
    • Consumers
    • Tasks and Job Runs
    • Transactional Outbox
    • Context Cache
    • Redis Cache
    • Fake Delete
    • Lifecycle Callbacks
    • Metrics
    • Redis Operations
    • Distributed Lock
    • Queries Log
    • Testing
    • Migrating from fluxaorm

Testing

Droplet ORM tests run against real MySQL, Redis and (optionally) NATS services. The orm package ships helpers that wire a registry to the local Docker services, reset the schema and data between tests, and let you intercept SQL calls and query logs.

Local Services

The ORM repository contains docker/docker-compose.yml with MySQL 8.0, Redis 8.6 (Validate() requires Redis 8.2+ or Valkey 9.0+), ClickHouse and NATS (JetStream enabled). It also defines a debezium service that only the ORM's own change-feed parity test uses; your tests do not need it. Ports are taken from environment variables; docker/.env provides the defaults the test helpers expect:

LOCAL_IP=0.0.0.0
MYSQL_PORT=3397
REDIS_PORT=6395
CLICKHOUSE_PORT=9942
CLICKHOUSE_HTTP_PORT=9943
NATS_PORT=9944
NATS_HTTP_PORT=9945
cd docker
docker compose up -d

MySQL is created with user root / password root and database test. Run the test suite with the race detector and without package parallelism (the packages share the same database):

go test -race -p 1 ./...
# a single test
go test -race -p 1 -run TestUserCRUD ./...

PrepareTables

func PrepareTables(t *testing.T, registry Registry, entities ...any) Context

PrepareTables takes a registry you have already customised (metrics, tasks, extra pools) and completes it with the local test services, then resets everything the test touches:

  1. registry.RegisterMySQL("root:root@tcp(localhost:3397)/test", DefaultPoolCode, &MySQLOptions{})
  2. registry.RegisterRedis("localhost:6395", 0, DefaultPoolCode, nil)
  3. registry.RegisterRedis("localhost:6395", 1, "second", nil)
  4. registry.RegisterEntity(entities...)
  5. registry.Validate() (the test fails on error), and registers a t.Cleanup that closes the engine's MySQL connection pools when the test ends - every test builds its own engine, and pools left open would exhaust MySQL's connections
  6. creates a context with engine.NewContext(context.Background())
  7. FlushDB on both Redis pools
  8. runs every pending schema alter (GetAlters + Exec)
  9. for every registered entity: TruncateTable and UpdateSchema

It returns a ready-to-use orm.Context. Entities are passed exactly as you pass them to RegisterEntity -- values (UserEntity{}) or pointers both work.

import (
    "testing"

    "github.com/DropletLive/orm"
)

func TestSomething(t *testing.T) {
    ctx := orm.PrepareTables(t, orm.NewRegistry(), UserEntity{}, ProductEntity{})
    // ...
}

PrepareTablesWithNats

func PrepareTablesWithNats(t *testing.T, registry Registry, entities ...any) Context

Same as PrepareTables, plus:

  • registry.RegisterNats([]string{"nats://localhost:9944"}, "nats", nil) -- a NATS pool with code "nats"
  • after the tables are prepared, all pending NATS alters are applied (GetNatsAlters + Exec), so registered streams and durable consumers exist before the test publishes.

PrepareTablesWithConsumers

func PrepareTablesWithConsumers(t *testing.T, registry Registry, consumers []ConsumerDef, entities ...any) Context

For tests of entity events, consumers and tasks. In addition to PrepareTablesWithNats it:

  • registers the entity stream and the task stream on the "nats" pool (RegisterEntityStream(EntityStreamOptions{NatsPool: "nats"}), RegisterTaskStream(TaskStreamOptions{NatsPool: "nats"})); the CDC change feed follows the entity stream's pool, so it lands on "nats" too unless you called RegisterCDCStream with another pool
  • registers every ConsumerDef with NatsPool forced to "nats"
  • purges the ORM_ENTITY, ORM_TASK and CDC streams after the alters, so messages from a previous run never leak into the test.

Tasks must be registered on the registry before calling the helper (a consumer draining a queue with no tasks is a validation error), entities listed in ConsumerDef.Entities must be tagged orm:"cdc", and orm.JobRunEntity{} must be registered when tasks are used:

type OrderEntity struct {
    ID     uint64 `orm:"cdc"`
    Number string `orm:"required"`
}

type SendWelcomeEmail struct {
    UserID uint64
}

func TestConsumers(t *testing.T) {
    registry := orm.NewRegistry()
    registry.RegisterTask(SendWelcomeEmail{}, orm.TaskOptions{})

    consumers := []orm.ConsumerDef{
        {Name: "indexer", Entities: []any{OrderEntity{}}},
        {Name: "emails-worker", Queues: []orm.Queue{orm.DefaultQueue}},
    }
    ctx := orm.PrepareTablesWithConsumers(t, registry, consumers, OrderEntity{}, orm.JobRunEntity{})
    defer ctx.Engine().Nats("nats").Close()
    // ...
}

Tips

Close the NATS pool at the end of a test that opened one (defer ctx.Engine().Nats("nats").Close()), otherwise connections accumulate across the package's tests. MySQL pools are closed by the helper itself.

Testing Event Handlers

Through the change feed

A write does not reach an entity consumer directly: it goes on the CDC stream, and the CDC reader forwards it to ORM_ENTITY. A test therefore pumps the reader first, then the consumer:

func TestOrderIndexer(t *testing.T) {
    consumers := []orm.ConsumerDef{{Name: "indexer", Entities: []any{OrderEntity{}}}}
    ctx := orm.PrepareTablesWithConsumers(t, orm.NewRegistry(), consumers, OrderEntity{})
    defer ctx.Engine().Nats("nats").Close()

    var got []*entities.OrderEntityDirtyEvent
    indexer := orm.NewConsumer(ctx.Engine(), entities.ConsumerIndexer).
        OnOrderEntity(func(_ orm.Context, ev *entities.OrderEntityDirtyEvent) error {
            got = append(got, ev)
            return nil
        }).
        Build()
    reader := orm.NewCDCReader(ctx.Engine())

    order := entities.OrderEntityProvider.New(ctx)
    order.SetNumber("A-1")
    require.NoError(t, ctx.Save(order)) // publishes to cdc.test.OrderEntity

    require.NoError(t, reader.Consume(ctx.Context(), 64, 300*time.Millisecond)) // CDC -> ORM_ENTITY
    require.NoError(t, indexer.Consume(ctx.Context(), 32, time.Second))         // ORM_ENTITY -> handler

    require.Len(t, got, 1)
    assert.Equal(t, orm.DirtyInsert, got[0].Op)
    assert.Nil(t, got[0].Before)
    assert.Equal(t, "A-1", got[0].After.GetNumber())
}

orm.ConsumerPending(ctx, orm.CDCReaderName) tells how many changes the reader has not forwarded yet. To test with Debezium as the producer, register orm.CDCStreamOptions{Producer: orm.CDCProducerExternal, NatsPool: "nats"} before calling the helper and publish envelopes to orm.CDCSubject("test", table) yourself; Save then publishes nothing.

Without a database

A handler is a plain function of an event, and Before/After are read-only entities. For cdc/outbox entities the generated provider has NewSnapshot, which builds such an entity in memory through its setters, so a unit test can hand-build an event without MySQL or NATS:

func (p orderEntityProvider) NewSnapshot(id uint64, fill func(e *OrderEntity)) *OrderEntity
func TestOrderHandlerIgnoresUnchangedNumber(t *testing.T) {
    before := entities.OrderEntityProvider.NewSnapshot(42, func(e *entities.OrderEntity) {
        e.SetNumber("A-1")
    })
    after := entities.OrderEntityProvider.NewSnapshot(42, func(e *entities.OrderEntity) {
        e.SetNumber("A-2")
    })
    ev := &entities.OrderEntityDirtyEvent{Op: orm.DirtyUpdate, ID: 42, Before: before, After: after}

    require.NoError(t, handleOrderChange(nil, ev))
}

fill may be nil. Fields that are not set hold their zero value (required enums their first value). The result behaves like an entity received from the feed: getters work and ctx.Save rejects it (it is bound to no context). orm.WatchFields is applied by the consumer, not by the handler, so a hand-built event bypasses it.

Redis-only Setup

When a test needs only Redis (e.g. the distributed lock), skip the helpers and use a dedicated database number:

registry := orm.NewRegistry()
registry.RegisterRedis("localhost:6395", 15, orm.DefaultPoolCode, nil)
engine, err := registry.Validate()
require.NoError(t, err)
ctx := engine.NewContext(context.Background())
require.NoError(t, engine.Redis(orm.DefaultPoolCode).FlushDB(ctx))

MockDBClient

MockDBClient sits between Droplet ORM and database/sql. It implements DBClient; every method whose mock function is nil delegates to OriginDB, so you only override what you want to intercept:

type MockDBClient struct {
    OriginDB            DBClient
    PrepareMock         func(query string) (*sql.Stmt, error)
    ExecMock            func(query string, args ...any) (sql.Result, error)
    ExecContextMock     func(context context.Context, query string, args ...any) (sql.Result, error)
    QueryRowMock        func(query string, args ...any) *sql.Row
    QueryRowContextMock func(context context.Context, query string, args ...any) *sql.Row
    QueryMock           func(query string, args ...any) (*sql.Rows, error)
    QueryContextMock    func(context context.Context, query string, args ...any) (*sql.Rows, error)
    BeginMock           func() (*sql.Tx, error)
    CommitMock          func() error
    RollbackMock        func() error
}

Begin delegates to OriginDB.(DBClientNoTX).Begin(), so OriginDB must be the real pool client returned by GetDBClient() -- the mock wraps a live connection, it does not replace it. PrepareMock, CommitMock and RollbackMock are currently not consulted by any method.

Install it with SetMockDBClient on the pool's DB and restore the original client when the test ends:

func TestInsertFailure(t *testing.T) {
    ctx := orm.PrepareTables(t, orm.NewRegistry(), UserEntity{})

    db := ctx.Engine().DB(orm.DefaultPoolCode)
    origin := db.GetDBClient()
    defer db.SetMockDBClient(origin)

    db.SetMockDBClient(&orm.MockDBClient{
        OriginDB: origin,
        ExecMock: func(query string, args ...any) (sql.Result, error) {
            if strings.HasPrefix(query, "INSERT") {
                return nil, errors.New("simulated insert failure")
            }
            return origin.Exec(query, args...)
        },
    })

    user := entities.UserEntityProvider.New(ctx)
    user.SetName("Alice")
    err := ctx.Save(user)
    assert.EqualError(t, err, "simulated insert failure")
}

The mock also applies inside ctx.Transaction(): transactions are opened through the mocked Begin, and statements run on the returned *sql.Tx.

MockLogHandler

MockLogHandler implements LogHandler and keeps every log entry:

type MockLogHandler struct {
    Logs []map[string]any
}

func (h *MockLogHandler) Handle(_ Context, log map[string]any) // appends to Logs
func (h *MockLogHandler) Clear()                               // Logs = nil

It is the easiest way to assert how the ORM talked to MySQL or Redis -- for example that a cached read did not hit the database:

logs := &orm.MockLogHandler{}
ctx.RegisterQueryLogger(logs, orm.QueryLoggerOptions{MySQL: true})

_, err := entities.UserEntityProvider.GetByID(ctx, id)
assert.NoError(t, err)

selects := 0
for _, entry := range logs.Logs {
    if entry["operation"] == "SELECT" {
        selects++
    }
}
assert.Equal(t, 0, selects, "expected the row to come from Redis")
logs.Clear()

Because the context cache answers repeated reads on the same context, use reader := ctx.Clone(); reader.DisableContextCache() when you want to prove a read goes to Redis or MySQL.

Full Example

Assume UserEntity is defined in your application package and code generation produced the entities package with entities.UserEntity and entities.UserEntityProvider:

package myapp

import (
    "errors"
    "testing"

    "github.com/DropletLive/orm"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"

    "myapp/entities"
)

type UserEntity struct {
    ID    uint64 `orm:"redisCache"`
    Name  string `orm:"required"`
    Email string `orm:"required"`
}

func (e UserEntity) UniqueIndexes() [][]string {
    return [][]string{{"Email"}}
}

func TestUserCRUD(t *testing.T) {
    ctx := orm.PrepareTables(t, orm.NewRegistry(), UserEntity{})

    logs := &orm.MockLogHandler{}
    ctx.RegisterQueryLogger(logs, orm.QueryLoggerOptions{MySQL: true, Redis: true})

    // create
    user := entities.UserEntityProvider.New(ctx)
    user.SetName("Alice").SetEmail("alice@example.com")
    require.NoError(t, ctx.Save(user))
    assert.NotZero(t, user.GetID())

    // read on a fresh context so the identity map is not involved
    reader := ctx.Clone()
    loaded, err := entities.UserEntityProvider.GetByID(reader, user.GetID())
    require.NoError(t, err)
    assert.Equal(t, "Alice", loaded.GetName())

    // update
    loaded.SetName("Bob")
    require.NoError(t, reader.Save(loaded))

    again, err := entities.UserEntityProvider.GetByID(ctx.Clone(), user.GetID())
    require.NoError(t, err)
    assert.Equal(t, "Bob", again.GetName())

    // delete
    require.NoError(t, ctx.Delete(again))
    _, err = entities.UserEntityProvider.GetByID(ctx.Clone(), user.GetID())
    _, missing := errors.AsType[*orm.NotFoundError](err)
    assert.True(t, missing)

    assert.NotEmpty(t, logs.Logs)
}

See CRUD Operations for the generated API used above.

Edit this page
Last Updated: 11/16/26, 1:49 PM
Prev
Queries Log
Next
Migrating from fluxaorm