harness

Documentation

Overview

Package harness contains basic reusable test harness components, without any domain-specific logic.

Index

• type IncomingRequestInfo
• type MockEndpoint
  • func (e *MockEndpoint) ActiveConnection() *IncomingRequestInfo
  • func (e *MockEndpoint) AwaitConnection(timeout time.Duration) (IncomingRequestInfo, error)
  • func (e *MockEndpoint) BaseURL() string
  • func (e *MockEndpoint) Close()
  • func (e *MockEndpoint) RequireConnection(t helpers.TestContext, timeout time.Duration) IncomingRequestInfo
  • func (e *MockEndpoint) RequireNoMoreConnections(t helpers.TestContext, timeout time.Duration)
• type MockEndpointOption
  • func MockEndpointContextFn(fn func(context.Context) context.Context) MockEndpointOption
  • func MockEndpointDescription(description string) MockEndpointOption
• type TestHarness
  • func NewTestHarness(testServiceBaseURL string, testHarnessExternalHostname string, ...) (*TestHarness, error)
  • func (h *TestHarness) NewMockEndpoint(handler http.Handler, logger framework.Logger, options ...MockEndpointOption) *MockEndpoint
  • func (h *TestHarness) NewTestServiceEntity(entityParams interface{}, description string, logger framework.Logger) (*TestServiceEntity, error)
  • func (h *TestHarness) StopService() error
  • func (h *TestHarness) TestServiceInfo() TestServiceInfo
• type TestServiceEntity
  • func (e *TestServiceEntity) Close() error
  • func (e *TestServiceEntity) SendCommand(command string, logger framework.Logger, responseOut interface{}) error
  • func (e *TestServiceEntity) SendCommandWithParams(allParams interface{}, logger framework.Logger, responseOut interface{}) error
• type TestServiceInfo
• type TestServiceInfoBase

Types

type IncomingRequestInfo

type IncomingRequestInfo struct {
	Headers http.Header
	Method  string
	URL     url.URL
	Body    []byte
	Context context.Context
	Cancel  context.CancelFunc
}

IncomingRequestInfo contains information about an HTTP request sent by the test service to one of the mock endpoints.

type MockEndpoint

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

MockEndpoint represents an endpoint that can receive requests.

func (*MockEndpoint) ActiveConnection

func (e *MockEndpoint) ActiveConnection() *IncomingRequestInfo

func (*MockEndpoint) AwaitConnection

func (e *MockEndpoint) AwaitConnection(timeout time.Duration) (IncomingRequestInfo, error)

AwaitConnection waits for an incoming request to the endpoint.

func (*MockEndpoint) BaseURL

func (e *MockEndpoint) BaseURL() string

BaseURL returns the base path of the mock endpoint.

func (*MockEndpoint) Close

func (e *MockEndpoint) Close()

Close unregisters the endpoint. Any subsequent requests to it will receive 404 errors. It also cancels the Context for every active request to that endpoint.

func (*MockEndpoint) RequireConnection

func (e *MockEndpoint) RequireConnection(t helpers.TestContext, timeout time.Duration) IncomingRequestInfo

RequireConnection waits for an incoming request to the endpoint, and causes the test to fail and terminate if it timed out.

func (*MockEndpoint) RequireNoMoreConnections

func (e *MockEndpoint) RequireNoMoreConnections(t helpers.TestContext, timeout time.Duration)

RequireNoMoreConnections causes the test to fail and terminate if there is another incoming request within the timeout.

type MockEndpointOption

type MockEndpointOption helpers.ConfigOption[MockEndpoint]

MockEndpointOption is the interface for options to NewMockEndpoint.

func MockEndpointContextFn

func MockEndpointContextFn(fn func(context.Context) context.Context) MockEndpointOption

MockEndpointContextFn is an option to set a context transformation function for the endpoint that will be called for each request. This can be used if the test logic managing the endpoint needs to be able to share some kind of state between the endpoint's HTTP handler and code elsewhere, by embedding a value in the context.

func MockEndpointDescription

func MockEndpointDescription(description string) MockEndpointOption

MockEndpointDescription is an option to set a descriptive name for the endpoint, such as "streaming service".

type TestHarness

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

TestHarness is the main component that manages communication with test services.

It always communicates with a single test service, which it verifies is alive on startup. It can then create any number of test service entities within the test service (NewTestServiceEntity) and any number of callback endpoints for the test service to interact with (NewMockEndpoint).

It contains no domain-specific test logic, but only provides a general mechanism for test suites to build on.

func NewTestHarness

func NewTestHarness(
	testServiceBaseURL string,
	testHarnessExternalHostname string,
	testHarnessPort int,
	statusQueryTimeout time.Duration,
	debugLogger framework.Logger,
	startupOutput io.Writer,
) (*TestHarness, error)

NewTestHarness creates a TestHarness instance, and verifies that the test service is responding by querying its status resource. It also starts an HTTP listener on the specified port to receive callback requests.

func (*TestHarness) NewMockEndpoint

func (h *TestHarness) NewMockEndpoint(
	handler http.Handler,
	logger framework.Logger,
	options ...MockEndpointOption,
) *MockEndpoint

NewMockEndpoint adds a new endpoint that can receive requests.

The specified handler will be called for all incoming requests to the endpoint's base URL or any subpath of it. For instance, if the generated base URL (as reported by MockEndpoint.BaseURL()) is http://localhost:8111/endpoints/3, then it can also receive requests to http://localhost:8111/endpoints/3/some/subpath.

When the handler is called, the test harness rewrites the request URL first so that the handler sees only the subpath. It also attaches a Context to the request whose Done channel will be closed if Close is called on the endpoint.

func (*TestHarness) NewTestServiceEntity

func (h *TestHarness) NewTestServiceEntity(
	entityParams interface{},
	description string,
	logger framework.Logger,
) (*TestServiceEntity, error)

NewTestServiceEntity tells the test service to create a new instance of whatever kind of entity it manages, based on the parameters we provide. The test harness can interact with it via the returned TestServiceEntity. The entity is assumed to remain active inside the test service until we explicitly close it.

The format of entityParams is defined by the test harness; this low-level method simply calls json.Marshal to convert whatever it is to JSON.

func (*TestHarness) StopService

func (h *TestHarness) StopService() error

StopService tells the test service that it should exit.

func (*TestHarness) TestServiceInfo

func (h *TestHarness) TestServiceInfo() TestServiceInfo

TestServiceInfo returns the initial status information received from the test service.

type TestServiceEntity

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

TestServiceEntity represents some kind of entity that we have asked the test service to create, which the test harness will interact with.

func (*TestServiceEntity) Close

func (e *TestServiceEntity) Close() error

Close tells the test service to dispose of this entity.

func (*TestServiceEntity) SendCommand

func (e *TestServiceEntity) SendCommand(
	command string,
	logger framework.Logger,
	responseOut interface{},
) error

SendCommand sends a command to the test service entity.

func (*TestServiceEntity) SendCommandWithParams

func (e *TestServiceEntity) SendCommandWithParams(
	allParams interface{},
	logger framework.Logger,
	responseOut interface{},
) error

SendCommandWithParams sends a command to the test service entity.

type TestServiceInfo

type TestServiceInfo struct {
	TestServiceInfoBase

	// FullData is the entire response received from the test service, which might contain additional
	// properties beyond TestServiceInfoBase.
	FullData []byte
}

TestServiceInfo is status information returned by the test service from the initial status query.

type TestServiceInfoBase

type TestServiceInfoBase struct {
	// Name is the name of the project that the test service is testing, such as "go-server-sdk".
	Name string `json:"name"`

	// Capabilities is a list of strings representing optional features of the test service.
	Capabilities framework.Capabilities `json:"capabilities"`
}

TestServiceInfoBase is the basic set of properties that all test services must provide.