6. Logging tools

.github/workflows/verify.yml

@@ -1,5 +1,7 @@
 # Copyright (c) The OpenTofu Authors
 # SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2023 HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
 name: Verify
 permissions: {}
 on:

LICENSE

@@ -1,4 +1,5 @@
 Copyright (c) The OpenTofu Authors
+Copyright (c) 2014 HashiCorp, Inc.
 
 Mozilla Public License, version 2.0
 

README.md

@@ -0,0 +1,127 @@
+# OpenTofu test utilities
+
+This library contains the test fixtures and utilities for testing OpenTofu. This library will be changed to suit the needs of OpenTofu only, please do not use it for any other purpose.
+
+## Test context
+
+Some tests need to create external resources, such as cloud resources, which need to be cleaned up reliably when the test ends. Unfortunately, `go test` unceremoniously kills the test run if it encounters a timeout without leaving time for cleanup functions to run. You can call `tofutestutils.Context` to obtain a `context.Context` that will leave enough time to perform a cleanup:
+
+```go
+package your_test
+
+import (
+	"testing"
+	"your"
+
+	"github.com/opentofu/tofutestutils"
+)
+
+func TestMyApplication(t *testing.T) {
+	ctx := tofutestutils.Context(t)
+
+	your.App(ctx)
+}
+```
+
+## Randomness
+
+The random functions provide a number of randomness sources for testing purposes, some deterministic, some not.
+
+To obtain a deterministic randomness source *tied to a test name*, you can use the `DeterministicSource` (implementing an `io.Reader`) as follows:
+
+```go
+package your_test
+
+import (
+	"testing"
+	"your"
+
+	"github.com/opentofu/tofutestutils"
+)
+
+func TestMyApp(t *testing.T) {
+	randomness := tofutestutils.DeterministicRandomSource(t)
+
+    your.App(randomness)	
+}
+```
+
+For a full list of possible functions, please [check the Go docs](https://pkg.go.dev/github.com/opentofu/tofutestutils).
+
+## Handling errors
+
+This package also provides the `Must()` and `Must2()` functions to make test code easier to read. For example:
+
+```go
+package your_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/opentofu/tofutestutils"
+)
+
+func erroringFunction() error {
+	return fmt.Errorf("this is an error")
+}
+
+func erroringFunctionWithReturn() (int, error) {
+	return 42, fmt.Errorf("this is an error")
+}
+
+func TestMyApp(t *testing.T) {
+	// This will cause a panic:
+	tofutestutils.Must(erroringFunction())
+}
+
+func TestMyApp2(t *testing.T) {
+	// This will also cause a panic:
+	result := tofutestutils.Must2(erroringFunctionWithReturn())
+	t.Logf("The number is: %d", result)
+}
+```
+
+## Certificate authority
+
+When you need an x509 certificate for a server or a client, you can use the `tofutestutils.CA` function to obtain a `testca.CertificateAuthority` implementation using a pseudo-random number generator. You can use this to create a certificate for a socket server:
+
+```go
+package your_test
+
+import (
+	"crypto/tls"
+	"io"
+	"net"
+	"strconv"
+	"testing"
+
+	"github.com/opentofu/tofutestutils"
+)
+
+func TestMySocket(t *testing.T) {
+	ca := tofutestutils.CA(t)
+
+	// Server side:
+	tlsListener := tofutestutils.Must2(tls.Listen("tcp", "127.0.0.1:0", ca.CreateLocalhostServerCert().GetServerTLSConfig()))
+	go func() {
+		conn, serverErr := tlsListener.Accept()
+		if serverErr != nil {
+			return
+		}
+		defer func() {
+			_ = conn.Close()
+		}()
+		_, _ = conn.Write([]byte("Hello world!"))
+	}()
+
+	// Client side:
+	port := tlsListener.Addr().(*net.TCPAddr).Port
+	client := tofutestutils.Must2(tls.Dial("tcp", net.JoinHostPort("127.0.0.1", strconv.Itoa(port)), ca.GetClientTLSConfig()))
+	defer func() {
+		_ = client.Close()
+	}()
+
+	t.Logf("%s", tofutestutils.Must2(io.ReadAll(client)))
+}
+```

ca.go

@@ -0,0 +1,19 @@
+// Copyright (c) The OpenTofu Authors
+// SPDX-License-Identifier: MPL-2.0
+// Copyright (c) 2023 HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package tofutestutils
+
+import (
+	"testing"
+	"time"
+
+	"github.com/opentofu/tofutestutils/testca"
+)
+
+// CA returns a certificate authority configured for the provided test. This implementation will configure the CA to use
+// a pseudorandom source. You can call testca.New() for more configuration options.
+func CA(t *testing.T) testca.CertificateAuthority {
+	return testca.New(t, RandomSource(), time.Now)
+}

context.go

@@ -0,0 +1,28 @@
+// Copyright (c) The OpenTofu Authors
+// SPDX-License-Identifier: MPL-2.0
+// Copyright (c) 2023 HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package tofutestutils
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/opentofu/tofutestutils/testcontext"
+)
+
+const minCleanupSafety = time.Second * 30
+const maxCleanupSafety = time.Minute * 5
+
+// Context returns a context configured for the test deadline. This function configures a context with 25% safety for
+// any cleanup tasks to finish. For a more flexible function see testcontext.Context.
+func Context(t *testing.T) context.Context {
+	return testcontext.Context(
+		t,
+		4,
+		minCleanupSafety,
+		maxCleanupSafety,
+	)
+}

generate.go

@@ -1,5 +1,7 @@
 // Copyright (c) The OpenTofu Authors
 // SPDX-License-Identifier: MPL-2.0
+// Copyright (c) 2023 HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
 
 package tofutestutils
 

go.mod

@@ -1,3 +1,62 @@
 module github.com/opentofu/tofutestutils
 
 go 1.22
+
+require (
+	github.com/hashicorp/go-hclog v1.6.3
+	github.com/testcontainers/testcontainers-go v0.32.0
+)
+
+require (
+	dario.cat/mergo v1.0.0 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/Microsoft/hcsshim v0.11.5 // indirect
+	github.com/cenkalti/backoff/v4 v4.2.1 // indirect
+	github.com/containerd/containerd v1.7.18 // indirect
+	github.com/containerd/errdefs v0.1.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/cpuguy83/dockercfg v0.3.1 // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v27.0.3+incompatible // indirect
+	github.com/docker/go-connections v0.5.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/fatih/color v1.13.0 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.1 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/klauspost/compress v1.17.4 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/mattn/go-colorable v0.1.12 // indirect
+	github.com/mattn/go-isatty v0.0.14 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.5.0 // indirect
+	github.com/moby/sys/user v0.1.0 // indirect
+	github.com/moby/term v0.5.0 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.0 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
+	github.com/shirou/gopsutil/v3 v3.23.12 // indirect
+	github.com/shoenig/go-m1cpu v0.1.6 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
+	github.com/yusufpapurcu/wmi v1.2.3 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
+	go.opentelemetry.io/otel v1.24.0 // indirect
+	go.opentelemetry.io/otel/metric v1.24.0 // indirect
+	go.opentelemetry.io/otel/trace v1.24.0 // indirect
+	golang.org/x/crypto v0.22.0 // indirect
+	golang.org/x/sys v0.19.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20231016165738-49dd2c1f3d0b // indirect
+	google.golang.org/grpc v1.59.0 // indirect
+	google.golang.org/protobuf v1.33.0 // indirect
+)