服务注册与分布式协调 / 系统课时
为 Workflow 编写单元测试
为 Workflow 编写单元测试
Workflow 的主要风险往往不在单个函数计算,而在“哪个 Activity 被调用、失败后走哪条分支、最终状态是什么”。本课使用 Temporal Go SDK testsuite 在内存环境执行 Workflow,通过 Activity Mock 注入成功与失败结果,并断言返回值、错误和状态变化。
学习目标
- 使用
testsuite.WorkflowTestSuite创建隔离的 Workflow 测试环境。 - Mock Activity,分别覆盖成功路径和确定失败路径。
- 使用
GetWorkflowResult、GetWorkflowError与业务状态历史验证编排逻辑。
测试环境应该隔离外部副作用
TestWorkflowEnvironment 会在测试进程内执行 Workflow 逻辑,适合快速验证分支、Timer、Signal、Activity 调用和返回结果。单元测试阶段应优先 Mock 会访问数据库、HTTP 或消息系统的 Activity,否则测试虽然仍能运行,却会把编排测试变成不稳定的集成测试。
每个测试都新建环境,不共享前一个用例的 Mock 或 Workflow 状态。成功和失败场景也应拆开断言:成功路径关心结果与状态轨迹,失败路径关心错误是否被 Workflow 正确暴露,以及后续步骤是否没有被误执行。
建立一个可观察的 Workflow
下面是片段示例:order.go 把状态更新放在 Workflow 内,并将最终状态与状态轨迹作为结果返回;它依赖下一节的 order_test.go 才构成本课完整可运行示例。Charge 只是 Activity 签名,测试会通过 Mock 替换其行为,因此不会访问真实支付服务。
package order
import (
"context"
"time"
"go.temporal.io/sdk/workflow"
)
type OrderResult struct {
Status string
History []string
}
func Charge(context.Context, string) error { return nil }
func OrderWorkflow(ctx workflow.Context, orderID string) (OrderResult, error) {
result := OrderResult{
Status: "CREATED",
History: []string{"CREATED"},
}
if err := workflow.SetQueryHandler(ctx, "status", func() string {
return result.Status
}); err != nil {
return result, err
}
ctx = workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
StartToCloseTimeout: time.Minute,
})
result.Status = "CHARGING"
result.History = append(result.History, result.Status)
if err := workflow.ExecuteActivity(ctx, Charge, orderID).Get(ctx, nil); err != nil {
result.Status = "FAILED"
result.History = append(result.History, result.Status)
return result, err
}
result.Status = "COMPLETED"
result.History = append(result.History, result.Status)
return result, nil
}这个例子故意让状态变化成为可断言数据,而不是依赖日志字符串。生产代码也可以通过 Query、Search Attribute 或独立审计记录暴露状态,但单元测试应优先断言稳定的业务结果,不要把日志文本当作协议。
Mock Activity 并断言两条路径
测试文件创建两个独立环境。成功用例让 Charge 返回 nil,然后读取 Workflow 结果;失败用例返回不可重试的业务错误,避免测试为了演示错误分支而等待 Activity 重试。下面的 order_test.go 与上一节的 order.go 共同构成完整可运行示例。
package order
import (
"testing"
"github.com/stretchr/testify/mock"
"github.com/stretchr/testify/require"
"go.temporal.io/sdk/temporal"
"go.temporal.io/sdk/testsuite"
)
func newWorkflowEnv() *testsuite.TestWorkflowEnvironment {
var suite testsuite.WorkflowTestSuite
return suite.NewTestWorkflowEnvironment()
}
func TestOrderWorkflowSuccess(t *testing.T) {
env := newWorkflowEnv()
env.OnActivity(Charge, mock.Anything, "order-42").Return(nil).Once()
env.ExecuteWorkflow(OrderWorkflow, "order-42")
require.True(t, env.IsWorkflowCompleted())
require.NoError(t, env.GetWorkflowError())
var got OrderResult
require.NoError(t, env.GetWorkflowResult(&got))
require.Equal(t, "COMPLETED", got.Status)
require.Equal(t, []string{"CREATED", "CHARGING", "COMPLETED"}, got.History)
env.AssertExpectations(t)
}
func TestOrderWorkflowChargeRejected(t *testing.T) {
env := newWorkflowEnv()
env.OnActivity(Charge, mock.Anything, "order-42").
Return(temporal.NewNonRetryableApplicationError(
"card declined",
"PaymentRejected",
nil,
)).Once()
env.ExecuteWorkflow(OrderWorkflow, "order-42")
require.True(t, env.IsWorkflowCompleted())
require.Error(t, env.GetWorkflowError())
require.Contains(t, env.GetWorkflowError().Error(), "card declined")
env.AssertExpectations(t)
}将两个文件置于同一 package 后执行:
go test ./...预期输出:
ok <PATH> <TIME><PATH> 和 <TIME> 会随项目与机器变化。若失败用例意外触发了额外 Activity,AssertExpectations 或调用次数约束会直接让测试失败,这比只断言“最后有一个 error”更能发现编排逻辑回归。
让测试覆盖行为而不是实现细节
优先断言业务可观察行为:Workflow 是否完成、返回结果是否正确、错误类型或错误语义是否正确、关键 Activity 是否按预期调用。不要把内部局部变量、日志行数或无关的调用顺序都写进断言,否则一次安全重构也会制造大量假失败。
Timer、Signal、Update 和长时间等待同样可以在 testsuite 中测试,但应为它们单独增加场景,而不是把所有机制塞进一个巨大用例。保持“一条业务路径一个测试”的粒度,才能让失败信息直接指向编排规则本身。