The Test Compatibility Kit (TCK) is a standardized test suite for validating storage implementations in the Fiber Storage repository. It provides a comprehensive set of tests that ensure all storage backends behave consistently and correctly implement the storage.Storage interface.

Overview

The TCK leverages testify/suite to provide a structured testing approach with setup/teardown hooks and consistent test execution. It automatically tests all core storage operations including:

Basic CRUD operations (Set, Get, Delete)
Context-aware operations (SetWithContext, GetWithContext, etc.)
TTL (Time-To-Live) functionality
Storage reset and cleanup
Connection handling for stores that implement StorageWithConn

Why Use the TCK?

Consistency: Ensures all storage implementations behave identically
Completeness: Tests all required storage interface methods
Maintenance: Reduces test code duplication across storage implementations
Quality: Provides comprehensive edge case and error condition testing
Integration: Works seamlessly with testcontainers for isolated testing

Core Concepts

TCKSuite Interface

To use the TCK, you must implement the TCKSuite interface:

// TCKSuite is the interface that must be implemented by the test suite.
// It defines how to create a new store with a container.
// The generic parameters are the storage type, the driver type returned by the Conn method,
// and the container type used to back the storage.
//
// IMPORTANT: The container type must exist as a Testcontainers module.
// Please refer to the [testcontainers] package for more information.
type TCKSuite[T storage.Storage, D any, C testcontainers.Container] interface {
	// NewStore is a function that returns a new store.
	// It is called by the [New] function to create a new store.
	NewStore() func(ctx context.Context, tb testing.TB, ctr C) (T, error)

	// NewContainer is a function that returns a new container.
	// It is called by the [New] function to create a new container.
	NewContainer() func(ctx context.Context, tb testing.TB) (C, error)
}

Generic Parameters:

T: Your concrete storage type (e.g., *mysql.Storage)
D: The driver type returned by Conn() method (e.g., *sql.DB)
C: The testcontainer type (e.g., *mysql.MySQLContainer)

Please verify that a suitable Testcontainers module exists for your container type. See the Testcontainers modules catalog for details.

Test Execution Modes

The TCK supports two execution modes:

PerTest (default): Creates a new container and storage instance for each test
PerSuite: Creates one container and storage instance for the entire test suite

Implementation Guide: Example

Here's how to implement TCK tests for a new storage backend:

Step 1: Define Your TCK Implementation

// ExampleStorageTCK is the test suite for the Example storage.
type ExampleStorageTCK struct{}

// NewStore is a function that returns a new Example storage.
// It implements the [tck.TCKSuite] interface, allowing the TCK to create a new Example storage
// from the container created by the TCK.
func (s *ExampleStorageTCK) NewStore() func(ctx context.Context, tb testing.TB, ctr *ExampleContainer) (*Storage, error) {
    return func(ctx context.Context, tb testing.TB, ctr *example.Container) (*Storage, error) {
        // Use container APIs to get connection details
        conn, err := ctr.ConnectionString(ctx)
        require.NoError(tb, err)

        store := New(Config{
            // Apply the storage-specific configuration
            ConnectionURI: conn,
            Reset:         true,
        })

        return store, nil
    }
}

// NewContainer is a function that returns a new Example container.
// It implements the [tck.TCKSuite] interface, allowing the TCK to create a new Example container
// for the Example storage.
func (s *ExampleStorageTCK) NewContainer() func(ctx context.Context, tb testing.TB) (*example.Container, error) {
    return func(ctx context.Context, tb testing.TB) (*example.Container, error) {
        return mustStartExample(tb), nil
    }
}

Step 2: Implement Container Creation

Create a helper function to start your storage backend's container:

func mustStartExample(t testing.TB) *example.Container {
    img := exampleImage
    if imgFromEnv := os.Getenv(exampleImageEnvVar); imgFromEnv != "" {
        img = imgFromEnv
    }

    ctx := context.Background()

    c, err := example.Run(ctx, img,
        example.WithOptionA("valueA"),
        example.WithOptionB("valueB"),
        testcontainers.WithWaitStrategy(
            wait.ForListeningPort("examplePort/tcp"),
        ),
    )
    testcontainers.CleanupContainer(t, c)
    require.NoError(t, err)

    return c
}

Step 3: Create and Run the TCK Test

func TestExampleStorageTCK(t *testing.T) {
    // Create the TCK suite with proper generic type parameters
    s, err := tck.New[*ExampleStorage, *ExampleDriver, *ExampleContainer](
        context.Background(), 
        t, 
        &ExampleStorageTCK{}, 
        tck.PerTest(), // or tck.PerSuite() for suite-level containers
    )
    require.NoError(t, err)

    // Run all TCK tests
    suite.Run(t, s)
}

Key Implementation Guidelines

1. Generic Type Parameters

When calling tck.New, specify the correct type parameters:

T: Your storage pointer type (e.g., *Storage)
D: The driver type returned by Conn() (or any if not applicable)
C: The container type returned by NewContainer()

2. Error Handling

Always use require.NoError(tb, err) in your factory functions to ensure test failures are properly reported.

3. Container Cleanup

The TCK handles container cleanup, but ensure your mustStart* helpers call testcontainers.CleanupContainer(t, container). For ad‑hoc tests outside the TCK, call CleanupContainer to avoid leaving containers running until the test process exits. Although Ryuk will prune them, it’s better to clean up immediately.

4. Configuration

Configure your storage with appropriate test settings:

Enable Reset: true if your storage supports it
Use test-specific database/namespace names
Configure appropriate timeouts and connection limits

5. Context Handling

Always respect the provided context.Context in your factory functions, especially for container startup and storage initialization.

Testing Different Scenarios

PerTest Mode (Recommended)

Use when you need complete isolation between tests:

s, err := tck.New[*Storage, *sql.DB](ctx, t, &ExampleStorageTCK{}, tck.PerTest())

Pros:

Complete test isolation
No cross-test contamination
Easier debugging of individual test failures

Cons:

Slower execution due to container startup overhead
Higher resource usage, although mitigated by Testcontainers' cleanup mechanism

PerSuite Mode

Use when container startup is expensive and tests can share state:

s, err := tck.New[*Storage, *sql.DB](ctx, t, &ExampleStorageTCK{}, tck.PerSuite())