add file and HTTP test utilities

- Add WriteTestFile function for creating temporary test files
- Add MockHTTPServer for easy HTTP server testing
- Add HTTPRequestCaptor for inspecting HTTP requests in tests
- Enhance README with new utilities and examples

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>

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)
 }
-```
-
+```

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,29 @@
+package testutils
+
+import (
+	"os"
+	"testing"
+)
+
+func TestWriteTestFile(t *testing.T) {
+	// test creating a file with content
+	content := "test content"
+	filePath := WriteTestFile(t, content)
+
+	// check if file exists
+	if _, err := os.Stat(filePath); os.IsNotExist(err) {
+		t.Errorf("WriteTestFile did not create file at %s", filePath)
+	}
+
+	// check content
+	data, err := os.ReadFile(filePath)
+	if err != nil {
+		t.Errorf("Failed to read test file: %v", err)
+	}
+
+	if string(data) != content {
+		t.Errorf("Expected content %q, got %q", content, string(data))
+	}
+
+	// file should be cleaned up automatically at the end of the test
+}

http_utils.go

@@ -0,0 +1,130 @@
+package testutils
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+)
+
+// MockHTTPServer creates a test HTTP server with the given handler.
+// Returns the server URL and a function to close it.
+func MockHTTPServer(t *testing.T, handler http.Handler) (serverURL string, cleanup func()) {
+	t.Helper()
+
+	server := httptest.NewServer(handler)
+
+	cleanup = func() {
+		server.Close()
+	}
+
+	// register cleanup with t.Cleanup to ensure the server is closed
+	// even if the test fails
+	t.Cleanup(cleanup)
+
+	return server.URL, cleanup
+}
+
+// RequestRecord holds information about a captured HTTP request
+type RequestRecord struct {
+	Method  string
+	Path    string
+	Headers http.Header
+	Body    []byte
+}
+
+// RequestCaptor captures HTTP requests for inspection in tests
+type RequestCaptor struct {
+	mu       sync.Mutex
+	requests []RequestRecord
+}
+
+// Len returns the number of captured requests
+func (c *RequestCaptor) Len() int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return len(c.requests)
+}
+
+// GetRequest returns the request at the specified index
+func (c *RequestCaptor) GetRequest(idx int) (RequestRecord, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if idx < 0 || idx >= len(c.requests) {
+		return RequestRecord{}, false
+	}
+
+	return c.requests[idx], true
+}
+
+// GetRequests returns all captured requests
+func (c *RequestCaptor) GetRequests() []RequestRecord {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	// return a copy to avoid race conditions
+	result := make([]RequestRecord, len(c.requests))
+	copy(result, c.requests)
+	return result
+}
+
+// Reset clears all captured requests
+func (c *RequestCaptor) Reset() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.requests = nil
+}
+
+// add records a new request
+func (c *RequestCaptor) add(rec RequestRecord) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.requests = append(c.requests, rec)
+}
+
+// HTTPRequestCaptor returns a request captor and HTTP handler that captures requests
+// The returned handler will forward requests to the provided next handler if not nil
+func HTTPRequestCaptor(t *testing.T, next http.Handler) (*RequestCaptor, http.Handler) {
+	t.Helper()
+
+	captor := &RequestCaptor{
+		requests: []RequestRecord{},
+	}
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// create a record from the request
+		record := RequestRecord{
+			Method:  r.Method,
+			Path:    r.URL.Path,
+			Headers: r.Header.Clone(),
+		}
+
+		// read and store the body if present
+		if r.Body != nil {
+			// read body
+			bodyBytes, err := io.ReadAll(r.Body)
+			if err != nil {
+				t.Logf("failed to read request body: %v", err)
+			}
+
+			// store the body in the record
+			record.Body = bodyBytes
+
+			// replace the body for downstream handlers
+			r.Body = io.NopCloser(bytes.NewReader(bodyBytes))
+		}
+
+		// add the record to the captor
+		captor.add(record)
+
+		// forward the request if a next handler is provided
+		if next != nil {
+			next.ServeHTTP(w, r)
+		}
+	})
+
+	return captor, handler
+}