spawn

README

spawn

Spawn makes it easy to spin up your Go server right from within its own test suite, for end-to-end testing.

Usage

An example usage for this simple HTTP server can be found below. The complete runnable example is at examples.

func TestMain(m *testing.M) {
	// start the server on localhost:8080 (we assume it accepts a `--port` argument)
	server := spawn.New(main, "--port", "8080")
	ctx, cancel := context.WithCancel(context.Background())
	server.Start(ctx)

	// wait a bit for it to become ready
	time.Sleep(500 * time.Millisecond)

	// execute the test suite
	result := m.Run()

	// cleanly shutdown server
	cancel()
	err := server.Wait()
	if err != nil {
		log.Fatal(err)
	}

	os.Exit(result)
}

func TestServerFoo(t *testing.T) {
	res, _ := http.Get("http://localhost:8080/foo")
	defer res.Body.Close()

	resBody, _ := ioutil.ReadAll(res.Body)

	if string(resBody) != "Hello!" {
		t.Fatalf("expected response to be 'Hello!', got '%s'", resBody)
	}
}

// more tests using the server

Rationale

Writing an end-to-end test for a server typically involves:

1. compiling the server code
2. spinning up the binary
3. communicating with it from the tests
4. shutting the server down
5. verify everything went OK (server was closed cleanly etc.)

This package aims to simplify this process.

Documentation

Overview

Package spawn makes it easy to end-to-end test Go servers. The main idea is that you spin up your server in your TestMain(), use it throughout your tests and shut it down at the end.

Refer to the examples directory for usage information.

Index

• type Cmd
  • func New(main func(), args ...string) *Cmd
  • func (c *Cmd) Start(ctx context.Context) error
  • func (c *Cmd) Wait() error

Types

type Cmd

type Cmd struct {
	Cmd *exec.Cmd
	// contains filtered or unexported fields
}

Cmd wraps exec.Cmd and represents a binary being prepared or run.

In the typical end-to-end testing scenario, Cmd will end up running two times:

1. from TestMain when the test suite is first executed. At this point it will spawn the already-compiled test binary (itself) again and...
2. from the spawned binary, inside TestMain again. But this time it will intercept TestMain and will execute main() instead (i.e. the actual program)

func New

func New(main func(), args ...string) *Cmd

New returns a Cmd that will either execute the passed in main() function, or the parent binary with the given arguments. The program's main() function should be passed as f.

func (*Cmd) Start

func (c *Cmd) Start(ctx context.Context) error

Start starts c until it terminates or ctx is cancelled. It does not wait for it to complete. When ctx is cancelled a SIGINT is sent to c.

The Wait method will return the exit code and release associated resources once the command exits.

func (*Cmd) Wait

func (c *Cmd) Wait() error

Wait waits for the command to exit and waits for any copying to stdin or copying from stdout or stderr to complete.

The command must have been started by Start.

The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, exits with a zero exit status and any signals to the command were delivered successfully.

Wait releases any resources associated with the command.