Readme

Signed-off-by: Janos <[email protected]>

README.md

@@ -166,4 +166,32 @@ func TestMyApp(t *testing.T) {
 ```
 
 > [!WARNING]
-> Always use the [test context](#test-context) for timeouts as described above so the backend has time to clean up the test container.
+> Always use the [test context](#test-context) for timeouts as described above so the backend has time to clean up the test container.
+
+## HTTP proxy
+
+This library implements a full HTTP proxy for testing purposes. You can use this package to test if a proxy configuration handles settings correctly. The simplest version to create a proxy is as follows:
+
+```go
+package your_test
+
+import (
+	"testing"
+
+	"github.com/opentofu/tofutestutils"
+)
+
+func TestMyApp(t *testing.T) {
+	proxy := tofutestutils.HTTPProxy(t)
+
+	t.Setenv("http_proxy", proxy.HTTPProxy().String())
+	t.Setenv("https_proxy", proxy.HTTPSProxy().String())
+
+	// Proxy-using code here
+}
+```
+
+> [!NOTE]
+> You can use the HTTP proxy for HTTPS URLs. This is because the connection to the proxy is not necessarily encrypted, the proxy can perform certificate verification. If you use the `HTTPSProxy()` call, you should configure your HTTP clients to accept the certificate presented in the `proxy.CACert()` function.
+
+You can customize the proxy behavior and force connections to go to a specific endpoint. For details, please check [the documentation for the testproxy package](https://pkg.go.dev/github.com/opentofu/tofutestutils/testproxy).

http_proxy.go

@@ -0,0 +1,17 @@
+// 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"
+
+	"github.com/opentofu/tofutestutils/testproxy"
+)
+
+// HTTPProxy starts an HTTP proxy and returns the connection details as a result.
+func HTTPProxy(t *testing.T, options ...testproxy.HTTPOption) testproxy.HTTPService {
+	return testproxy.HTTP(t, options...)
+}

testproxy/README.md

@@ -0,0 +1,27 @@
+# HTTP proxy
+
+This package implements a full HTTP proxy for testing purposes. You can use this package to test if a proxy configuration handles settings correctly. The simplest version to create a proxy is as follows:
+
+```go
+package your_test
+
+import (
+	"testing"
+
+	"github.com/opentofu/tofutestutils/testproxy"
+)
+
+func TestMyApp(t *testing.T) {
+	proxy := testproxy.HTTP(t)
+
+	t.Setenv("http_proxy", proxy.HTTPProxy().String())
+	t.Setenv("https_proxy", proxy.HTTPSProxy().String())
+
+	// Proxy-using code here
+}
+```
+
+> [!NOTE]
+> You can use the HTTP proxy for HTTPS URLs. This is because the connection to the proxy is not necessarily encrypted, the proxy can perform certificate verification. If you use the `HTTPSProxy()` call, you should configure your HTTP clients to accept the certificate presented in the `proxy.CACert()` function.
+
+You can customize the proxy behavior and force connections to go to a specific endpoint. For details, please check [the documentation for this package](https://pkg.go.dev/github.com/opentofu/tofutestutils/testproxy).