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).

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.

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.UDPAddr
• func GenFile(file string) string
• func GetSCIONDAddress(networksFile string, ia addr.IA) (string, error)
• func GetSCIONDAddresses(networksFile string) (map[string]string, error)
• func GroupBySource(pairs []IAPair) map[*snet.UDPAddr][]*snet.UDPAddr
• func Init() error
• func ListenDone(onDone func(src, dst addr.IA)) (string, func(), error)
• func LoadNetworkAllocs() (map[addr.IA]*snet.UDPAddr, error)
• func LogDir() string
• func Run(ctx context.Context, cfg RunConfig) 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.UDPAddr) (io.Closer, error)
• func TesterID(a *snet.UDPAddr) string
• func WithTimestamp(s string) string
• type BinaryWaiter
  • func (bw *BinaryWaiter) Output() []byte
  • func (bw *BinaryWaiter) Wait() error
• type Cmd
  • func (c Cmd) String() string
  • func (c Cmd) Template(src, dst *snet.UDPAddr) (Cmd, error)
• 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 RunConfig
• type Waiter

Constants

const (
	// SCIOND is a placeholder for the SCIOND server in the arguments.
	SCIOND = "<SCIOND>"
	// 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 = 40 * 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
	// SCIONDAddressesFile is the default file for SCIOND addresses in a topology created
	// with the topology generator.
	SCIONDAddressesFile = "sciond_addresses.json"
)

Variables

var (
	// ASList exposes the loaded ASList.
	ASList *util.ASList
)

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.UDPAddr

ExtractUniqueDsts returns all unique destinations in pairs.

func GenFile

func GenFile(file string) string

GenFile returns the path for the given file in the gen folder.

func GetSCIONDAddress

func GetSCIONDAddress(networksFile string, ia addr.IA) (string, error)

func GetSCIONDAddresses

func GetSCIONDAddresses(networksFile string) (map[string]string, error)

func GroupBySource

func GroupBySource(pairs []IAPair) map[*snet.UDPAddr][]*snet.UDPAddr

GroupBySource groups the ISD-AS pairs by source.

func Init

func Init() error

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

func ListenDone

func ListenDone(onDone func(src, dst addr.IA)) (string, func(), error)

ListenDone opens a RPC server to listen for done signals.

func LoadNetworkAllocs

func LoadNetworkAllocs() (map[addr.IA]*snet.UDPAddr, error)

func LogDir

func LogDir() string

LogDir returns the path for logs.

func Run

func Run(ctx context.Context, cfg RunConfig) error

Run runs the commands of the run config. The caller must ensure that all commands are executable when run in a tester container. E.g., for end-to-end tests this means the source address is the same for all.

func RunClient

func RunClient(in Integration, pair IAPair, timeout time.Duration,
	checkOutput func([]byte) error) 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, checkOutput func([]byte) error) 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.UDPAddr) (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 TesterID

func TesterID(a *snet.UDPAddr) string

TesterID returns the ID of the tester container.

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 BinaryWaiter

type BinaryWaiter struct {
	// contains filtered or unexported fields
}

BinaryWaiter can be used to wait on completion of the process.

func (*BinaryWaiter) Output

func (bw *BinaryWaiter) Output() []byte

Output is the output of the process, only available after Wait is returnred.

func (*BinaryWaiter) Wait

func (bw *BinaryWaiter) Wait() error

Wait waits for completion of the process.

type Cmd

type Cmd struct {
	// Binary is the path to the application binary.
	Binary string
	Args   []string
}

Cmd represents a single command.

func (Cmd) String

func (c Cmd) String() string

func (Cmd) Template

func (c Cmd) Template(src, dst *snet.UDPAddr) (Cmd, error)

Template returns a command with the place holder arguments filled in.

type HostAddr

type HostAddr func(ia addr.IA) *snet.UDPAddr

var DispAddr HostAddr = func(ia addr.IA) *snet.UDPAddr {
	if a := loadAddr(ia); a != nil {
		return a
	}
	path := GenFile(fmt.Sprintf("AS%s/topology.json", ia.A.FileFmt()))
	topo, err := topology.RWTopologyFromJSONFile(path)
	if err != nil {
		log.Error("Error loading topology", "err", err)
		os.Exit(1)
	}
	cs := topo.CS["cs"+ia.FileFmt(false)+"-1"]
	return &snet.UDPAddr{IA: ia, Host: cs.SCIONAddress}
}

DispAddr reads the CS 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, Dst *snet.UDPAddr
}

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.UDPAddr) (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.UDPAddr) (*BinaryWaiter, 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 RunConfig

type RunConfig struct {
	Commands []Cmd
	LogFile  string
	// Tester is the tester container to run the commands in. If it is empty,
	// the commands are run directly, instead of in a tester container.
	Tester string
}

RunConfig is used to configure the run.

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.