harness

Documentation

Overview

Package harness provides a suite of API compatibility checks. They were originally ported from the OpenTracing Python library's "harness" module.

To run this test suite against your tracer, call harness.RunAPIChecks and provide it a function that returns a Tracer implementation and a function to call to close it. The function will be called to create a new tracer before each test in the suite is run, and the returned closer function will be called after each test is finished.

Several options provide additional checks for your Tracer's behavior: CheckBaggageValues(true) indicates your tracer supports baggage propagation, CheckExtract(true) tells the suite to test if the Tracer can extract a trace context from text and binary carriers, and CheckInject(true) tests if the Tracer can inject the trace context into a carrier.

The UseProbe option provides an APICheckProbe implementation that allows the test suite to additionally check if two Spans are part of the same trace, and if a Span and a SpanContext are part of the same trace. Implementing an APICheckProbe provides additional assertions that your tracer is working properly.

Index

• func RunAPIChecks(t *testing.T, newTracer func() (tracer opentracing.Tracer, closer func()), ...)
• type APICheckCapabilities
• type APICheckOption
  • func CheckBaggageValues(val bool) APICheckOption
  • func CheckEverything() APICheckOption
  • func CheckExtract(val bool) APICheckOption
  • func CheckInject(val bool) APICheckOption
  • func UseProbe(probe APICheckProbe) APICheckOption
• type APICheckProbe
• type APICheckSuite
  • func (s *APICheckSuite) SetupTest()
  • func (s *APICheckSuite) TearDownTest()
  • func (s *APICheckSuite) TestBinaryPropagation()
  • func (s *APICheckSuite) TestContextBaggage()
  • func (s *APICheckSuite) TestHTTPPropagation()
  • func (s *APICheckSuite) TestInvalidExtract()
  • func (s *APICheckSuite) TestInvalidInject()
  • func (s *APICheckSuite) TestMandatoryFormats()
  • func (s *APICheckSuite) TestMultiBaggage()
  • func (s *APICheckSuite) TestSetOperationName()
  • func (s *APICheckSuite) TestSpanBaggage()
  • func (s *APICheckSuite) TestSpanLogs()
  • func (s *APICheckSuite) TestSpanTagValueTypes()
  • func (s *APICheckSuite) TestSpanTagsWithChaining()
  • func (s *APICheckSuite) TestStartSpan()
  • func (s *APICheckSuite) TestStartSpanWithParent()
  • func (s *APICheckSuite) TestTextPropagation()
  • func (s *APICheckSuite) TestUnknownFormat()
• type ForeignSpanContext
  • func (f ForeignSpanContext) ForeachBaggageItem(handler func(k, v string) bool)
• type NotACarrier

Functions

func RunAPIChecks

func RunAPIChecks(
	t *testing.T,
	newTracer func() (tracer opentracing.Tracer, closer func()),
	opts ...APICheckOption,
)

RunAPIChecks runs a test suite to check a Tracer against the OpenTracing API. It is provided a function that will be executed to create and destroy a tracer for each test in the suite, and the given APICheckOption functional options `opts`.

Types

type APICheckCapabilities

type APICheckCapabilities struct {
	CheckBaggageValues bool          // whether to check for propagation of baggage values
	CheckExtract       bool          // whether to check if extracting contexts from carriers works
	CheckInject        bool          // whether to check if injecting contexts works
	Probe              APICheckProbe // optional interface providing methods to check recorded data
}

APICheckCapabilities describes capabilities of a Tracer that should be checked by APICheckSuite.

type APICheckOption

type APICheckOption func(*APICheckSuite)

APICheckOption instances may be passed to NewAPICheckSuite.

func CheckBaggageValues

func CheckBaggageValues(val bool) APICheckOption

CheckBaggageValues returns an option that sets whether to check for propagation of baggage values.

func CheckEverything

func CheckEverything() APICheckOption

CheckEverything returns an option that enables all API checks.

func CheckExtract

func CheckExtract(val bool) APICheckOption

CheckExtract returns an option that sets whether to check if extracting contexts from carriers works.

func CheckInject

func CheckInject(val bool) APICheckOption

CheckInject returns an option that sets whether to check if injecting contexts works.

func UseProbe

func UseProbe(probe APICheckProbe) APICheckOption

UseProbe returns an option that specifies an APICheckProbe implementation to use.

type APICheckProbe

type APICheckProbe interface {
	// SameTrace helps tests assert that this tracer's spans are from the same trace.
	SameTrace(first, second opentracing.Span) bool
	// SameSpanContext helps tests assert that a span and a context are from the same trace and span.
	SameSpanContext(opentracing.Span, opentracing.SpanContext) bool
}

APICheckProbe exposes methods for testing data recorded by a Tracer.

type APICheckSuite

type APICheckSuite struct {
	suite.Suite
	// contains filtered or unexported fields
}

APICheckSuite is a testify suite for checking a Tracer against the OpenTracing API.

func (*APICheckSuite) SetupTest

func (s *APICheckSuite) SetupTest()

SetupTest creates a tracer for this specific test invocation.

func (*APICheckSuite) TearDownTest

func (s *APICheckSuite) TearDownTest()

TearDownTest closes the tracer, and clears the test-specific tracer.

func (*APICheckSuite) TestBinaryPropagation

func (s *APICheckSuite) TestBinaryPropagation()

TestBinaryPropagation tests if the Tracer can Inject a span into a binary buffer, and later Extract it. If CheckExtract is set, it will check if Extract was successful (returned no error). If a Probe is set, it will check if the extracted context is in the same trace as the original span.

func (*APICheckSuite) TestContextBaggage

func (s *APICheckSuite) TestContextBaggage()

TestContextBaggage tests calls to set and get span baggage, and if the CheckBaggageValues option is set, asserts that baggage values were successfully retrieved from the span's SpanContext.

func (*APICheckSuite) TestHTTPPropagation

func (s *APICheckSuite) TestHTTPPropagation()

TestHTTPPropagation tests if the Tracer can Inject a span into HTTP headers, and later Extract it. If CheckExtract is set, it will check if Extract was successful (returned no error). If a Probe is set, it will check if the extracted context is in the same trace as the original span.

func (*APICheckSuite) TestInvalidExtract

func (s *APICheckSuite) TestInvalidExtract()

TestInvalidExtract checks if errors are returned when Extract is called with invalid inputs.

func (*APICheckSuite) TestInvalidInject

func (s *APICheckSuite) TestInvalidInject()

TestInvalidInject checks if errors are returned when Inject is called with invalid inputs.

func (*APICheckSuite) TestMandatoryFormats

func (s *APICheckSuite) TestMandatoryFormats()

TestMandatoryFormats tests if all mandatory carrier formats are supported. If CheckExtract is set, it will check if the call to Extract was successful (returned no error such as ErrUnsupportedFormat).

func (*APICheckSuite) TestMultiBaggage

func (s *APICheckSuite) TestMultiBaggage()

TestMultiBaggage tests calls to set multiple baggage items, and if the CheckBaggageValues option is set, asserts that a baggage value was successfully retrieved from the span's SpanContext. It also ensures that returning false from the ForeachBaggageItem handler aborts iteration.

func (*APICheckSuite) TestSetOperationName

func (s *APICheckSuite) TestSetOperationName()

TestSetOperationName attempts to set the operation name on a span after it has been created.

func (*APICheckSuite) TestSpanBaggage

func (s *APICheckSuite) TestSpanBaggage()

TestSpanBaggage tests calls to set and get span baggage, and if the CheckBaggageValues option is set, asserts that baggage values were successfully retrieved.

func (*APICheckSuite) TestSpanLogs

func (s *APICheckSuite) TestSpanLogs()

TestSpanLogs tests calls to log keys and values with spans.

func (*APICheckSuite) TestSpanTagValueTypes

func (s *APICheckSuite) TestSpanTagValueTypes()

TestSpanTagValueTypes sets tags using values of different types.

func (*APICheckSuite) TestSpanTagsWithChaining

func (s *APICheckSuite) TestSpanTagsWithChaining()

TestSpanTagsWithChaining tests chaining of calls to SetTag.

func (*APICheckSuite) TestStartSpan

func (s *APICheckSuite) TestStartSpan()

TestStartSpan checks if a Tracer can start a span and calls some span API methods.

func (*APICheckSuite) TestStartSpanWithParent

func (s *APICheckSuite) TestStartSpanWithParent()

TestStartSpanWithParent checks if a Tracer can start a span with a specified parent.

func (*APICheckSuite) TestTextPropagation

func (s *APICheckSuite) TestTextPropagation()

TestTextPropagation tests if the Tracer can Inject a span into a TextMapCarrier, and later Extract it. If CheckExtract is set, it will check if Extract was successful (returned no error). If a Probe is set, it will check if the extracted context is in the same trace as the original span.

func (*APICheckSuite) TestUnknownFormat

func (s *APICheckSuite) TestUnknownFormat()

TestUnknownFormat checks if attempting to Inject or Extract using an unsupported format returns ErrUnsupportedFormat, if CheckInject and CheckExtract are set.

type ForeignSpanContext

type ForeignSpanContext struct{}

ForeignSpanContext satisfies the opentracing.SpanContext interface, but otherwise does nothing.

func (ForeignSpanContext) ForeachBaggageItem

func (f ForeignSpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem could call handler for each baggage KV, but does nothing.

type NotACarrier

type NotACarrier struct{}

NotACarrier does not satisfy any of the opentracing carrier interfaces.