testing.md

Testing

This document describes the project's testing utilities and best practices.

Test helpers

Test helpers can be found in the common/testing package.

testvars package

Instead of creating identifiers like task queue name, namespace or worker identity by hand, use the testvars package.

Example:

func TestFoo(t *testing.T) {
    tv := testvars.New(t)

    req := &workflowservice.SignalWithStartWorkflowExecutionRequest{
        RequestId:    tv.Any().String(),
        Namespace:    tv.NamespaceName().String(),
        WorkflowId:   tv.WorkflowID(),
        WorkflowType: tv.WorkflowType(),
        TaskQueue:    tv.TaskQueue(),
        SignalName:   tv.SignalName(),
    }
}

Later you can assert on the generated values. testvars guarantees to provide the same value every time you call the same method.

assert.Equal(t, tv.WorkflowID(), startedWorkflow.WorkflowId)

If you need more than one value for the same entity in one test, you can use WithEntityNumber() method to get a new instance of testvars with a different value.

func TestFoo(t *testing.T) {

    tv := testvars.New(t)
    tv1 := tv.WithUpdateIDNumber(1)
    tv2 := tv.WithUpdateIDNumber(2)

    req1 := &workflowservice.UpdateWorkflowExecutionRequest{
        Namespace:         tv1.NamespaceName().String(),
        WorkflowExecution: tv1.WorkflowExecution(),
        Request: &updatepb.Request{
            Meta: &updatepb.Meta{UpdateId: tv1.UpdateID()},
            Input: &updatepb.Input{
                Name: tv1.HandlerName(),
                Args: payloads.EncodeString("args-value-of-" + tv1.UpdateID()),
            },
        },
    }

	req2 := &workflowservice.UpdateWorkflowExecutionRequest{
        Namespace:         tv2.NamespaceName().String(),
        WorkflowExecution: tv2.WorkflowExecution(),
        Request: &updatepb.Request{
            Meta: &updatepb.Meta{UpdateId: tv2.UpdateID()},
            Input: &updatepb.Input{
                Name: tv2.HandlerName(),
                Args: payloads.EncodeString("args-value-of-" + tv2.UpdateID()),
            },
        },
    }
}

If you don't care about specific value, you can use Any() method to generate a random value. It indicates that value doesn't matter for this test and will never be asserted on (but required for API, for example).

taskpoller package

For end-to-end testing, consider using taskpoller.TaskPoller to handle workflow tasks. This is useful when you need full control over the worker behavior in a way that the SDK cannot provide; or if there's no SDK support for that API available yet.

You'll find a fully initialized task poller in any functional test suite, look for s.TaskPoller.

NOTE: The previous testcore.TaskPoller has been deprecated and should not be used in new code.