testutil

README

Consul Testing Utilities

This package provides some generic helpers to facilitate testing in Consul.

TestServer

TestServer is a harness for managing Consul agents and initializing them with test data. Using it, you can form test clusters, create services, add health checks, manipulate the K/V store, etc. This test harness is completely decoupled from Consul's core and API client, meaning it can be easily imported and used in external unit tests for various applications. It works by invoking the Consul CLI, which means it is a requirement to have Consul installed in the $PATH.

Following is an example usage:

package my_program

import (
	"testing"

	"github.com/hashicorp/consul/consul/structs"
	"github.com/hashicorp/consul/testutil"
)

func TestMain(t *testing.T) {
	// Create a test Consul server
	srv1 := testutil.NewTestServer(t)
	defer srv1.Stop()

	// Create a secondary server, passing in configuration
	// to avoid bootstrapping as we are forming a cluster.
	srv2 := testutil.NewTestServerConfig(t, func(c *testutil.TestServerConfig) {
		c.Bootstrap = false
	})
	defer srv2.Stop()

	// Join the servers together
	srv1.JoinLAN(srv2.LANAddr)

	// Create a test key/value pair
	srv1.SetKV("foo", []byte("bar"))

	// Create lots of test key/value pairs
	srv1.PopulateKV(map[string][]byte{
		"bar": []byte("123"),
		"baz": []byte("456"),
	})

	// Create a service
	srv1.AddService("redis", structs.HealthPassing, []string{"master"})

	// Create a service check
	srv1.AddCheck("service:redis", "redis", structs.HealthPassing)

	// Create a node check
	srv1.AddCheck("mem", "", structs.HealthCritical)

	// The HTTPAddr field contains the address of the Consul
	// API on the new test server instance.
	println(srv1.HTTPAddr)
}

Documentation

Index

• func WaitForLeader(t *testing.T, rpc rpcFn, dc string) structs.IndexedNodes
• func WaitForResult(test testFn, error errorFn)
• type ServerConfigCallback
• type TestAddressConfig
• type TestCheck
• type TestKVResponse
• type TestPerformanceConfig
• type TestPortConfig
• type TestServer
  • func NewTestServer(t TestingT) *TestServer
  • func NewTestServerConfig(t TestingT, cb ServerConfigCallback) *TestServer
  • func (s *TestServer) AddCheck(name, serviceID, status string)
  • func (s *TestServer) AddService(name, status string, tags []string)
  • func (s *TestServer) GetKV(key string) []byte
  • func (s *TestServer) JoinLAN(addr string)
  • func (s *TestServer) JoinWAN(addr string)
  • func (s *TestServer) ListKV(prefix string) []string
  • func (s *TestServer) PopulateKV(data map[string][]byte)
  • func (s *TestServer) SetKV(key string, val []byte)
  • func (s *TestServer) Stop()
• type TestServerConfig
• type TestService
• type TestingT

Functions

func WaitForLeader

func WaitForLeader(t *testing.T, rpc rpcFn, dc string) structs.IndexedNodes

func WaitForResult

func WaitForResult(test testFn, error errorFn)

Types

type ServerConfigCallback

type ServerConfigCallback func(c *TestServerConfig)

ServerConfigCallback is a function interface which can be passed to NewTestServerConfig to modify the server config.

type TestAddressConfig

type TestAddressConfig struct {
	HTTP string `json:"http,omitempty"`
}

TestAddressConfig contains the bind addresses for various components of the Consul server.

type TestCheck

type TestCheck struct {
	ID        string `json:",omitempty"`
	Name      string `json:",omitempty"`
	ServiceID string `json:",omitempty"`
	TTL       string `json:",omitempty"`
}

TestCheck is used to serialize a check definition.

type TestKVResponse

type TestKVResponse struct {
	Value string
}

TestKVResponse is what we use to decode KV data.

type TestPerformanceConfig

type TestPerformanceConfig struct {
	RaftMultiplier uint `json:"raft_multiplier,omitempty"`
}

TestPerformanceConfig configures the performance parameters.

type TestPortConfig

type TestPortConfig struct {
	DNS     int `json:"dns,omitempty"`
	HTTP    int `json:"http,omitempty"`
	RPC     int `json:"rpc,omitempty"`
	SerfLan int `json:"serf_lan,omitempty"`
	SerfWan int `json:"serf_wan,omitempty"`
	Server  int `json:"server,omitempty"`
}

TestPortConfig configures the various ports used for services provided by the Consul server.

type TestServer

type TestServer struct {
	Config *TestServerConfig

	HTTPAddr string
	LANAddr  string
	WANAddr  string

	HttpClient *http.Client
	// contains filtered or unexported fields
}

TestServer is the main server wrapper struct.

func NewTestServer

func NewTestServer(t TestingT) *TestServer

NewTestServer is an easy helper method to create a new Consul test server with the most basic configuration.

func NewTestServerConfig

func NewTestServerConfig(t TestingT, cb ServerConfigCallback) *TestServer

NewTestServerConfig creates a new TestServer, and makes a call to an optional callback function to modify the configuration.

func (*TestServer) AddCheck

func (s *TestServer) AddCheck(name, serviceID, status string)

AddCheck adds a check to the Consul instance. If the serviceID is left empty (""), then the check will be associated with the node. The check status may be "passing", "warning", or "critical".

func (*TestServer) AddService

func (s *TestServer) AddService(name, status string, tags []string)

AddService adds a new service to the Consul instance. It also automatically adds a health check with the given status, which can be one of "passing", "warning", or "critical".

func (*TestServer) GetKV

func (s *TestServer) GetKV(key string) []byte

GetKV retrieves a single key and returns its value

func (*TestServer) JoinLAN

func (s *TestServer) JoinLAN(addr string)

JoinLAN is used to join nodes within the same datacenter.

func (*TestServer) JoinWAN

func (s *TestServer) JoinWAN(addr string)

JoinWAN is used to join remote datacenters together.

func (*TestServer) ListKV

func (s *TestServer) ListKV(prefix string) []string

ListKV returns a list of keys present in the KV store. This will list all keys under the given prefix recursively and return them as a slice.

func (*TestServer) PopulateKV

func (s *TestServer) PopulateKV(data map[string][]byte)

PopulateKV fills the Consul KV with data from a generic map.

func (*TestServer) SetKV

func (s *TestServer) SetKV(key string, val []byte)

SetKV sets an individual key in the K/V store.

func (*TestServer) Stop

func (s *TestServer) Stop()

Stop stops the test Consul server, and removes the Consul data directory once we are done.

type TestServerConfig

type TestServerConfig struct {
	NodeName          string                 `json:"node_name"`
	Performance       *TestPerformanceConfig `json:"performance,omitempty"`
	Bootstrap         bool                   `json:"bootstrap,omitempty"`
	Server            bool                   `json:"server,omitempty"`
	DataDir           string                 `json:"data_dir,omitempty"`
	Datacenter        string                 `json:"datacenter,omitempty"`
	DisableCheckpoint bool                   `json:"disable_update_check"`
	LogLevel          string                 `json:"log_level,omitempty"`
	Bind              string                 `json:"bind_addr,omitempty"`
	Addresses         *TestAddressConfig     `json:"addresses,omitempty"`
	Ports             *TestPortConfig        `json:"ports,omitempty"`
	ACLMasterToken    string                 `json:"acl_master_token,omitempty"`
	ACLDatacenter     string                 `json:"acl_datacenter,omitempty"`
	ACLDefaultPolicy  string                 `json:"acl_default_policy,omitempty"`
	Encrypt           string                 `json:"encrypt,omitempty"`
	Stdout, Stderr    io.Writer              `json:"-"`
	Args              []string               `json:"-"`
}

TestServerConfig is the main server configuration struct.

type TestService

type TestService struct {
	ID      string   `json:",omitempty"`
	Name    string   `json:",omitempty"`
	Tags    []string `json:",omitempty"`
	Address string   `json:",omitempty"`
	Port    int      `json:",omitempty"`
}

TestService is used to serialize a service definition.

type TestingT

type TestingT interface {
	Logf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
	Fatalf(format string, args ...interface{})
	Fatal(args ...interface{})
	Skip(args ...interface{})
}

TestingT is an interface wrapper around TestingT