diff --git a/testutil/README.md b/testutil/README.md new file mode 100644 index 000000000..0369d0c1b --- /dev/null +++ b/testutil/README.md @@ -0,0 +1,60 @@ +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 some example usage: + +```go +package main + +import ( + "github.com/hashicorp/consul/testutil" + "testing" +) + +func TestMain(t *testing.T) { + // Create a server + srv1 := testutil.NewTestServer(t) + defer srv1.Stop() + + // Create a secondary server + srv2 := testutil.NewTestServer(t) + 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", "passing", []string{"master"}) + + // Create a service check + srv1.AddCheck("service:redis", "redis", "passing") + + // Create a node check + srv1.AddCheck("mem", "", "critical") + + // The HTTPAddr field contains the address of the Consul + // API on the new test server instance. + println(srv1.HTTPAddr) +} +```