Documentation
¶
Overview ¶
Package testcontainer provides utilities for running Temporal server in Docker containers for integration testing.
This package makes it easy to start a Temporal server container, connect to it, and clean up resources after testing. It's designed to be framework-agnostic and can be used in any Go testing scenario.
Basic Usage ¶
The simplest way to use this package is with the Setup function, which handles container startup, client creation, and cleanup:
import (
"context"
"testing"
"github.com/jasoet/pkg/v3/temporal"
"github.com/jasoet/pkg/v3/temporal/testcontainer"
)
func TestMyWorkflow(t *testing.T) {
ctx := context.Background()
// Start container and create client
container, client, cleanup, err := testcontainer.Setup(
ctx,
testcontainer.ClientConfig{Namespace: "default"},
testcontainer.Options{Logger: t},
)
if err != nil {
t.Fatalf("Setup failed: %v", err)
}
defer cleanup()
// Use client for your tests...
// client.ExecuteWorkflow(...)
}
Advanced Usage ¶
For more control, you can start the container and create the client separately:
func TestAdvanced(t *testing.T) {
ctx := context.Background()
// Start container with custom options
container, err := testcontainer.Start(ctx, testcontainer.Options{
Image: "temporalio/temporal:1.22.0",
StartupTimeout: 120 * time.Second,
Logger: t,
})
if err != nil {
t.Fatalf("Failed to start container: %v", err)
}
defer container.Terminate(ctx)
// Create client manually
client, err := temporal.NewClient(temporal.WithHostPort(container.HostPort()))
if err != nil {
t.Fatalf("Failed to create client: %v", err)
}
defer client.Close()
// Run tests...
}
Configuration Options ¶
The Options struct allows you to customize the container:
- Image: Docker image to use (default: "temporalio/temporal:latest")
- StartupTimeout: How long to wait for container startup (default: 60s)
- Logger: Optional logger for container events (can be *testing.T)
- ExtraPorts: Additional ports to expose
- InitialWaitTime: Extra time to wait after startup (default: 3s)
Logging ¶
You can pass any type that implements the Logger interface (including *testing.T):
opts := testcontainer.Options{
Logger: t, // *testing.T implements Logger
}
Or implement your own:
type MyLogger struct{}
func (l *MyLogger) Logf(format string, args ...interface{}) {
fmt.Printf(format+"\n", args...)
}
Using in Other Projects ¶
This package is designed to be imported and used in any Go project:
go get github.com/jasoet/pkg/v3/temporal/testcontainer
Then import and use in your tests:
import "github.com/jasoet/pkg/v3/temporal/testcontainer"
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ClientConfig ¶
type ClientConfig struct {
// Namespace is the Temporal namespace to use.
// Default: "default"
Namespace string
}
ClientConfig holds the configuration for creating a Temporal client. The connection address is taken from the started container, so no host/port is configured here.
type Container ¶
type Container struct {
testcontainers.Container
// contains filtered or unexported fields
}
Container represents a running Temporal server test container.
func Setup ¶
func Setup(ctx context.Context, config ClientConfig, opts Options) (*Container, client.Client, func(), error)
Setup is a convenience function that: 1. Starts a Temporal test container 2. Creates a Temporal client configured to connect to the container 3. Returns a cleanup function that closes the client and terminates the container
This function is ideal for integration tests where you need both container and client.
Example:
container, client, cleanup, err := testcontainer.Setup(ctx, testcontainer.ClientConfig{
Namespace: "default",
}, testcontainer.Options{})
if err != nil {
t.Fatalf("Setup failed: %v", err)
}
defer cleanup()
// Use client for your tests...
func Start ¶
Start creates and starts a Temporal server container for testing. It returns a Container instance that can be used to connect to the server.
type Logger ¶
type Logger interface {
Logf(format string, args ...interface{})
}
Logger is an interface for logging within the testcontainer package. This allows users to provide their own logger implementation (e.g., *testing.T, zerolog, etc.) or pass nil for no logging.
type Options ¶
type Options struct {
// Image is the Docker image to use for Temporal server.
// Default: "temporalio/temporal:latest"
Image string
// StartupTimeout is the maximum time to wait for the container to be ready.
// Default: 60 seconds
StartupTimeout time.Duration
// Logger is an optional logger for container events.
// If nil, no logging will be performed.
Logger Logger
// ExtraPorts are additional ports to expose from the container.
// By default, ports 7233 (gRPC) and 8233 (Web UI) are exposed.
ExtraPorts []string
// InitialWaitTime is the additional time to wait after container starts
// to ensure Temporal is fully initialized.
// Default: 3 seconds
InitialWaitTime time.Duration
}
Options configures the Temporal test container.
Source Files