docs(tests): document tracing test helper utilities

Author: rvagg

testutil/tracing.go

@@ -15,19 +15,24 @@ import (
 
 var _ trace.SpanExporter = &Collector{}
 
+// Collector can be used as a trace batcher to provide traces to, we collect
+// individual spans and then extract useful data out of them for test assertions
 type Collector struct {
 	Spans tracetest.SpanStubs
 }
 
+// ExportSpans receives the ReadOnlySpans from the batch provider
 func (c *Collector) ExportSpans(ctx context.Context, spans []trace.ReadOnlySpan) error {
 	c.Spans = tracetest.SpanStubsFromReadOnlySpans(spans)
 	return nil
 }
 
+// Shutdown is a noop, we don't need to do anything fancy
 func (c *Collector) Shutdown(ctx context.Context) error {
 	return nil
 }
 
+// FindSpans returns a list of spans by their name
 func (c Collector) FindSpans(name string) tracetest.SpanStubs {
 	var found = tracetest.SpanStubs{}
 	for _, s := range c.Spans {
@@ -38,8 +43,9 @@ func (c Collector) FindSpans(name string) tracetest.SpanStubs {
 	return found
 }
 
-// TracesToString returns an array of traces represented as strings with each
-// span in the trace identified by name separated by a '->'
+// TracesToString returns an array of all traces represented as strings with each
+// span in the trace identified by name and its number (within the parent span)
+// in parens, separated by a '->'. e.g. `"foo(0)->bar(0)","foo(0)->bar(1)"`
 func (c Collector) TracesToStrings() []string {
 	return c.tracesToString("", c.FindParentSpans(), "", func(_ tracetest.SpanStub) {})
 }
@@ -67,14 +73,23 @@ func (c Collector) tracesToString(trace string, spans tracetest.SpanStubs, match
 	return traces
 }
 
-func (c Collector) FindSpanByTraceString(trace string) tracetest.SpanStubs {
-	var found = tracetest.SpanStubs{}
+// FindSpanByTraceString is similar to FindSpans but returns a single span
+// identified by its trace string as described in TracesToStrings. Note that
+// this string can also be a partial of a complete trace, e.g. just `"foo(0)"`
+// without any children to fetch the parent span.
+func (c Collector) FindSpanByTraceString(trace string) tracetest.SpanStub {
+	var found tracetest.SpanStub
 	c.tracesToString("", c.FindParentSpans(), trace, func(span tracetest.SpanStub) {
-		found = append(found, span)
+		if found.Name != "" {
+			panic("found more than one span with the same trace string")
+		}
+		found = span
 	})
 	return found
 }
 
+// FindParentSpans finds spans that have no parents, they are at the top any
+// stack.
 func (c Collector) FindParentSpans() tracetest.SpanStubs {
 	var found = tracetest.SpanStubs{}
 	for _, s := range c.Spans {
@@ -85,6 +100,7 @@ func (c Collector) FindParentSpans() tracetest.SpanStubs {
 	return found
 }
 
+// FindSpansWithParent finds spans that are children of the provided span.
 func (c Collector) FindSpansWithParent(stub tracetest.SpanStub) tracetest.SpanStubs {
 	var found = tracetest.SpanStubs{}
 	for _, s := range c.Spans {
@@ -95,22 +111,29 @@ func (c Collector) FindSpansWithParent(stub tracetest.SpanStub) tracetest.SpanSt
 	return found
 }
 
+// SingleExceptionEvent is a test helper that asserts that a span, identified by a
+// trace string (see TracesToStrings) contains a single exception, identified by
+// the type (regexp) and message (regexp). If errorCode is true, then we also assert
+// that the span has an error status code, with the same message (regexp)
 func (c Collector) SingleExceptionEvent(t *testing.T, trace string, typeRe string, messageRe string, errorCode bool) {
 	t.Helper()
 
 	// has ContextCancelError exception recorded in the right place
 	et := c.FindSpanByTraceString(trace)
-	require.Len(t, et, 1, "expected one span with trace %v", trace)
-	require.Len(t, et[0].Events, 1, "expected one event in span %v", trace)
-	ex := EventAsException(t, EventInTraceSpan(t, et[0], "exception"))
+	require.Len(t, et.Events, 1, "expected one event in span %v", trace)
+	ex := EventAsException(t, EventInTraceSpan(t, et, "exception"))
 	require.Regexp(t, typeRe, ex.Type)
 	require.Regexp(t, messageRe, ex.Message)
 	if errorCode {
-		require.Equal(t, codes.Error, et[0].Status.Code)
-		require.Regexp(t, messageRe, et[0].Status.Description)
+		require.Equal(t, codes.Error, et.Status.Code)
+		require.Regexp(t, messageRe, et.Status.Description)
 	}
 }
 
+// SetupTracing returns a test helper that can will collect all spans within
+// a Collector. The returned helper function should be called at the point in
+// a test where the spans are ready to be analyzed. Any spans not properly
+// completed at that point won't be represented in the Collector.
 func SetupTracing() func(t *testing.T) *Collector {
 	collector := &Collector{}
 	tp := trace.NewTracerProvider(trace.WithBatcher(collector))
@@ -126,6 +149,9 @@ func SetupTracing() func(t *testing.T) *Collector {
 	return collect
 }
 
+// AttributeValueInTraceSpan is a test helper that asserts that at a span
+// contains an attribute with the name provided, and returns the value of
+// that attribute for further inspection.
 func AttributeValueInTraceSpan(t *testing.T, stub tracetest.SpanStub, attributeName string) attribute.Value {
 	t.Helper()
 
@@ -138,6 +164,9 @@ func AttributeValueInTraceSpan(t *testing.T, stub tracetest.SpanStub, attributeN
 	return attribute.Value{}
 }
 
+// EventInTraceSpan is a test helper that asserts that at a span
+// contains an event with the name provided, and returns the value of
+// that event for further inspection.
 func EventInTraceSpan(t *testing.T, stub tracetest.SpanStub, eventName string) trace.Event {
 	t.Helper()
 
@@ -150,11 +179,14 @@ func EventInTraceSpan(t *testing.T, stub tracetest.SpanStub, eventName string) t
 	return trace.Event{}
 }
 
+// ExceptionEvent is a simplistic string form representation of an event
 type ExceptionEvent struct {
 	Type    string
 	Message string
 }
 
+// EventAsException is a test helper that converts a trace event to an ExceptionEvent
+// for easier inspection.
 func EventAsException(t *testing.T, evt trace.Event) ExceptionEvent {
 	t.Helper()