dd_sdk_go_testing

README

Datadog SDK for Go testing

This SDK is part of Datadog's CI Visibility product, currently in beta.

Getting Started

Installing

Installation of the Datadog Go testing SDK is done via go get:

go get -u github.com/DataDog/dd-sdk-go-testing

Requires:

• Go >= 1.12
• Datadog's Trace Agent >= 5.21.1

Instrumenting your tests

To instrument tests that use Go's native testing package, you have to call ddtesting.Run(m) in your TestMain function, and call ddtesting.StartTest(t) or ddtesting.StartTestWithContext(ctx, t) and defer finish() on each test.

For example:

package go_sdk_sample

import (
	"os"
	"testing"

	ddtesting "github.com/DataDog/dd-sdk-go-testing"
)

func TestMain(m *testing.M) {
	os.Exit(ddtesting.Run(m))
}

// Simple test without `context` usage
func TestSimpleExample(t *testing.T) {
	_, finish := ddtesting.StartTest(t)
	defer finish()

	// Test code...
}

// Test with subtests using `StartTestWithContext`
func TestExampleWithSubTests(t *testing.T) {
	ctx, finish := ddtesting.StartTest(t)
	defer finish()

	testCases := []struct {
		name string
	}{
		{"Sub01"},
		{"Sub02"},
		{"Sub03"},
		{"Sub04"},
		{"Sub05"},
	}

	for _, tc := range testCases {
		t.Run(tc.name, func(t *testing.T) {
			_, finish := ddtesting.StartTestWithContext(ctx, t)
			defer finish()

			// Test code ...
		})
	}
}

Note that after this, you can use ctx to refer to the context of the running test, which has information about its trace. Use it when you make any external call to see the traces within the test span.

For example:

package go_sdk_sample

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"os"
	"testing"

	ddtesting "github.com/DataDog/dd-sdk-go-testing"
	ddhttp "gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http"
	ddtracer "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func TestMain(m *testing.M) {
	os.Exit(ddtesting.Run(m))
}

func TestWithExternalCalls(t *testing.T) {
	ctx, finish := ddtesting.StartTest(t)
	defer finish()

	s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello World"))
	}))
	defer s.Close()

	t.Run("default", func(t *testing.T) {
		ctx, finish := ddtesting.StartTestWithContext(ctx, t)
		defer finish()

		rt := ddhttp.WrapRoundTripper(http.DefaultTransport)
		client := &http.Client{
			Transport: rt,
		}

		req, err := http.NewRequest("GET", s.URL+"/hello/world", nil)
		if err != nil {
			t.FailNow()
		}

		req = req.WithContext(ctx)

		client.Do(req)
	})

	t.Run("custom-name", func(t *testing.T) {
		ctx, finish := ddtesting.StartTestWithContext(ctx, t)
		defer finish()

		span, _ := ddtracer.SpanFromContext(ctx)

		customNamer := func(req *http.Request) string {
			value := fmt.Sprintf("%s %s", req.Method, req.URL.Path)
			span.SetTag("customNamer.Value", value)
			return value
		}

		rt := ddhttp.WrapRoundTripper(http.DefaultTransport, ddhttp.RTWithResourceNamer(customNamer))
		client := &http.Client{
			Transport: rt,
		}

		req, err := http.NewRequest("GET", s.URL+"/hello/world", nil)
		if err != nil {
			t.FailNow()
		}

		req = req.WithContext(ctx)

		client.Do(req)
	})
}

Environment variables

The following environment variables set the configuration options of the sdk:

Name	Description	Default	Example
DD_SERVICE	Name of the service or library under test.	The repository name	my-go-app
DD_ENV	Name of the environment where tests are being run.	none	ci, local
DD_AGENT_HOST	Datadog Agent host for trace collection	localhost
DD_TRACE_AGENT_PORT	Datadog Agent port for trace collection	8126

License

This work is dual-licensed under Apache 2.0 or BSD3.

Apache License, v2.0

BSD, v3.0

Documentation

Index

• func Run(m *testing.M, opts ...tracer.StartOption) int
• type FinishFunc
  • func StartTest(tb TB, opts ...Option) (context.Context, FinishFunc)
  • func StartTestWithContext(ctx context.Context, tb TB, opts ...Option) (context.Context, FinishFunc)
• type Option
  • func WithIncrementSkipFrame() Option
  • func WithSkipFrames(skip int) Option
  • func WithSpanOptions(opts ...ddtrace.StartSpanOption) Option
• type TB

Functions

func Run

func Run(m *testing.M, opts ...tracer.StartOption) int

Run is a helper function to run a `testing.M` object and gracefully stopping the tracer afterwards

Types

type FinishFunc

type FinishFunc func()

FinishFunc closes a started span and attaches test status information.

func StartTest

func StartTest(tb TB, opts ...Option) (context.Context, FinishFunc)

StartTest returns a new span with the given testing.TB interface and options. It uses tracer.StartSpanFromContext function to start the span with automatically detected information.

func StartTestWithContext

func StartTestWithContext(ctx context.Context, tb TB, opts ...Option) (context.Context, FinishFunc)

StartTestWithContext returns a new span with the given testing.TB interface and options. It uses tracer.StartSpanFromContext function to start the span with automatically detected information.

type Option

type Option func(*config)

Option represents an option that can be passed to NewServeMux or WrapHandler.

func WithIncrementSkipFrame

func WithIncrementSkipFrame() Option

WithIncrementSkipFrame increments how many frames should be skipped for caller by 1.

func WithSkipFrames

func WithSkipFrames(skip int) Option

WithSkipFrames defines a how many frames should be skipped for caller autodetection. The value should be changed if StartSpanWithFinish is called from a custom wrapper.

func WithSpanOptions

func WithSpanOptions(opts ...ddtrace.StartSpanOption) Option

WithSpanOptions defines a set of additional ddtrace.StartSpanOption to be added to spans started by the integration.

type TB

type TB interface {
	Failed() bool
	Name() string
	Skipped() bool
}

TB is the minimal interface common to T and B.