temporalio__skill-temporal-developer/references/go/testing.md

Go SDK Testing

Overview

The Go SDK provides the testsuite package for testing Workflows and Activities. It uses the testify library for assertions (assert/require) and mocking (mock). The test environment supports automatic time-skipping for Workflows with timers.

Test Environment Setup

Two approaches: struct-based with suite.Suite or function-based with testsuite.NewTestWorkflowEnvironment().

Approach 1: Struct-based (testify suite)

package sample

import (
	"testing"

	"github.com/stretchr/testify/mock"
	"github.com/stretchr/testify/suite"

	"go.temporal.io/sdk/testsuite"
)

type UnitTestSuite struct {
	suite.Suite
	testsuite.WorkflowTestSuite

	env *testsuite.TestWorkflowEnvironment
}

func (s *UnitTestSuite) SetupTest() {
	s.env = s.NewTestWorkflowEnvironment()
}

func (s *UnitTestSuite) AfterTest(suiteName, testName string) {
	s.env.AssertExpectations(s.T())
}

func (s *UnitTestSuite) Test_MyWorkflow_Success() {
	s.env.ExecuteWorkflow(MyWorkflow, "input")

	s.True(s.env.IsWorkflowCompleted())
	s.NoError(s.env.GetWorkflowError())
}

func TestUnitTestSuite(t *testing.T) {
	suite.Run(t, new(UnitTestSuite))
}

Approach 2: Function-based

package sample

import (
	"testing"

	"github.com/stretchr/testify/assert"
	"go.temporal.io/sdk/testsuite"
)

func Test_MyWorkflow(t *testing.T) {
	testSuite := &testsuite.WorkflowTestSuite{}
	env := testSuite.NewTestWorkflowEnvironment()
	env.RegisterActivity(MyActivity)

	env.ExecuteWorkflow(MyWorkflow, "input")
	assert.True(t, env.IsWorkflowCompleted())
	assert.NoError(t, env.GetWorkflowError())

	var result string
	assert.NoError(t, env.GetWorkflowResult(&result))
	assert.Equal(t, "expected", result)
}

You must register all Activity Definitions used by the Workflow with env.RegisterActivity(ActivityFunc). The Workflow itself does not need to be registered.

Activity Mocking

Mock activities with env.OnActivity() to test Workflow logic in isolation.

Return mock values:

env.OnActivity(MyActivity, mock.Anything, mock.Anything).Return("mock_result", nil)

Return a function replacement (for parameter validation or custom logic):

env.OnActivity(MyActivity, mock.Anything, mock.Anything).Return(
	func(ctx context.Context, input string) (string, error) {
		// Custom logic, assertions, etc.
		return "computed_result", nil
	},
)

Match specific arguments:

env.OnActivity(MyActivity, mock.Anything, "specific_input").Return("result", nil)

When using mocks, you do not need to call env.RegisterActivity() for that Activity. The mock signature must match the original Activity function signature.

Testing Signals and Queries

Use RegisterDelayedCallback to send Signals during Workflow execution. Use QueryWorkflow to test query handlers.

func (s *UnitTestSuite) Test_SignalsAndQueries() {
	// Register a delayed callback to send a signal after 5 seconds
	s.env.RegisterDelayedCallback(func() {
		s.env.SignalWorkflow("approve", SignalData{Approved: true})
	}, time.Second*5)

	s.env.ExecuteWorkflow(ApprovalWorkflow, input)

	s.True(s.env.IsWorkflowCompleted())
	s.NoError(s.env.GetWorkflowError())
}

Query a running Workflow (must be called inside RegisterDelayedCallback or after ExecuteWorkflow):

s.env.RegisterDelayedCallback(func() {
	res, err := s.env.QueryWorkflow("getProgress")
	s.NoError(err)

	var progress int
	err = res.Get(&progress)
	s.NoError(err)
	s.Equal(50, progress)
}, time.Second*10+time.Millisecond)

QueryWorkflow returns a converter.EncodedValue. Use .Get(&result) to decode the value.

For "Signal-With-Start" testing, set the delay to 0.

Testing Failure Cases

func (s *UnitTestSuite) Test_WorkflowFailure() {
	// Mock activity to return an error
	s.env.OnActivity(MyActivity, mock.Anything, mock.Anything).Return(
		"", errors.New("activity failed"))

	s.env.ExecuteWorkflow(MyWorkflow, "input")

	s.True(s.env.IsWorkflowCompleted())

	err := s.env.GetWorkflowError()
	s.Error(err)

	var applicationErr *temporal.ApplicationError
	s.True(errors.As(err, &applicationErr))
	s.Equal("activity failed", applicationErr.Error())
}

env.GetWorkflowError() returns the Workflow error. Use errors.As(err, &applicationErr) to check the error type. Mock activities returning errors to test Workflow error-handling paths.

Replay Testing

Use worker.NewWorkflowReplayer() to verify that code changes do not break determinism. Load history from a JSON file exported via the Temporal CLI or Web UI.

package sample

import (
	"testing"

	"github.com/stretchr/testify/assert"
	"go.temporal.io/sdk/worker"
)

func Test_ReplayFromFile(t *testing.T) {
	replayer := worker.NewWorkflowReplayer()
	replayer.RegisterWorkflow(MyWorkflow)

	err := replayer.ReplayWorkflowHistoryFromJSONFile(nil, "my_workflow_history.json")
	assert.NoError(t, err)
}

Export history via CLI: temporal workflow show --workflow-id <id> --output json > history.json

Replay from a programmatically fetched history:

func Test_ReplayFromServer(t *testing.T) {
	// Fetch history from the server
	hist, err := GetWorkflowHistory(ctx, client, workflowID, runID)
	assert.NoError(t, err)

	replayer := worker.NewWorkflowReplayer()
	replayer.RegisterWorkflow(MyWorkflow)

	err = replayer.ReplayWorkflowHistory(nil, hist)
	assert.NoError(t, err)
}

Activity Testing

Test Activities in isolation using TestActivityEnvironment. No Worker or Workflow needed.

func Test_MyActivity(t *testing.T) {
	testSuite := &testsuite.WorkflowTestSuite{}
	env := testSuite.NewTestActivityEnvironment()
	env.RegisterActivity(MyActivity)

	val, err := env.ExecuteActivity(MyActivity, "input")
	assert.NoError(t, err)

	var result string
	assert.NoError(t, val.Get(&result))
	assert.Equal(t, "expected_output", result)
}

ExecuteActivity returns (converter.EncodedValue, error). Use val.Get(&result) to extract the typed result. The Activity executes synchronously in the calling goroutine.

Best Practices

1. Register all Activities used by the Workflow with env.RegisterActivity(), unless you mock them with env.OnActivity()
2. Use mocks to isolate Workflow logic from Activity implementations
3. Test failure paths by mocking Activities that return errors
4. Use replay testing before deploying Workflow code changes to catch non-determinism errors
5. Use unique task queues per test when running integration tests
6. Call env.AssertExpectations(s.T()) in AfterTest to verify all mocks were called