TestGen

Kill 90% of test boilerplate. TestGen records your HTTP traffic and generates Go test functions automatically. You fill in the assertions.

What It Does

TestGen generates the boring parts of integration tests:

• Test function structure with subtests
• Request payloads mapped to Go structs
• Basic status code checks
• Proper grouping by endpoint

What you still write:

• Custom assertions
• Test setup (configuring your app in main_test.go)
• ID tracking between requests

Think of it as scaffolding - TestGen gives you 90% of the code, you add the 10% that matters.

Features

• HTTP Traffic Recording: Start a proxy server to intercept and record all HTTP requests and responses
• Automatic Test Generation: Generate Go test files from recorded traffic
• Code Annotation Support: Use @testgen comments to map endpoints to structs
• CRUD Test Support: Automatically generates tests for Create, Read, Update, and Delete operations
• Struct Mapping: Automatically maps JSON payloads to Go struct definitions

What Gets Generated

Before TestGen: You write this entire test by hand (200+ lines for a CRUD flow).

After TestGen:

func testUsers(t *testing.T) {
    app := setup()

    // TODO: Track IDs between requests
    var userID int64

    t.Run("POST /api/v1/users", func(t *testing.T) {
        payload:=  models.User{
        Name:"John",
        Email:"john@example.com",
        }
        resp := makeReq(t, app, http.MethodPost, "/api/v1/users", payload)
        require.Equal(t, http.StatusOK, resp.StatusCode)
        // TODO: Add custom assertions here or parse the response via decode function in the helper file generated by testgen
    })

    // More subtests...
}

You just fill in the TODOs. That's it.

Demo

Installation

go install github.com/muzzii255/testgen@latest

Or clone and build from source:

git clone https://github.com/muzzii255/testgen.git
cd testgen
go build -o testgen .

Usage

Recording HTTP Traffic

Start the proxy server to record HTTP traffic:

testgen record --port 9000 --target 8080

Options:

• --port, -p: Port to run the proxy server on (default: 9000)
• --target, -t: Target backend URL port (default: 8080)

The proxy will intercept requests and save recordings to the ./recordings directory.

Generating Tests

Generate test files from recorded JSON data:

testgen gen --file recordings/your-recording.json

Options:

• --file, -f: Path to the recorded JSON file (required)

Code Annotations

Annotations are optional and can be placed anywhere in your codebase - not just directly above the struct definition. You can write them in the same file as your struct, a separate file, or even in a dedicated annotations file. TestGen will scan all .go files in your project to find them.

To map endpoints to structs for test generation, add @testgen comments in your Go code:

// @testgen router=/api/v1/users struct=User
type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

The annotation format is:

// @testgen router=<endpoint-path> struct=<struct-name>

For external packages:

// @testgen router=/api/v1/users struct=package.StructName

Example of placing annotations in a separate file:

// annotations.go

// @testgen router=/api/v1/users struct=User
// @testgen router=/api/v1/products struct=Product
// @testgen router=/api/v1/orders struct=Order

Project Structure

testgen/
├── cmd/                # CLI command implementations
│   ├── generate.go     # Generate command
│   ├── record.go       # Record command
│   └── root.go         # Root command
├── generator/          # Test generation logic
│   ├── codegen.go     # Code generation from recordings
│   └── generator.go   # Tag scanning and processing
├── proxy/             # HTTP proxy and recording
│   └── proxy.go       # Proxy server implementation
├── structgen/         # Struct parsing and mapping
│   └── structgen.go   # AST-based struct analysis
└── main.go            # Entry point

Workflow

1. Start your backend server on port 8080 (or your preferred port)

2. Start the recording proxy:

   testgen record --port 9000 --target 8080

3. Configure your application to use the proxy (set HTTP_PROXY=http://localhost:9000)

4. Make requests to your application through the proxy

5. Stop the proxy - recordings will be saved automatically

6. Add annotations to your code structs:

   // @testgen router=/api/v1/users struct=models.User
   type User struct {
       // ...
   }

7. Generate tests:

   testgen gen --file recordings/2026-01-01-users.json

8. Find generated tests in the ./gentest directory

Examples

Projects using TestGen:

• test_server - Example Go web application with TestGen-generated tests

Generated Test Structure

The generated tests include:

• Setup functions for test initialization
• Test cases for each HTTP method (GET, POST, PUT, DELETE)
• Status code assertions
• Payload mapping from JSON to Go structs

Generated Files

TestGen creates a ./gentest/ directory with:

Initial Setup (generated once)

• main_test.go - Test suite setup with TestMain and example test
• testutils.go - Helper functions (makeReq, decodeResp, Ptr)

These files are only created if they don't exist. TestGen never overwrites them, so you can customize them freely.

Generated Tests (each testgen gen run)

• {endpoint}_test.go - One file per endpoint with all CRUD operations

Example:

gentest/
├── main_test.go       # Your test setup (edit this once)
├── testutils.go       # Helper functions (customize as needed)
├── users_test.go      # Generated from recordings
└── offices_test.go    # Generated from recordings

Important: Update main_test.go to initialize your actual app:

var testApp *fiber.App // Change to your framework

func TestMain(m *testing.M) {
    testApp = setupYourApp() // Your initialization
}

Requirements

• Go 1.25 or later
• A Go web application to test

Dependencies

• github.com/spf13/cobra - CLI framework
• golang.org/x/tools - Go tools for code analysis

License

This project is licensed under the MIT License - see the LICENSE file for details.