integration

package
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 23, 2024 License: BSD-2-Clause Imports: 21 Imported by: 0

Documentation

Overview

Package integration contains helpers for integration testing.

The integration test package should normally be used from within a file that does not build unless integration tests are being run: 

//go:build integration

It should also normally be used from within a test containing the term "Integration". The build constraint ensures that we don't run integration tests when we only want to run unit tests and the test name ensures that we don't run unit tests when we only want to run integration tests. For example, a simple test of sending a ping might be called TestIntegrationSendPing.

Tests can be setup by importing the various packages under this package such as "prosody" and "ejabberd". To setup a test against a server the "Test" function should be used and configured with the general options provided in this package and the server specific options provided in the server's package. This creates a SubtestRunner which can be called multiple times to spin up servers with the provided configuration and run one or more subtests against them. For example, running two tests against Prosody and one against Ejabberd might look like the following: 

func TestIntegrationSendPing(t *testing.T) {
	prosodyRun := prosody.Test(context.TODO(), t,
		integration.Log(),
		prosody.ListenC2S(),
	)
	prosodyRun(integrationSendPing)
	prosodyRun(integrationRecvPing)

	ejabberdRun := ejabberd.Test(context.TODO(), t,
		integration.Log(),
		ejabberd.ListenC2S(),
	)
	ejabberdRun(integrationSendPing)
}

For more information see the SubtestRunner type and the various Option functions.

The SubtestRunner passes each call a Cmd. This is a representation of the command that is being run (ie. the server or client we're testing against) and provides you with the information you'll need to connect and communicate with the command. For example, in the ping example above the subtest being run might use Cmd's DialClient shortcut to quickly create a connection to the prosody server spun up for the test. 

func integrationSendPing(ctx context.Context, t *testing.T, cmd *integration.Cmd) {
	j, pass := cmd.User()
	session, err := cmd.DialClient(ctx, j, t,
		xmpp.StartTLS(&tls.Config{
			InsecureSkipVerify: true,
		}),
		xmpp.SASL("", pass, sasl.Plain),
		xmpp.BindResource(),
	)
}

For more information see the Cmd type.

Configuration

The integration package uses several environment variables to control the behavior of tests. These environment variables are described below. 

MELLIUM_INTEGRATION_NO_CLEANUP=false do not remove temporary files when tests complete
MELLIUM_INTEGRATION_SKIP=""          a comma separated list of command names to skip

For example: 

MELLIUM_INTEGRATION_NO_CLEANUP=true go test -tags "integration" -run Integration .

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cmd 

type Cmd struct {
	*exec.Cmd

	// Config is meant to be used by internal packages like prosody and ejabberd
	// to store their internal representation of the config before writing it out.
	Config interface{}
	// contains filtered or unexported fields
}

Cmd is an external command being prepared or run.

A Cmd cannot be reused after calling its Run, Output or CombinedOutput methods.

func New 

func New(ctx context.Context, name string, opts ...Option) (*Cmd, error)

New creates a new, unstarted, command.

The provided context is used to kill the process (by calling os.Process.Kill) if the context becomes done before the command completes on its own.

func (*Cmd) C2SAddr added in v0.18.0 

func (cmd *Cmd) C2SAddr() (net.Addr, string)

C2SAddr returns the client-to-server address and network.

func (*Cmd) C2SListen 

func (cmd *Cmd) C2SListen(network, addr string) (net.Listener, error)

C2SListen returns a listener with a random port. The listener is created on the first call to C2SListener. Subsequent calls ignore the arguments and return the existing listener.

func (*Cmd) C2SPort added in v0.18.0 

func (cmd *Cmd) C2SPort() string

C2SPort returns the port on which the C2S listener is running (if any).

func (*Cmd) ClientCert added in v0.18.0 

func (cmd *Cmd) ClientCert(*tls.CertificateRequestInfo) (*tls.Certificate, error)

ClientCert returns the last configured client certificate. The certificate request info is currently ignored and is only there to make promoting this method to a function and using it as tls.Config.GetClientCertificate possible.

func (*Cmd) Close 

func (cmd *Cmd) Close() error

Close kills the command if it is still running and cleans up any temporary resources that were created.

func (*Cmd) ComponentAddr added in v0.18.0 

func (cmd *Cmd) ComponentAddr() (net.Addr, string)

ComponentAddr returns the component address and network.

func (*Cmd) ComponentConn added in v0.18.0 

func (cmd *Cmd) ComponentConn(ctx context.Context) (net.Conn, error)

ComponentConn dials a connection to the component socket and returns it without negotiating a session.

func (*Cmd) ComponentListen added in v0.18.0 

func (cmd *Cmd) ComponentListen(network, addr string) (net.Listener, error)

ComponentListen returns a listener with a random port. The listener is created on the first call to ComponentListener. Subsequent calls ignore the arguments and return the existing listener.

func (*Cmd) ConfigDir 

func (cmd *Cmd) ConfigDir() string

ConfigDir returns the temporary directory used to store config files.

func (*Cmd) Conn added in v0.18.0 

func (cmd *Cmd) Conn(ctx context.Context, s2s bool) (net.Conn, error)

Conn dials a connection and returns it without negotiating a session.

func (*Cmd) DialClient added in v0.18.0 

func (cmd *Cmd) DialClient(ctx context.Context, j jid.JID, t *testing.T, features ...xmpp.StreamFeature) (*xmpp.Session, error)

DialClient attempts to connect to the server with a client-to-server (c2s) connection by dialing the address reserved by C2SListen and then negotiating a stream with the location set to the domainpart of j and the origin set to j.

func (*Cmd) DialServer added in v0.18.0 

func (cmd *Cmd) DialServer(ctx context.Context, location, origin jid.JID, t *testing.T, features ...xmpp.StreamFeature) (*xmpp.Session, error)

DialServer attempts to connect to the server with a server-to-server (s2s) connection by dialing the address reserved by S2SListen and then negotiating a stream.

func (*Cmd) Done added in v0.18.0 

func (cmd *Cmd) Done() <-chan error

Done returns a channel that's closed when the commands process terminates.

func (*Cmd) HTTPConn added in v0.18.0 

func (cmd *Cmd) HTTPConn(ctx context.Context, secure bool) (net.Conn, error)

HTTPConn dials a connection and returns it without negotiating a session.

func (*Cmd) HTTPListen added in v0.18.0 

func (cmd *Cmd) HTTPListen(network, addr string) (net.Listener, error)

HTTPListen returns a listener with a random port (for HTTP). The listener is created on the first call to HTTPListener. Subsequent calls ignore the arguments and return the existing listener.

func (*Cmd) HTTPPort added in v0.18.0 

func (cmd *Cmd) HTTPPort() string

HTTPPort returns the port on which the HTTP listener is running (if any).

func (*Cmd) HTTPSListen added in v0.18.0 

func (cmd *Cmd) HTTPSListen(network, addr string) (net.Listener, error)

HTTPSListen returns a listener with a random port (for HTTPS). The listener is created on the first call to HTTPSListener. Subsequent calls ignore the arguments and return the existing listener.

func (*Cmd) HTTPSPort added in v0.18.0 

func (cmd *Cmd) HTTPSPort() string

HTTPSPort returns the port on which the HTTPS listener is running (if any).

func (*Cmd) S2SAddr added in v0.18.0 

func (cmd *Cmd) S2SAddr() (net.Addr, string)

S2SAddr returns the server-to-server address and network.

func (*Cmd) S2SListen added in v0.18.0 

func (cmd *Cmd) S2SListen(network, addr string) (net.Listener, error)

S2SListen returns a listener with a random port. The listener is created on the first call to S2SListener. Subsequent calls ignore the arguments and return the existing listener.

func (*Cmd) Start added in v0.18.0 

func (cmd *Cmd) Start() error

Start runs the command.

func (*Cmd) Stdin added in v0.18.0 

func (cmd *Cmd) Stdin() io.WriteCloser

Stdin returns a pipe to the commands standard input.

func (*Cmd) User added in v0.18.0 

func (cmd *Cmd) User() (jid.JID, string)

User returns the address and password of a user created on the server (if any).

type Option 

type Option func(cmd *Cmd) error

Option is used to configure a Cmd.

func Args 

func Args(f ...string) Option

Args sets additional command line args to be passed to the command.

func Cert 

func Cert(name string) Option

Cert creates a private key and certificate with the given name.

func ClientCert added in v0.18.0 

func ClientCert(name string) Option

ClientCert creates a private key and certificate with the given name that can be used for TLS authentication.

func Defer 

func Defer(f func(*Cmd) error) Option

Defer is an option that calls f after the command is started. If multiple Defer options are passed they are called in order until an error is encountered.

func Log 

func Log() Option

Log configures the command to copy stdout to the current testing.T. This should not be used for CLI or TUI clients.

func LogFile added in v0.18.0 

func LogFile(f string, tee io.Writer) Option

LogFile reads the provided file into the log in the same way that the Log option reads a commands standard output. It can optionally copy the command to the provided io.Writer (if non-nil) as well similar to the tee(1) command. Normally this should be used by the various server and client packages to read a FIFO which has been configured to be the log by the actual client process so that it functions similar to the tail(1) command.

func LogXML 

func LogXML() Option

LogXML configures the command to log sent and received XML to the current testing.T.

func Name added in v0.21.0 

func Name(s string) Option

Name sets the name of the test. This defaults to the basename of the path to the binary (ie. if the testing binary is /usr/local/sbin/prosody the name of the test will be "prosody"). It can be useful to override this when multiple tests run the same binary, for example the aioxmpp and slixmpp package would both generate tests called "python" if they did not provide this option.

func Shutdown 

func Shutdown(f func(*Cmd) error) Option

Shutdown is run before the configuration is removed and is meant to gracefully shutdown the application in case it does not handle the kill signal correctly. If multiple shutdown options are used the functions will be run in the order in which they are passed until an error is encountered.

func Skip added in v0.21.0 

func Skip() Option

Skip calls t.Skip on the test before the command has been started (as opposed to doing it in the test itself where you may still have log output from the command). It is useful to temporarily disable a broken test.

func TempFile 

func TempFile(cfgFileName string, f func(*Cmd, io.Writer) error) Option

TempFile creates a file in the commands temporary working directory. After all configuration is complete it then calls f to populate the config files.

func User added in v0.18.0 

func User(user jid.JID, pass string) Option

User sets the values that will be returned by a call to cmd.User later. It does not actually create a user.

type SubtestRunner 

type SubtestRunner func(func(context.Context, *testing.T, *Cmd)) bool

SubtestRunner is the signature of a function that can be used to start subtests.

func Test 

func Test(ctx context.Context, name string, t *testing.T, opts ...Option) SubtestRunner

Test starts a command and returns a function that runs tests as a subtest using t.Run. Multiple calls to the returned function will result in uniquely named subtests. When all subtests have completed, the daemon is stopped.

Source Files

View all Source files

Directories

Path Synopsis
Package aioxmpp facilitates integration testing against aioxmpp.
 Package aioxmpp facilitates integration testing against aioxmpp.
Package ejabberd facilitates integration testing against Ejabberd.
 Package ejabberd facilitates integration testing against Ejabberd.
Package jackal facilitates integration testing against Jackal.
 Package jackal facilitates integration testing against Jackal.
Package mcabber facilitates integration testing against Mcabber.
 Package mcabber facilitates integration testing against Mcabber.
Package mellium facilitates integration testing against clients.
 Package mellium facilitates integration testing against clients.
Package prosody facilitates integration testing against Prosody.
 Package prosody facilitates integration testing against Prosody.
Package python facilitates integration testing against Python scripts.
 Package python facilitates integration testing against Python scripts.
Package sendxmpp facilitates integration testing with sendxmpp.
 Package sendxmpp facilitates integration testing with sendxmpp.
Package slixmpp facilitates integration testing against slixmpp.
 Package slixmpp facilitates integration testing against slixmpp.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.