integration

README

Go Integration Tests

Integration tests in go are standalone binaries that can be run. The convention is that binaries should end in _integration. We do this by putting the main of integration test in a package named *_integration. After building the integration test binaries end up in ./bin

All integration tests assume the topology is running (scion.sh run)

To run the pingpong integration test do:

./scion.sh build
./scion.sh start
./bin/pp_integration

Implementation of your own integration test

• An integration test should be a standalone binary, i.e. should have a main method.
• The binary should be named *_integration.
• It should exit (os.Exit()) with 0 on success and with a non-zero value on error.
• The Integration interface and the methods in integration should be used to implement the test.
• An example can be found in go/examples/pingpong/pp_integration.

Documentation

Overview

Package integration simplifies the creation of integration tests.

Index

• Constants
• Variables
• func ExecuteTimed(name string, f func() error) error
• func ExtractUniqueDsts(pairs []IAPair) []snet.Addr
• func Init(name string) error
• func RunBinaryTests(in Integration, pairs []IAPair, timeout time.Duration) error
• func RunClient(in Integration, pair IAPair, timeout time.Duration) error
• func RunUnaryTests(in Integration, pairs []IAPair, timeout time.Duration) error
• func StartServer(in Integration, dst snet.Addr) (io.Closer, error)
• func WithTimestamp(s string) string
• type HostAddr
• type IAPair
  • func IAPairs(hostAddr HostAddr) []IAPair
  • func UniqueIAPairs(hostAddr HostAddr) []IAPair
• type Integration
  • func NewBinaryIntegration(name string, cmd string, clientArgs, serverArgs []string) Integration
• type Waiter

Constants

const (
	// ServerPortReplace is a placeholder for the server port in the arguments.
	ServerPortReplace = "<ServerPort>"
	// SrcIAReplace is a placeholder for the source IA in the arguments.
	SrcIAReplace = "<SRCIA>"
	// SrcHostReplace is a placeholder for the source host in the arguments.
	SrcHostReplace = "<SRCHost>"
	// SrcAddrPattern is a placeholder for the source address in the arguments.
	SrcAddrPattern = SrcIAReplace + ",[" + SrcHostReplace + "]"
	// DstIAReplace is a placeholder for the destination IA in the arguments.
	DstIAReplace = "<DSTIA>"
	// DstHostReplace is a placeholder for the destination host in the arguments.
	DstHostReplace = "<DSTHost>"
	// DstAddrPattern is a placeholder for the destination address in the arguments.
	DstAddrPattern = DstIAReplace + ",[" + DstHostReplace + "]"
	// ReadySignal should be written to Stdout by the server once it is read to accept clients.
	// The message should always be `Listening ia=<IA>`
	// where <IA> is the IA the server is listening on.
	ReadySignal = "Listening ia="
	// GoIntegrationEnv is an environment variable that is set for the binary under test.
	// It can be used to guard certain statements, like printing the ReadySignal,
	// in a program under test.
	GoIntegrationEnv = "SCION_GO_INTEGRATION"

	// WrapperCmd is the command used to run non-test binaries
	WrapperCmd = "./integration/bin_wrapper.sh"
)

const (
	// StartServerTimeout is the timeout for starting a server.
	StartServerTimeout = 6 * time.Second
	// DefaultRunTimeout is the timeout when running a server or a client.
	DefaultRunTimeout = 8 * time.Second
	// CtxTimeout is the timeout a context waits before being killed
	CtxTimeout = 2 * time.Second
	// RetryTimeout is the timeout between different attempts
	RetryTimeout = time.Second / 2
)

Variables

var (
	// Docker indicates if the tests should be executed in a Docker container
	Docker = flag.Bool("d", false, "Run tests in a docker container")
)

Functions

func ExecuteTimed

func ExecuteTimed(name string, f func() error) error

ExecuteTimed executes f and prints how long f took to StdOut. Returns the error of f.

func ExtractUniqueDsts

func ExtractUniqueDsts(pairs []IAPair) []snet.Addr

ExtractUniqueDsts returns all unique destinations in pairs.

func Init

func Init(name string) error

Init initializes the integration test, it adds and validates the command line flags, and initializes logging.

func RunBinaryTests

func RunBinaryTests(in Integration, pairs []IAPair, timeout time.Duration) error

RunBinaryTests runs the client and server for each IAPair. A number of tests are run in parallel In case of an error the function is terminated immediately.

func RunClient

func RunClient(in Integration, pair IAPair, timeout time.Duration) error

RunClient runs a client on the given IAPair. If the client does not finish until timeout it is killed.

func RunUnaryTests

func RunUnaryTests(in Integration, pairs []IAPair, timeout time.Duration) error

RunUnaryTests runs the client for each IAPair. In case of an error the function is terminated immediately.

func StartServer

func StartServer(in Integration, dst snet.Addr) (io.Closer, error)

StartServer runs a server. The server can be stopped by calling Close() on the returned Closer. To start a server with a custom context use in.StartServer directly.

func WithTimestamp

func WithTimestamp(s string) string

WithTimestamp returns s with the now timestamp prefixed. This is helpful for logging staments to stdout/stderr or in a file where the logger isn't used.

Types

type HostAddr

type HostAddr func(ia addr.IA) snet.Addr

var DispAddr HostAddr = func(ia addr.IA) snet.Addr {
	path := fmt.Sprintf("gen/ISD%d/AS%s/endhost/topology.json", ia.I, ia.A.FileFmt())
	topo, err := topology.LoadFromFile(path)
	if err != nil {
		log.Error("Error loading topology", "err", err)
		os.Exit(1)
	}
	bs := topo.BS["bs"+ia.FileFmt(false)+"-1"]
	return snet.Addr{Host: &addr.AppAddr{L3: bs.IPv4.PublicAddr().L3}, IA: ia}
}

DispAddr reads the BS host Addr from the topology for the specified IA. In general this could be the IP of any service (PS/BS/CS) in that IA because they share the same dispatcher in the dockerized topology. The host IP is used as client or server address in the tests because the testing container is connecting to the dispatcher of the services.

type IAPair

type IAPair struct {
	Src snet.Addr
	Dst snet.Addr
}

IAPair is a source, destination pair. The client (Src) will dial the server (Dst).

func IAPairs

func IAPairs(hostAddr HostAddr) []IAPair

IAPairs returns all IAPairs that should be tested.

func UniqueIAPairs

func UniqueIAPairs(hostAddr HostAddr) []IAPair

UniqueIAPairs returns all distinct IAPairs that should be tested.

type Integration

type Integration interface {
	// Name returns the name of the test
	Name() string
	// StartServer should start the server listening on the address dst.
	// StartServer should return after it is ready to accept clients.
	// The context should be used to make the server cancellable.
	StartServer(ctx context.Context, dst snet.Addr) (Waiter, error)
	// StartClient should start the client on the src address connecting to the dst address.
	// StartClient should return immediately.
	// The context should be used to make the client cancellable.
	StartClient(ctx context.Context, src, dst snet.Addr) (Waiter, error)
}

Integration can be used to run integration tests.

func NewBinaryIntegration

func NewBinaryIntegration(name string, cmd string, clientArgs, serverArgs []string) Integration

NewBinaryIntegration returns an implementation of the Integration interface. Start* will run the binary programm with name and use the given arguments for the client/server. Use SrcIAReplace and DstIAReplace in arguments as placeholder for the source and destination IAs. When starting a client/server the placeholders will be replaced with the actual values. The server should output the ReadySignal to Stdout once it is ready to accept clients.

type Waiter

type Waiter interface {
	// Wait should block until the underlying program is terminated.
	Wait() error
}

Waiter is a descriptor of a process running in the integration test. It should be used to wait on completion of the process.