Downstream Logger Unit Testing

[bflad]

terraform-plugin-log version

v0.3.0

Use cases

Downstream SDKs (and potentially providers?) should be able to implement unit testing to verify their logging setup is working as expected, especially when creating subsystems. This module uses some internally available functionality in the internal/loggertest package to create root loggers which output to a predefined io.Writer, e.g.

func SDKRoot(ctx context.Context, output io.Writer) context.Context {
	return tfsdklog.NewRootSDKLogger(
		ctx,
		logging.WithoutLocation(),
		logging.WithoutTimestamp(),
		logging.WithOutput(output),
	)
}

And unit testing such as:

func TestTrace(t *testing.T) {
	t.Parallel()

	testCases := map[string]struct {
		message          string
		additionalFields []map[string]interface{}
		expectedOutput   []map[string]interface{}
	}{
		"no-fields": {
			message: "test message",
			expectedOutput: []map[string]interface{}{
				{
					"@level":   hclog.Trace.String(),
					"@message": "test message",
					"@module":  "sdk",
				},
			},
		},
		"fields-single-map": {
			message: "test message",
			additionalFields: []map[string]interface{}{
				{
					"test-key-1": "test-value-1",
					"test-key-2": "test-value-2",
					"test-key-3": "test-value-3",
				},
			},
			expectedOutput: []map[string]interface{}{
				{
					"@level":     hclog.Trace.String(),
					"@message":   "test message",
					"@module":    "sdk",
					"test-key-1": "test-value-1",
					"test-key-2": "test-value-2",
					"test-key-3": "test-value-3",
				},
			},
		},
		"fields-multiple-maps": {
			message: "test message",
			additionalFields: []map[string]interface{}{
				{
					"test-key-1": "test-value-1-map1",
					"test-key-2": "test-value-2-map1",
					"test-key-3": "test-value-3-map1",
				},
				{
					"test-key-4": "test-value-4-map2",
					"test-key-1": "test-value-1-map2",
					"test-key-5": "test-value-5-map2",
				},
			},
			expectedOutput: []map[string]interface{}{
				{
					"@level":     hclog.Trace.String(),
					"@message":   "test message",
					"@module":    "sdk",
					"test-key-1": "test-value-1-map2",
					"test-key-2": "test-value-2-map1",
					"test-key-3": "test-value-3-map1",
					"test-key-4": "test-value-4-map2",
					"test-key-5": "test-value-5-map2",
				},
			},
		},
	}

	for name, testCase := range testCases {
		name, testCase := name, testCase

		t.Run(name, func(t *testing.T) {
			t.Parallel()

			var outputBuffer bytes.Buffer

			ctx := context.Background()
			ctx = loggertest.SDKRoot(ctx, &outputBuffer)

			tfsdklog.Trace(ctx, testCase.message, testCase.additionalFields...)

			got, err := loggertest.MultilineJSONDecode(&outputBuffer)

			if err != nil {
				t.Fatalf("unable to read multiple line JSON: %s", err)
			}

			if diff := cmp.Diff(testCase.expectedOutput, got); diff != "" {
				t.Errorf("unexpected output difference: %s", diff)
			}
		})
	}
}

It should be possible for other modules to also implement similar unit testing.

Attempted solutions

Manual verification. 😢

Proposals

Initially I was thinking something like proposal 1, but proposal 2 might make life much simpler for everyone.

Proposal 1

Export logging.WithoutLocation(), logging.WithoutTimestamp(), and logging.WithOutput() functions in at least the tfsdklog package, denoting they are only intended for unit testing.

Proposal 2

Create "unit testing" packages (e.g. tfsdklogtest) that expose the root loggers, similar to loggertest. e.g.

// package tflogtest

func RootLogger(ctx context.Context, output io.Writer) context.Context {
	return tfsdklog.NewRootProviderLogger(
		ctx,
		logging.WithoutLocation(),
		logging.WithoutTimestamp(),
		logging.WithOutput(output),
	)
}

// package tfsdklogtest

func RootLogger(ctx context.Context, output io.Writer) context.Context {
	return tfsdklog.NewRootSDKLogger(
		ctx,
		logging.WithoutLocation(),
		logging.WithoutTimestamp(),
		logging.WithOutput(output),
	)
}

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.