test

Documentation

Overview

Package test provides utilities for running integration tests on the trace agent. You may use the runner to start a fake backend, a trace-agent instance with a custom configuration, post payloads to the agent and assert the results.

To use this package, start by instantiating a runner. It needs not be initialized and can be used as is, for example:

// this runner is ready to use:
var runner test.Runner

Next, start the fake backend before running any tests:

if err := runner.Start(); err != nil {
	log.Fatal(err)
}

Then, use `runner.RunAgent`, `runner.Post`, `runner.Out` and `runner.KillAgent` to run tests. For a full demonstration, see the package example.

Example

The below example shows a common use-case scenario for the runner.

var runner Runner
// Start the runner.
if err := runner.Start(); err != nil {
	log.Fatal(err)
}
defer log.Fatal(runner.Shutdown(time.Second))

// Run an agent with a given config.
conf, err := ioutil.ReadFile("/opt/datadog-agent/etc/datadog.yaml")
if err != nil {
	log.Fatal(err)
}
if err := runner.RunAgent(conf); err != nil {
	log.Fatal(err)
}

// Post a payload.
payload := pb.Traces{
	pb.Trace{testutil.RandomSpan()},
	pb.Trace{testutil.RandomSpan()},
}
if err := runner.Post(payload); err != nil {
	log.Fatal(err)
}

// Assert the results.
switch v := (<-runner.Out()).(type) {
case pb.AgentPayload:
	fmt.Println("OK tracer payloads: ", len(v.TracerPayloads))
case pb.StatsPayload:
	fmt.Println("OK stats: ", len(v.Stats))
}

Index

• Variables
• type Runner
  • func (s *Runner) AgentLog() string
  • func (s *Runner) KillAgent()
  • func (s *Runner) Out() <-chan interface{}
  • func (s *Runner) Post(traceList pb.Traces) error
  • func (s *Runner) PostMsgpack(path string, data msgp.Marshaler) (err error)
  • func (s *Runner) RunAgent(conf []byte) error
  • func (s *Runner) Shutdown(wait time.Duration) error
  • func (s *Runner) Start() error

Examples

• Package

Variables

var ErrNotInstalled = errors.New("agent: trace-agent not found in $PATH")

ErrNotInstalled is returned when the trace-agent can not be found in $PATH.

var ErrNotStarted = errors.New("runner: not started")

ErrNotStarted is returned when attempting to operate an unstarted Runner.

Types

type Runner

type Runner struct {
	// Verbose will make the runner output more verbose, more specifically
	// around operations regarding the trace-agent process.
	Verbose bool

	// ChannelSize specifies the size of the payload buffer of the fake backend.
	// If reached, HTTP handlers will block until payloads are received from
	// the out channel. It defaults to 100.
	ChannelSize int
	// contains filtered or unexported fields
}

Runner can start an agent instance using a custom configuration, send payloads to it and act as a fake backend. Call Start first to initiate the fake backend, then RunAgent to start agent instances. Post may be used to send payloads to the agent and Out to receive its output.

func (*Runner) AgentLog

func (s *Runner) AgentLog() string

AgentLog returns up to 1MB of tail from the trace agent log.

func (*Runner) KillAgent

func (s *Runner) KillAgent()

KillAgent kills any agent that was started by this runner.

func (*Runner) Out

func (s *Runner) Out() <-chan interface{}

Out returns a channel which will provide payloads received by the fake backend. They can be of type pb.AgentPayload or agent.StatsPayload.

func (*Runner) Post

func (s *Runner) Post(traceList pb.Traces) error

Post posts the given list of traces to the trace agent. Before posting, agent must be started. You can start an agent using RunAgent.

func (*Runner) PostMsgpack

func (s *Runner) PostMsgpack(path string, data msgp.Marshaler) (err error)

PostMsgpack encodes data using msgpack and posts it to the given path. The agent must be started using RunAgent.

Example: r.PostMsgpack("/v0.5/stats", pb.ClientStatsPayload{})

func (*Runner) RunAgent

func (s *Runner) RunAgent(conf []byte) error

RunAgent starts an agent instance using the given YAML configuration.

func (*Runner) Shutdown

func (s *Runner) Shutdown(wait time.Duration) error

Shutdown stops any running agent and shuts down the fake backend.

func (*Runner) Start

func (s *Runner) Start() error

Start initializes the runner and starts the fake backend.