pkg/contract -- Built-in Contract Testing

Design Philosophy

Schema declares Input: CreateUserRequest{Name, Email}
Schema declares Output: UserResponse{ID, Name, Email}
 |
Request {"name":"alice"} <- missing email -> Input validation fails
Response {"id":1,"name":"alice"} <- missing email -> Output validation fails

Bidirectional Schema Validation

Quick Start

Manual Testing

import (
 "testing"
 "github.com/maoxiaoyue/hypgo/pkg/contract"
)
func TestCreateUser(t *testing.T) {
 r := setupRouter() // Router with Schema routes registered
 contract.Test(t, r, contract.TestCase{
 Route: "POST /api/users",
 Input: `{"name":"alice","email":"alice@test.com"}`,
 ExpectStatus: 201,
 ExpectSchema: true, // Validate response conforms to Output schema
 })
}

Auto-test All Routes

func TestAllRoutes(t *testing.T) {
 r := setupRouter()
 contract.TestAll(t, r) // Automatically generates tests for each schema route
}

Simple Route Existence Testing

func TestHealthEndpoint(t *testing.T) {
 r := setupRouter()
 contract.TestRoute(t, r, "GET", "/health", 200)
}

TestCase Fields

type TestCase struct {
 Route string // "METHOD /path", e.g. "POST /api/users"
 Input string // JSON request body
 Headers map[string]string // Custom request headers
 Query map[string]string // URL query parameters
 ExpectStatus int // Expected HTTP status code
 ExpectSchema bool // Whether to validate response against Output schema
 ExpectBody string // Exact match response body (optional)
}

Validation Mechanisms

Schema Validation (ExpectSchema: true)

// Schema declaration
r.Schema(schema.Route{
 Method: "GET",
 Path: "/api/users/:id",
 Output: UserResponse{}, // Has 3 required fields: ID, Name, Email
}).Handle(getUserHandler)
// If handler returns {"id":1} -> fails (missing name, email)
// If handler returns {"id":1,"name":"a","email":"b"} -> passes

Required Field Rules

Status Code Validation

Exact Body Match

Multi-Protocol Support

// TestAll with mixed protocols
schema.RegisterGRPC("UserService/CreateUser", "Create user", req, resp)
schema.RegisterBot("/start", "Start the bot", nil, WelcomeMsg{})
contract.TestAll(t, router)
// → REST routes: full HTTP testing
// → gRPC routes: schema completeness validation
// → Bot routes: schema completeness validation

Automatic Test Generation (TestAll — REST)

Path Parameter Resolution

Status Code Inference

Request Body Generation

Complete Example

package api_test
import (
 "testing"
 "github.com/maoxiaoyue/hypgo/pkg/contract"
 "github.com/maoxiaoyue/hypgo/pkg/router"
 "github.com/maoxiaoyue/hypgo/pkg/schema"
)
type CreateUserReq struct {
 Name string `json:"name"`
 Email string `json:"email"`
}
type UserResp struct {
 ID int `json:"id"`
 Name string `json:"name"`
 Email string `json:"email"`
}
func setupRouter() *router.Router {
 r := router.New()
 r.Schema(schema.Route{
 Method: "POST",
 Path: "/api/users",
 Summary: "Create user",
 Input: CreateUserReq{},
 Output: UserResp{},
 Responses: map[int]schema.ResponseSchema{
 201: {Description: "Created"},
 },
 }).Handle(createUserHandler)
 r.Schema(schema.Route{
 Method: "GET",
 Path: "/api/users/:id",
 Output: UserResp{},
 }).Handle(getUserHandler)
 r.GET("/health", healthHandler)
 return r
}
// Manual test for a specific route
func TestCreateUser(t *testing.T) {
 r := setupRouter()
 contract.Test(t, r, contract.TestCase{
 Route: "POST /api/users",
 Input: `{"name":"alice","email":"alice@test.com"}`,
 ExpectStatus: 201,
 ExpectSchema: true,
 })
}
// Test with query parameters
func TestSearchUsers(t *testing.T) {
 r := setupRouter()
 contract.Test(t, r, contract.TestCase{
 Route: "GET /api/users",
 Query: map[string]string{"page": "1", "limit": "10"},
 ExpectStatus: 200,
 })
}
// Test with custom headers
func TestAuthRequired(t *testing.T) {
 r := setupRouter()
 contract.Test(t, r, contract.TestCase{
 Route: "GET /api/admin",
 Headers: map[string]string{"Authorization": "Bearer test-token"},
 ExpectStatus: 200,
 })
}
// One-click test for all schema routes
func TestAllContracts(t *testing.T) {
 r := setupRouter()
 contract.TestAll(t, r)
}
// Simple route check
func TestHealth(t *testing.T) {
 r := setupRouter()
 contract.TestRoute(t, r, "GET", "/health", 200)
}

Architecture

pkg/contract/
├── contract.go Test(), TestAll(), TestRoute() core test functions
├── validate.go validateResponse(), validateRequest(), validateRequiredFields()
├── generate.go generateTestCase(), generateMinimalJSON(), resolvePath()
└── contract_test.go 24 unit tests

Dependencies

pkg/contract -> pkg/router (Router.ServeHTTP to execute requests)
 -> pkg/schema (Global() to look up schema metadata)
 -> net/http/httptest (simulate HTTP requests)

Relationship with Schema

Schema-first Routes Contract Testing
+------------------+ +------------------+
| Route{ | | TestCase{ |
| Input: Req{} |----->| ExpectSchema: |
| Output: Resp{} | | true |
| Responses: ... | | } |
| } | | |
+------------------+ +------------------+
 | |
 +--- schema.Global() ----+
 (shared Registry)