temporaltest

README

The temporaltest package provides helpers for writing end to end tests against a real Temporal server which can be run via the go test command.

Backwards Compatibility

This package must not break Go API backwards compatibility in accordance with semantic versioning. One exception to this policy is the WithBaseServerOptions function, which may have breaking changes in any Temporal server release.

The base configuration (eg. dynamic config values) and behavior of TestServer may also be modified in any release. Such changes should be for the purposes of improving performance or stability for testing scenarios.

Documentation

Overview

Package temporaltest provides utilities for end to end Temporal server testing.

Index

• type TestServer
  • func NewServer(opts ...TestServerOption) *TestServer
  • func (ts *TestServer) GetDefaultClient() client.Client
  • func (ts *TestServer) GetDefaultNamespace() string
  • func (ts *TestServer) NewClientWithOptions(opts client.Options) client.Client
  • func (ts *TestServer) NewWorker(taskQueue string, registerFunc func(registry worker.Registry)) worker.Worker
  • func (ts *TestServer) NewWorkerWithOptions(taskQueue string, registerFunc func(registry worker.Registry), ...) worker.Worker
  • func (ts *TestServer) Stop()
• type TestServerOption
  • func WithBaseClientOptions(o client.Options) TestServerOption
  • func WithBaseServerOptions(options ...temporal.ServerOption) TestServerOption
  • func WithBaseWorkerOptions(o worker.Options) TestServerOption
  • func WithT(t *testing.T) TestServerOption

Examples

• NewServer

Types

type TestServer

type TestServer struct {
	// contains filtered or unexported fields
}

A TestServer is a Temporal server listening on a system-chosen port on the local loopback interface, for use in end-to-end tests.

Methods on TestServer are not safe for concurrent use.

func NewServer

func NewServer(opts ...TestServerOption) *TestServer

NewServer starts and returns a new TestServer.

If not specifying the WithT option, the caller should execute Stop when finished to close the server and release resources.

Example

package main

import (
	"context"
	"fmt"
	"testing"
	"time"

	"go.temporal.io/sdk/activity"
	"go.temporal.io/sdk/client"
	"go.temporal.io/sdk/worker"
	"go.temporal.io/sdk/workflow"

	"go.temporal.io/server/temporaltest"
)

// to be used in example code
var t *testing.T

func main() {
	// Create test Temporal server and client
	ts := temporaltest.NewServer(temporaltest.WithT(t))
	c := ts.GetDefaultClient()

	// Register a new worker on the `hello_world` task queue
	ts.NewWorker("hello_world", func(registry worker.Registry) {
		RegisterWorkflowsAndActivities(registry)
	})

	// Start test workflow
	wfr, err := c.ExecuteWorkflow(
		context.Background(),
		client.StartWorkflowOptions{TaskQueue: "hello_world"},
		Greet,
		"world",
	)
	if err != nil {
		t.Fatal(err)
	}

	// Get workflow result
	var result string
	if err := wfr.Get(context.Background(), &result); err != nil {
		t.Fatal(err)
	}

	// Print result
	fmt.Println(result)
}

// Greet implements a Temporal workflow that returns a salutation for a given subject.
func Greet(ctx workflow.Context, subject string) (string, error) {
	var greeting string
	if err := workflow.ExecuteActivity(
		workflow.WithActivityOptions(ctx, workflow.ActivityOptions{ScheduleToCloseTimeout: time.Second}),
		PickGreeting,
	).Get(ctx, &greeting); err != nil {
		return "", err
	}

	return fmt.Sprintf("%s %s", greeting, subject), nil
}

// PickGreeting is a Temporal activity that returns some greeting text.
func PickGreeting(ctx context.Context) (string, error) {
	return "Hello", nil
}

func HandleIntercept(ctx context.Context) (string, error) {
	return "Ok", nil
}

func RegisterWorkflowsAndActivities(r worker.Registry) {
	r.RegisterWorkflow(Greet)
	r.RegisterActivity(PickGreeting)
	r.RegisterActivityWithOptions(HandleIntercept, activity.RegisterOptions{Name: "HandleIntercept"})
}

Output:

Hello world

func (*TestServer) GetDefaultClient

func (ts *TestServer) GetDefaultClient() client.Client

GetDefaultClient returns the default Temporal client configured for making requests to the server.

It is configured to use a pre-registered test namespace and will be closed on TestServer.Stop.

func (*TestServer) GetDefaultNamespace

func (ts *TestServer) GetDefaultNamespace() string

GetDefaultNamespace returns the randomly generated namespace which has been pre-registered with the test server.

func (*TestServer) NewClientWithOptions

func (ts *TestServer) NewClientWithOptions(opts client.Options) client.Client

NewClientWithOptions returns a new Temporal client configured for making requests to the server.

If no namespace option is set it will use a pre-registered test namespace. The returned client will be closed on TestServer.Stop.

func (*TestServer) NewWorker

func (ts *TestServer) NewWorker(taskQueue string, registerFunc func(registry worker.Registry)) worker.Worker

NewWorker registers and starts a Temporal worker on the specified task queue.

func (*TestServer) NewWorkerWithOptions

func (ts *TestServer) NewWorkerWithOptions(taskQueue string, registerFunc func(registry worker.Registry), opts worker.Options) worker.Worker

NewWorkerWithOptions returns a Temporal worker on the specified task queue.

WorkflowPanicPolicy is always set to worker.FailWorkflow so that workflow executions fail fast when workflow code panics or detects non-determinism.

func (*TestServer) Stop

func (ts *TestServer) Stop()

Stop closes test clients and shuts down the server.

type TestServerOption

type TestServerOption interface {
	// contains filtered or unexported methods
}

func WithBaseClientOptions

func WithBaseClientOptions(o client.Options) TestServerOption

WithBaseClientOptions configures options for the default clients and workers connected to the test server.

func WithBaseServerOptions

func WithBaseServerOptions(options ...temporal.ServerOption) TestServerOption

WithBaseServerOptions enables configuring additional server options not directly exposed via temporaltest.

func WithBaseWorkerOptions

func WithBaseWorkerOptions(o worker.Options) TestServerOption

WithBaseWorkerOptions configures default options for workers connected to the test server.

WorkflowPanicPolicy is always set to worker.FailWorkflow so that workflow executions fail fast when workflow code panics or detects non-determinism.

func WithT

func WithT(t *testing.T) TestServerOption

WithT directs all worker and client logs to the test logger.

If this option is specified, then server will automatically be stopped when the test completes.