integration

README

Go Integration Tests

Integration tests in go are standalone binaries that can be run. The convetion 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
• func ExecuteTimed(name string, f func() error) error
• func ExtractUniqueDsts(pairs []IAPair) []addr.IA
• func Init(name string) error
• func RunClient(in Integration, pair IAPair, timeout time.Duration) error
• func StartServer(in Integration, dst addr.IA) (io.Closer, error)
• type IAPair
  • func IAPairs() []IAPair
• type Integration
  • func NewBinaryIntegration(name string, clientArgs, serverArgs []string) Integration
• type Waiter

Constants

const (
	// SrcIAReplace is a placeholder for the source IA in the arguments.
	SrcIAReplace = "<SRCIA>"
	// DstIAReplace is a placeholder for the destination IA in the arguments.
	DstIAReplace = "<DSTIA>"
	// 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"
)

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) []addr.IA

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 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 StartServer

func StartServer(in Integration, dst addr.IA) (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.

Types

type IAPair

type IAPair struct {
	Src addr.IA
	Dst addr.IA
}

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

func IAPairs

func IAPairs() []IAPair

IAPairs returns all 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 addr.IA) (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 addr.IA) (Waiter, error)
}

Integration can be used to run integration tests.

func NewBinaryIntegration

func NewBinaryIntegration(name 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.