testutil

README

Testing Utilities

This package provides utilities to help with testing, particularly for tests that require external dependencies like Redis and Kafka.

Docker Container Management

The docker.go file contains utilities for starting and stopping Docker containers for Redis and Kafka, making it easy to run integration tests without needing manual setup of these services.

Available Functions

Basic Container Management

• StartRedisContainer(ctx context.Context) (*DockerContainer, error) - Starts a Redis container and waits for it to be ready.
• StartKafkaContainer(ctx context.Context) (*DockerContainer, error) - Starts a Kafka container (and a linked Zookeeper container) and waits for it to be ready.
• (*DockerContainer) Stop(ctx context.Context) error - Stops and removes a Docker container.

Test Helpers

• WithRedisOnly(t TestingT, testFunc func(redisAddr string)) - Runs a test with only Redis dependency.
• WithKafkaOnly(t TestingT, testFunc func(kafkaAddr string)) - Runs a test with only Kafka dependency.
• WithTestDependencies(t TestingT, testFunc func(redisAddr, kafkaAddr string)) - Runs a test with both Redis and Kafka dependencies.

Flexible Dependency Management

For more flexibility, use the WithDependencies function that lets you specify which dependencies your test needs:

WithDependencies(t, depType DependencyType, testFunc interface{})

The DependencyType can be:

• NoDependencies - For tests without external dependencies
• RedisOnly - For tests requiring only Redis
• KafkaOnly - For tests requiring only Kafka
• RedisAndKafka - For tests requiring both Redis and Kafka

The testFunc parameter should be a function matching the dependency type:

• func() for NoDependencies
• func(redisAddr string) for RedisOnly
• func(kafkaAddr string) for KafkaOnly
• func(redisAddr, kafkaAddr string) for RedisAndKafka

Usage Examples

Basic usage with Redis only:

func TestWithRedis(t *testing.T) {
    testutil.WithRedisOnly(t, func(redisAddr string) {
        // Connect to Redis using redisAddr
        client := redis.NewClient(&redis.Options{
            Addr: redisAddr,
        })
        defer client.Close()
        
        // Run your test...
    })
}

Using the flexible dependency manager:

func TestFlexibleDependencies(t *testing.T) {
    testutil.WithDependencies(t, testutil.RedisAndKafka, func(redisAddr, kafkaAddr string) {
        // Connect to Redis and Kafka
        // Run your test...
    })
}

Dependency Checks

The dependencies.go file provides functions to skip tests if required dependencies are not available:

• SkipIfRedisUnavailable(t *testing.T, redisAddr string) - Skip test if Redis is not available
• SkipIfKafkaUnavailable(t *testing.T, kafkaAddr string) - Skip test if Kafka is not available
• SkipIfDependenciesUnavailable(t *testing.T, redisAddr, kafkaAddr string) - Skip test if either dependency is unavailable

These functions are useful for tests that expect the services to be already running, rather than starting the services themselves.

Documentation

Index

• func RunIntegrationTest(t interface{ ... }, testFunc func(redisAddr, kafkaAddr string))
• func SkipIfDependenciesUnavailable(t *testing.T, redisAddr, kafkaAddr string)
• func SkipIfKafkaUnavailable(t *testing.T, kafkaAddr string)
• func SkipIfRedisUnavailable(t *testing.T, redisAddr string)
• func WithDependencies(t interface{ ... }, depType DependencyType, testFunc interface{})
• func WithKafkaOnly(t interface{ ... }, testFunc func(kafkaAddr string))
• func WithRedisOnly(t interface{ ... }, testFunc func(redisAddr string))
• func WithTestDependencies(t interface{ ... }, testFunc func(redisAddr, kafkaAddr string))
• type DependencyType
• type DockerContainer
  • func StartKafkaContainer(ctx context.Context) (*DockerContainer, error)
  • func StartRedisContainer(ctx context.Context) (*DockerContainer, error)
  • func (c *DockerContainer) Stop(ctx context.Context) error

Functions

func RunIntegrationTest

func RunIntegrationTest(t interface {
	Helper()
	Skip(args ...interface{})
	Cleanup(f func())
	Errorf(format string, args ...interface{})
	Logf(format string, args ...interface{})
}, testFunc func(redisAddr, kafkaAddr string))

RunIntegrationTest runs an integration test with both Redis and Kafka containers, configuring them for the matchingo integration testing. This is specifically designed for integration tests that need to verify the end-to-end functionality.

func SkipIfDependenciesUnavailable

func SkipIfDependenciesUnavailable(t *testing.T, redisAddr, kafkaAddr string)

SkipIfDependenciesUnavailable skips the test if either Redis or Kafka is unavailable

func SkipIfKafkaUnavailable

func SkipIfKafkaUnavailable(t *testing.T, kafkaAddr string)

SkipIfKafkaUnavailable skips the test if Kafka is unavailable on the specified address

func SkipIfRedisUnavailable

func SkipIfRedisUnavailable(t *testing.T, redisAddr string)

SkipIfRedisUnavailable skips the test if Redis is unavailable on the specified address

func WithDependencies

func WithDependencies(t interface {
	Helper()
	Skip(args ...interface{})
	Cleanup(f func())
	Errorf(format string, args ...interface{})
}, depType DependencyType, testFunc interface{})

WithDependencies runs a test with the specified dependencies. It automatically sets up and tears down the required containers.

func WithKafkaOnly

func WithKafkaOnly(t interface {
	Helper()
	Skip(args ...interface{})
	Cleanup(f func())
	Errorf(format string, args ...interface{})
}, testFunc func(kafkaAddr string))

WithKafkaOnly runs a test function with only Kafka dependency It starts the Kafka container, runs the test, then stops the container regardless of the test outcome

func WithRedisOnly

func WithRedisOnly(t interface {
	Helper()
	Skip(args ...interface{})
	Cleanup(f func())
	Errorf(format string, args ...interface{})
}, testFunc func(redisAddr string))

WithRedisOnly runs a test function with only Redis dependency It starts the Redis container, runs the test, then stops the container regardless of the test outcome

func WithTestDependencies

func WithTestDependencies(t interface {
	Helper()
	Skip(args ...interface{})
	Cleanup(f func())
	Errorf(format string, args ...interface{})
}, testFunc func(redisAddr, kafkaAddr string))

WithTestDependencies runs a test function with Redis and Kafka dependencies It starts the containers, runs the test, then stops the containers regardless of test outcome

Types

type DependencyType

type DependencyType int

DependencyType specifies which dependencies are needed for a test

const (
	// NoDependencies indicates that no external dependencies are needed
	NoDependencies DependencyType = iota
	// RedisOnly indicates that only Redis is needed
	RedisOnly
	// KafkaOnly indicates that only Kafka is needed
	KafkaOnly
	// RedisAndKafka indicates that both Redis and Kafka are needed
	RedisAndKafka
)

type DockerContainer

type DockerContainer struct {
	ID        string
	Name      string
	Type      string
	Port      string
	HostPort  string
	StartedAt time.Time
}

DockerContainer represents a Docker container used for testing

func StartKafkaContainer

func StartKafkaContainer(ctx context.Context) (*DockerContainer, error)

StartKafkaContainer starts a Kafka container for testing

func StartRedisContainer

func StartRedisContainer(ctx context.Context) (*DockerContainer, error)

StartRedisContainer starts a Redis container for testing

func (*DockerContainer) Stop

func (c *DockerContainer) Stop(ctx context.Context) error

Stop stops and removes the Docker container