Merge pull request #1 from go-pkgz/add-test-utilities

Add file and HTTP test utilities

Author: umputun

CLAUDE.md

@@ -0,0 +1,21 @@
+# Go-pkgz/testutils Commands and Guidelines
+
+## Build/Test/Lint Commands
+- Build: `go build -race`
+- Test all packages: `go test -race -covermode=atomic -coverprofile=profile.cov ./...`
+- Run single test: `go test -run=TestName ./path/to/package`
+- Run test in verbose mode: `go test -v -run=TestName ./path/to/package`
+- Lint: `golangci-lint run`
+
+## Code Style Guidelines
+- Use camelCase for functions and variables, with clear descriptive names
+- Test files use `_test.go` suffix with table-driven tests using anonymous structs
+- Pass context as first parameter when relevant
+- Use t.Helper() in test utility functions for better error reporting
+- Employ t.Run() for subtests with descriptive names
+- Always defer resource cleanup in tests and production code
+- Return errors rather than panicking; handle errors explicitly
+- Include t.Skip() for integration tests when testing.Short() is true
+- Prefer testify's require/assert package for test assertions
+- Use proper Go modules import ordering (standard lib, external, internal)
+- Always close resources using defer pattern after creation (eg. defer container.Close(ctx))

README.md

@@ -4,20 +4,132 @@ Package `testutils` provides useful test helpers.
 
 ## Details
 
-- `CaptureStdout`, `CaptureSterr` and `CaptureStdoutAndStderr`: capture stdout, stderr or both for testing purposes. All capture functions are not thread-safe if used in parallel tests, and usually it is better to pass a custom io.Writer to the function under test instead.
+### Capture Utilities
 
-- `containers`: provides test containers for integration testing:
-    - `SSHTestContainer`: SSH server container for testing SSH connections and operations
-    - `PostgresTestContainer`: PostgreSQL database container with automatic database creation
-    - `MySQLTestContainer`: MySQL database container with automatic database creation
-    - `MongoTestContainer`: MongoDB container with support for multiple versions (5, 6, 7)
-    - `LocalstackTestContainer`: LocalStack container with S3 service for AWS testing
+- `CaptureStdout`: Captures stdout output from the provided function
+- `CaptureStderr`: Captures stderr output from the provided function
+- `CaptureStdoutAndStderr`: Captures both stdout and stderr from the provided function
+
+These capture utilities are useful for testing functions that write directly to stdout/stderr. They redirect the standard outputs to a buffer and return the captured content as a string.
+
+**Important Note**: The capture functions are not thread-safe if used in parallel tests. For concurrent tests, it's better to pass a custom io.Writer to the function under test instead.
+
+### File Utilities
+
+- `WriteTestFile`: Creates a temporary file with specified content and returns its path. The file is automatically cleaned up after the test completes.
+
+### HTTP Test Utilities
+
+- `MockHTTPServer`: Creates a test HTTP server with the given handler. Returns the server URL and a cleanup function.
+- `HTTPRequestCaptor`: Returns a request captor and an HTTP handler that captures and records HTTP requests for later inspection.
+
+### Test Containers
+
+The `containers` package provides several test containers for integration testing:
+
+- `SSHTestContainer`: SSH server container for testing SSH connections and operations
+- `PostgresTestContainer`: PostgreSQL database container with automatic database creation
+- `MySQLTestContainer`: MySQL database container with automatic database creation
+- `MongoTestContainer`: MongoDB container with support for multiple versions (5, 6, 7)
+- `LocalstackTestContainer`: LocalStack container with S3 service for AWS testing
 
 ## Install and update
 
 `go get -u github.com/go-pkgz/testutils`
 
-### Example usage:
+## Example Usage
+
+### Capture Functions
+
+```go
+// Capture stdout
+func TestMyFunction(t *testing.T) {
+    output := testutils.CaptureStdout(t, func() {
+        fmt.Println("Hello, World!")
+    })
+    
+    assert.Equal(t, "Hello, World!\n", output)
+}
+
+// Capture stderr
+func TestErrorOutput(t *testing.T) {
+    errOutput := testutils.CaptureStderr(t, func() {
+        fmt.Fprintln(os.Stderr, "Error message")
+    })
+    
+    assert.Equal(t, "Error message\n", errOutput)
+}
+
+// Capture both stdout and stderr
+func TestBothOutputs(t *testing.T) {
+    stdout, stderr := testutils.CaptureStdoutAndStderr(t, func() {
+        fmt.Println("Standard output")
+        fmt.Fprintln(os.Stderr, "Error output")
+    })
+    
+    assert.Equal(t, "Standard output\n", stdout)
+    assert.Equal(t, "Error output\n", stderr)
+}
+```
+
+### File Utilities
+
+```go
+// Create a temporary test file
+func TestWithTempFile(t *testing.T) {
+    content := "test file content"
+    filePath := testutils.WriteTestFile(t, content)
+    
+    // Use the file in your test
+    data, err := os.ReadFile(filePath)
+    require.NoError(t, err)
+    assert.Equal(t, content, string(data))
+    
+    // No need to clean up - it happens automatically when the test ends
+}
+```
+
+### HTTP Test Utilities
+
+```go
+// Create a mock HTTP server
+func TestWithMockServer(t *testing.T) {
+    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        w.WriteHeader(http.StatusOK)
+        w.Write([]byte("response"))
+    })
+    
+    serverURL, _ := testutils.MockHTTPServer(t, handler)
+    
+    // Make requests to the server
+    resp, err := http.Get(serverURL + "/path")
+    require.NoError(t, err)
+    defer resp.Body.Close()
+    
+    assert.Equal(t, http.StatusOK, resp.StatusCode)
+}
+
+// Capture and inspect HTTP requests
+func TestWithRequestCaptor(t *testing.T) {
+    // Create a request captor
+    captor, handler := testutils.HTTPRequestCaptor(t, nil)
+    
+    // Create a server with the capturing handler
+    serverURL, _ := testutils.MockHTTPServer(t, handler)
+    
+    // Make a request
+    http.Post(serverURL+"/api", "application/json", 
+              strings.NewReader(`{"key":"value"}`))
+    
+    // Inspect the captured request
+    req, _ := captor.GetRequest(0)
+    assert.Equal(t, http.MethodPost, req.Method)
+    assert.Equal(t, "/api", req.Path)
+    assert.Equal(t, `{"key":"value"}`, string(req.Body))
+}
+```
+
+### Test Containers
 
 ```go
 // PostgreSQL test container
@@ -84,5 +196,4 @@ func TestWithS3(t *testing.T) {
     })
     require.NoError(t, err)
 }
-```
-
+```

capture_test.go

@@ -5,6 +5,8 @@ import (
 	"os"
 	"strings"
 	"testing"
+	
+	"github.com/stretchr/testify/require"
 )
 
 func TestCaptureStdout(t *testing.T) {
@@ -38,9 +40,7 @@ func TestCaptureStdout(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			got := CaptureStdout(t, tt.f)
-			if got != tt.want {
-				t.Errorf("CaptureStdout() = %q, want %q", got, tt.want)
-			}
+			require.Equal(t, tt.want, got, "CaptureStdout() returned unexpected output")
 		})
 	}
 }
@@ -76,9 +76,7 @@ func TestCaptureStderr(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			got := CaptureStderr(t, tt.f)
-			if got != tt.want {
-				t.Errorf("CaptureStderr() = %q, want %q", got, tt.want)
-			}
+			require.Equal(t, tt.want, got, "CaptureStderr() returned unexpected output")
 		})
 	}
 }
@@ -129,12 +127,8 @@ func TestCaptureStdoutAndStderr(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			gotOut, gotErr := CaptureStdoutAndStderr(t, tt.f)
-			if gotOut != tt.wantOut {
-				t.Errorf("CaptureStdoutAndStderr() stdout = %q, want %q", gotOut, tt.wantOut)
-			}
-			if gotErr != tt.wantErr {
-				t.Errorf("CaptureStdoutAndStderr() stderr = %q, want %q", gotErr, tt.wantErr)
-			}
+			require.Equal(t, tt.wantOut, gotOut, "CaptureStdoutAndStderr() stdout returned unexpected output")
+			require.Equal(t, tt.wantErr, gotErr, "CaptureStdoutAndStderr() stderr returned unexpected output")
 		})
 	}
 }

file_utils.go

@@ -0,0 +1,34 @@
+package testutils
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// WriteTestFile creates a temporary file with the given content and returns its path.
+// The file is automatically cleaned up after the test completes.
+func WriteTestFile(t *testing.T, content string) string {
+	t.Helper()
+
+	// create a temporary directory for the file
+	tempDir, err := os.MkdirTemp("", "testutils-")
+	if err != nil {
+		t.Fatalf("failed to create temp directory: %v", err)
+	}
+
+	// register cleanup to remove the temporary directory and its contents
+	t.Cleanup(func() {
+		if err := os.RemoveAll(tempDir); err != nil {
+			t.Logf("failed to remove temporary directory %s: %v", tempDir, err)
+		}
+	})
+
+	// create a file with a unique name
+	tempFile := filepath.Join(tempDir, "testfile")
+	if err := os.WriteFile(tempFile, []byte(content), 0o600); err != nil {
+		t.Fatalf("failed to write test file: %v", err)
+	}
+
+	return tempFile
+}

file_utils_test.go

@@ -0,0 +1,25 @@
+package testutils
+
+import (
+	"os"
+	"testing"
+	
+	"github.com/stretchr/testify/require"
+)
+
+func TestWriteTestFile(t *testing.T) {
+	// test creating a file with content
+	content := "test content"
+	filePath := WriteTestFile(t, content)
+
+	// check if file exists
+	_, err := os.Stat(filePath)
+	require.False(t, os.IsNotExist(err), "WriteTestFile did not create file at %s", filePath)
+	
+	// check content
+	data, err := os.ReadFile(filePath)
+	require.NoError(t, err, "Failed to read test file")
+	require.Equal(t, content, string(data), "File content doesn't match expected")
+	
+	// file should be cleaned up automatically at the end of the test
+}