Add propagationtest package

oteltest/text_map_propagator.go

@@ -29,6 +29,8 @@ type ctxKeyType string
 
 // TextMapCarrier provides a testing storage medium to for a
 // TextMapPropagator. It records all the operations it performs.
+//
+// Deprecated: use the propagationtest package instead.
 type TextMapCarrier struct {
 	mtx sync.Mutex
 
@@ -38,6 +40,8 @@ type TextMapCarrier struct {
 }
 
 // NewTextMapCarrier returns a new *TextMapCarrier populated with data.
+//
+// Deprecated: use the propagationtest package instead.
 func NewTextMapCarrier(data map[string]string) *TextMapCarrier {
 	copied := make(map[string]string, len(data))
 	for k, v := range data {
@@ -161,11 +165,17 @@ func (s state) String() string {
 	return fmt.Sprintf("%d,%d", s.Injections, s.Extractions)
 }
 
+// TextMapPropagator is a propagation.TextMapPropagator used for testing.
+//
+// Deprecated: use the propagationtest package instead.
 type TextMapPropagator struct {
 	Name   string
 	ctxKey ctxKeyType
 }
 
+// NewTextMapPropagator returns a new TextMapPropagator for testing.
+//
+// Deprecated: use the propagationtest package instead.
 func NewTextMapPropagator(name string) *TextMapPropagator {
 	return &TextMapPropagator{Name: name, ctxKey: ctxKeyType(name)}
 }

propagation/propagationtest/doc.go

@@ -0,0 +1,23 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package propagationtest provides testing utilities for the propagation
+package.
+
+This package is currently in a Release Candidate phase. Backwards incompatible
+changes may be introduced prior to v1.0.0, but we believe the current API is
+ready to stabilize.
+*/
+package propagationtest

propagation/propagationtest/text_map_carrier.go

@@ -0,0 +1,141 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package propagationtest
+
+import (
+	"sync"
+	"testing"
+
+	"go.opentelemetry.io/otel/propagation"
+)
+
+// TextMapCarrier is a storage medium for a TextMapPropagator used in testing.
+// The methods of a TextMapCarrier are concurrent safe.
+type TextMapCarrier struct {
+	mtx sync.Mutex
+
+	gets []string
+	sets [][2]string
+	data map[string]string
+}
+
+var _ propagation.TextMapCarrier = (*TextMapCarrier)(nil)
+
+// NewTextMapCarrier returns a new *TextMapCarrier populated with data.
+func NewTextMapCarrier(data map[string]string) *TextMapCarrier {
+	copied := make(map[string]string, len(data))
+	for k, v := range data {
+		copied[k] = v
+	}
+	return &TextMapCarrier{data: copied}
+}
+
+// Keys returns the keys for which this carrier has a value.
+func (c *TextMapCarrier) Keys() []string {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+
+	result := make([]string, 0, len(c.data))
+	for k := range c.data {
+		result = append(result, k)
+	}
+	return result
+}
+
+// Get returns the value associated with the passed key.
+func (c *TextMapCarrier) Get(key string) string {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	c.gets = append(c.gets, key)
+	return c.data[key]
+}
+
+// GotKey tests if c.Get has been called for key.
+func (c *TextMapCarrier) GotKey(t *testing.T, key string) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	for _, k := range c.gets {
+		if k == key {
+			return true
+		}
+	}
+	t.Errorf("TextMapCarrier.Get(%q) has not been called", key)
+	return false
+}
+
+// GotN tests if n calls to c.Get have been made.
+func (c *TextMapCarrier) GotN(t *testing.T, n int) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	if len(c.gets) != n {
+		t.Errorf("TextMapCarrier.Get was called %d times, not %d", len(c.gets), n)
+		return false
+	}
+	return true
+}
+
+// Set stores the key-value pair.
+func (c *TextMapCarrier) Set(key, value string) {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	c.sets = append(c.sets, [2]string{key, value})
+	c.data[key] = value
+}
+
+// SetKeyValue tests if c.Set has been called for the key-value pair.
+func (c *TextMapCarrier) SetKeyValue(t *testing.T, key, value string) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	var vals []string
+	for _, pair := range c.sets {
+		if key == pair[0] {
+			if value == pair[1] {
+				return true
+			}
+			vals = append(vals, pair[1])
+		}
+	}
+	if len(vals) > 0 {
+		t.Errorf("TextMapCarrier.Set called with %q and %v values, but not %s", key, vals, value)
+	}
+	t.Errorf("TextMapCarrier.Set(%q,%q) has not been called", key, value)
+	return false
+}
+
+// SetN tests if n calls to c.Set have been made.
+func (c *TextMapCarrier) SetN(t *testing.T, n int) bool {
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+	if len(c.sets) != n {
+		t.Errorf("TextMapCarrier.Set was called %d times, not %d", len(c.sets), n)
+		return false
+	}
+	return true
+}
+
+// Reset zeros out the recording state and sets the carried values to data.
+func (c *TextMapCarrier) Reset(data map[string]string) {
+	copied := make(map[string]string, len(data))
+	for k, v := range data {
+		copied[k] = v
+	}
+
+	c.mtx.Lock()
+	defer c.mtx.Unlock()
+
+	c.gets = nil
+	c.sets = nil
+	c.data = copied
+}

propagation/propagationtest/text_map_carrier_test.go

@@ -0,0 +1,83 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package propagationtest
+
+import (
+	"reflect"
+	"testing"
+)
+
+var (
+	key, value = "test", "true"
+)
+
+func TestTextMapCarrierKeys(t *testing.T) {
+	tmc := NewTextMapCarrier(map[string]string{key: value})
+	expected, actual := []string{key}, tmc.Keys()
+	if !reflect.DeepEqual(actual, expected) {
+		t.Errorf("expected tmc.Keys() to be %v but it was %v", expected, actual)
+	}
+}
+
+func TestTextMapCarrierGet(t *testing.T) {
+	tmc := NewTextMapCarrier(map[string]string{key: value})
+	tmc.GotN(t, 0)
+	if got := tmc.Get("empty"); got != "" {
+		t.Errorf("TextMapCarrier.Get returned %q for an empty key", got)
+	}
+	tmc.GotKey(t, "empty")
+	tmc.GotN(t, 1)
+	if got := tmc.Get(key); got != value {
+		t.Errorf("TextMapCarrier.Get(%q) returned %q, want %q", key, got, value)
+	}
+	tmc.GotKey(t, key)
+	tmc.GotN(t, 2)
+}
+
+func TestTextMapCarrierSet(t *testing.T) {
+	tmc := NewTextMapCarrier(nil)
+	tmc.SetN(t, 0)
+	tmc.Set(key, value)
+	if got, ok := tmc.data[key]; !ok {
+		t.Errorf("TextMapCarrier.Set(%q,%q) failed to store pair", key, value)
+	} else if got != value {
+		t.Errorf("TextMapCarrier.Set(%q,%q) stored (%q,%q), not (%q,%q)", key, value, key, got, key, value)
+	}
+	tmc.SetKeyValue(t, key, value)
+	tmc.SetN(t, 1)
+}
+
+func TestTextMapCarrierReset(t *testing.T) {
+	tmc := NewTextMapCarrier(map[string]string{key: value})
+	tmc.GotN(t, 0)
+	tmc.SetN(t, 0)
+	tmc.Reset(nil)
+	tmc.GotN(t, 0)
+	tmc.SetN(t, 0)
+	if got := tmc.Get(key); got != "" {
+		t.Error("TextMapCarrier.Reset() failed to clear initial data")
+	}
+	tmc.GotN(t, 1)
+	tmc.GotKey(t, key)
+	tmc.Set(key, value)
+	tmc.SetKeyValue(t, key, value)
+	tmc.SetN(t, 1)
+	tmc.Reset(nil)
+	tmc.GotN(t, 0)
+	tmc.SetN(t, 0)
+	if got := tmc.Get(key); got != "" {
+		t.Error("TextMapCarrier.Reset() failed to clear data")
+	}
+}

propagation/propagationtest/text_map_propagator.go

@@ -0,0 +1,112 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package propagationtest
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"testing"
+
+	"go.opentelemetry.io/otel/propagation"
+)
+
+type ctxKeyType string
+
+type state struct {
+	Injections  uint64
+	Extractions uint64
+}
+
+func newState(encoded string) state {
+	if encoded == "" {
+		return state{}
+	}
+	split := strings.SplitN(encoded, ",", 2)
+	injects, _ := strconv.ParseUint(split[0], 10, 64)
+	extracts, _ := strconv.ParseUint(split[1], 10, 64)
+	return state{
+		Injections:  injects,
+		Extractions: extracts,
+	}
+}
+
+func (s state) String() string {
+	return fmt.Sprintf("%d,%d", s.Injections, s.Extractions)
+}
+
+// TextMapPropagator is a propagation.TextMapPropagator used for testing.
+type TextMapPropagator struct {
+	name   string
+	ctxKey ctxKeyType
+}
+
+var _ propagation.TextMapPropagator = (*TextMapPropagator)(nil)
+
+// NewTextMapPropagator returns a new TextMapPropagator for testing. It will
+// use name as the key it injects into a TextMapCarrier when Inject is called.
+func NewTextMapPropagator(name string) *TextMapPropagator {
+	return &TextMapPropagator{name: name, ctxKey: ctxKeyType(name)}
+}
+
+func (p *TextMapPropagator) stateFromContext(ctx context.Context) state {
+	if v := ctx.Value(p.ctxKey); v != nil {
+		if s, ok := v.(state); ok {
+			return s
+		}
+	}
+	return state{}
+}
+
+func (p *TextMapPropagator) stateFromCarrier(carrier propagation.TextMapCarrier) state {
+	return newState(carrier.Get(p.name))
+}
+
+// Inject sets cross-cutting concerns for p from ctx into carrier.
+func (p *TextMapPropagator) Inject(ctx context.Context, carrier propagation.TextMapCarrier) {
+	s := p.stateFromContext(ctx)
+	s.Injections++
+	carrier.Set(p.name, s.String())
+}
+
+// InjectedN tests if p has made n injections to carrier.
+func (p *TextMapPropagator) InjectedN(t *testing.T, carrier *TextMapCarrier, n int) bool {
+	if actual := p.stateFromCarrier(carrier).Injections; actual != uint64(n) {
+		t.Errorf("TextMapPropagator{%q} injected %d times, not %d", p.name, actual, n)
+		return false
+	}
+	return true
+}
+
+// Extract reads cross-cutting concerns for p from carrier into ctx.
+func (p *TextMapPropagator) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context {
+	s := p.stateFromCarrier(carrier)
+	s.Extractions++
+	return context.WithValue(ctx, p.ctxKey, s)
+}
+
+// ExtractedN tests if p has made n extractions from the lineage of ctx.
+// nolint (context is not first arg)
+func (p *TextMapPropagator) ExtractedN(t *testing.T, ctx context.Context, n int) bool {
+	if actual := p.stateFromContext(ctx).Extractions; actual != uint64(n) {
+		t.Errorf("TextMapPropagator{%q} extracted %d time, not %d", p.name, actual, n)
+		return false
+	}
+	return true
+}
+
+// Fields returns the name of p as the key who's value is set with Inject.
+func (p *TextMapPropagator) Fields() []string { return []string{p.name} }