ssetests

Documentation

Overview

Package ssetests contains the SSE contract tests themselves and their supporting API.

Test harness infrastructure that is not specific to the SSE domain, such as the ability to communicate with the test service and to receive requests on mock endpoints, is in the lower-level framework package.

Index

• Variables
• func DoBasicParsingTests(t *T)
• func DoCommentTests(t *T)
• func DoHTTPBehaviorTests(t *T)
• func DoLinefeedTests(t *T)
• func DoReconnectionTests(t *T)
• func RunTestSuite(harness *framework.TestHarness, filter framework.Filter, ...) framework.Results
• type CreateStreamOpts
• type EventMessage
  • func (e EventMessage) String() string
• type ReceivedMessage
  • func (m ReceivedMessage) String() string
• type T
  • func (t *T) AwaitNewConnectionToStream() framework.IncomingRequestInfo
  • func (t *T) BreakStreamConnection()
  • func (t *T) Debug(format string, args ...interface{})
  • func (t *T) Errorf(format string, args ...interface{})
  • func (t *T) FailNow()
  • func (t *T) RequireCapability(capability string)
  • func (t *T) RequireComment() string
  • func (t *T) RequireError() string
  • func (t *T) RequireEvent() EventMessage
  • func (t *T) RequireMessage() ReceivedMessage
  • func (t *T) RequireSpecificEvents(events ...EventMessage)
  • func (t *T) RestartClient()
  • func (t *T) Run(name string, action func(*T))
  • func (t *T) SendOnStream(data string)
  • func (t *T) SendOnStreamInChunks(data string, chunkSize int, delayBetween time.Duration)
  • func (t *T) StartSSEClient() framework.IncomingRequestInfo
  • func (t *T) StartSSEClientOptions(opts CreateStreamOpts) framework.IncomingRequestInfo
  • func (t *T) TellClientToExpectEventType(eventType string)

Variables

var AllCapabilities = []string{
	"comments",
	"headers",
	"last-event-id",
	"post",
	"read-timeout",
	"report",
}

Functions

func DoBasicParsingTests

func DoBasicParsingTests(t *T)

func DoCommentTests

func DoCommentTests(t *T)

func DoHTTPBehaviorTests

func DoHTTPBehaviorTests(t *T)

func DoLinefeedTests

func DoLinefeedTests(t *T)

func DoReconnectionTests

func DoReconnectionTests(t *T)

func RunTestSuite

func RunTestSuite(
	harness *framework.TestHarness,
	filter framework.Filter,
	testLogger framework.TestLogger,
) framework.Results

Types

type CreateStreamOpts

type CreateStreamOpts struct {
	InitialDelayMS ldvalue.OptionalInt `json:"initialDelayMs,omitempty"`
	LastEventID    string              `json:"lastEventId,omitempty"`
	Method         string              `json:"method,omitempty"`
	Body           string              `json:"body,omitempty"`
	Headers        map[string]string   `json:"headers,omitempty"`
	ReadTimeoutMS  ldvalue.OptionalInt `json:"readTimeoutMs,omitempty"`
}

type EventMessage

type EventMessage struct {
	Type string `json:"type"`
	Data string `json:"data"`
	ID   string `json:"id"`
}

EventMessage contains the fields of an SSE event, exactly as it was received from the test service's SSE client.

func (EventMessage) String

func (e EventMessage) String() string

type ReceivedMessage

type ReceivedMessage struct {
	// Kind is "event", "comment", or "error".
	Kind string `json:"kind"`

	// Event is non-nil if Kind is "event". It contains an SSE event that was received by the
	// test service's SSE client.
	Event *EventMessage `json:"event,omitempty"`

	// Comment contains an SSE comment that was received by the test service's SSE client,
	// if Kind is "comment". Not all SSE implementations are able to return comments.
	Comment string `json:"comment,omitempty"`

	// Error contains an error message from the test service, if Kind is "error".
	Error string `json:"error,omitempty"`
	// contains filtered or unexported fields
}

ReceivedMessage is a single message sent to us by the test service.

func (ReceivedMessage) String

func (m ReceivedMessage) String() string

type T

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

T represents a test or subtest in our SSE test suite.

It implements the same basic functionality as Go's testing.T, but in an environment that is outside of the Go test runner, and with some extra features such as debug logging that are convenient for our use case. Those features are provided by our lower-level framework package.

It also provides functionality that is specific to SSE testing. Every T instance maintains a mock stream (implemented in our stream package), and a reference to an SSE client in the test service. It has methods for interacting with both of those.

To make test assertions, you can use the assert and require packages, passing the *T as if it were a *testing.T. There are also assertions built into many of the stream/client interaction methods, causing the test to immediately fail if something unexpected happens, to reduce the amount of boilerplate logic in tests.

func (*T) AwaitNewConnectionToStream

func (t *T) AwaitNewConnectionToStream() framework.IncomingRequestInfo

AwaitNewConnectionToStream waits for the SSE client to connect to the mock stream. It will fail and immediately exit the test if it times out while waiting. It returns information about the incoming connection.

Tests only need to call this method if they expect another connection after the first one.

func (*T) BreakStreamConnection

func (t *T) BreakStreamConnection()

BreakStreamConnection causes the mock stream to disconnect from the SSE client.

func (*T) Debug

func (t *T) Debug(format string, args ...interface{})

Debug logs some debug output for the test. The output will be passed to the test logger at the end of the test.

func (*T) Errorf

func (t *T) Errorf(format string, args ...interface{})

Errorf is called by assertions to log a test failure. It does not cause an immediate exit.

func (*T) FailNow

func (t *T) FailNow()

FailNow is called by assertions when a test should fail and immediately exit. The methods in the require package call FailNow.

func (*T) RequireCapability

func (t *T) RequireCapability(capability string)

RequireCapability skips this test if the test service did not declare that it supports the specified capability.

func (*T) RequireComment

func (t *T) RequireComment() string

RequireEvent waits for the SSE client in the test service to tell us that it received a comment.

The test fails and immediately exits if it times out without receiving anything, or if what we receive from the test service us is not a comment.

func (*T) RequireError

func (t *T) RequireError() string

RequireError waits for the SSE client in the test service to tell us that it received an error.

The test fails and immediately exits if it times out without receiving anything, or if what we receive from the test service us is not an error.

func (*T) RequireEvent

func (t *T) RequireEvent() EventMessage

RequireEvent waits for the SSE client in the test service to tell us that it received an event.

The test fails and immediately exits if it times out without receiving anything, or if what we receive from the test service us is not an event.

func (*T) RequireMessage

func (t *T) RequireMessage() ReceivedMessage

RequireMessage waits for the SSE client in the test service to send us some kind of information.

The test fails and immediately exits if it times out without receiving anything.

func (*T) RequireSpecificEvents

func (t *T) RequireSpecificEvents(events ...EventMessage)

RequireSpecificEvents waits for the SSE client in the test service to tell us that it received a series of events, which must match the specified events.

Since some SSE implementations do not properly set the default event type to "message", this method uses a loose comparison where event types of "message" and "" are equal. We can check the default event type behavior in a more specific test, so lack of compliance on that point won't cause all sorts of other tests to fail.

func (*T) RestartClient

func (t *T) RestartClient()

RestartClient tells the SSE client in the test service to immediately disconnect and retry. Not all SSE implementations support this.

func (*T) Run

func (t *T) Run(name string, action func(*T))

Run runs a subtest. This is equivalent to the Run method of testing.T.

The specified function receives a new T instance, with its own mock stream.

func (*T) SendOnStream

func (t *T) SendOnStream(data string)

SendOnStream tells the mock stream to send a piece of data.

func (*T) SendOnStreamInChunks

func (t *T) SendOnStreamInChunks(data string, chunkSize int, delayBetween time.Duration)

SendOnStreamInChunks tells the mock stream to send some data broken into chunks of the specified number of bytes, with an optional delay between chunks.

func (*T) StartSSEClient

func (t *T) StartSSEClient() framework.IncomingRequestInfo

StartSSEClient tells the test service to start an SSE client with default options. All subsequent calls to methods like RequireEvent will refer to this client.

This also causes the test to wait for the client to connect to the mock stream. It will fail and immediately exit the test if it times out while waiting. It returns information about the incoming connection.

func (*T) StartSSEClientOptions

func (t *T) StartSSEClientOptions(opts CreateStreamOpts) framework.IncomingRequestInfo

StartSSEClientOptions tells the test service to start an SSE client with the specified options. All subsequent calls to methods like RequireEvent will refer to this client.

This also causes the test to wait for the client to connect to the mock stream. It will fail and immediately exit the test if it times out while waiting. It returns information about the incoming connection.

func (*T) TellClientToExpectEventType

func (t *T) TellClientToExpectEventType(eventType string)

TellClientToExpectEventType tells the SSE client in the test service that it should be ready to receive an event with the specified type. This is only necessary for SSE implementations that require you to explicitly listen for each event type.