Mock

Overview

The mock middleware provides request mocking capabilities for testing and development, returning predefined responses for specified routes. Use it when you need:

API mocking for frontend development
Test fixtures
Stubbing external services

Installation

import "github.com/go-mizu/mizu/middlewares/mock"

Quick Start

app := mizu.New()

// Mock a response
app.Use(mock.New(mock.Routes{
    "GET /api/users": mock.JSON(200, users),
}))

Configuration

Routes Map

type Routes map[string]Response

// Pattern: "METHOD /path"

Examples

JSON Response

app.Use(mock.New(mock.Routes{
    "GET /api/users": mock.JSON(200, []User{
        {ID: 1, Name: "John"},
        {ID: 2, Name: "Jane"},
    }),
}))

Multiple Routes

app.Use(mock.New(mock.Routes{
    "GET /api/users":     mock.JSON(200, users),
    "GET /api/users/1":   mock.JSON(200, user),
    "POST /api/users":    mock.JSON(201, newUser),
    "DELETE /api/users/1": mock.Status(204),
}))

With Headers

app.Use(mock.New(mock.Routes{
    "GET /api/data": mock.Response{
        Status:  200,
        Body:    `{"data": "test"}`,
        Headers: map[string]string{
            "Content-Type":  "application/json",
            "X-Custom":      "value",
        },
    },
}))

From File

app.Use(mock.New(mock.Routes{
    "GET /api/users": mock.File("testdata/users.json"),
}))

Conditional Mocking

app.Use(mock.WithOptions(mock.Options{
    Routes: mockRoutes,
    Enabled: func() bool {
        return os.Getenv("MOCK_API") == "true"
    },
}))

Delay Response

app.Use(mock.New(mock.Routes{
    "GET /api/slow": mock.Response{
        Status: 200,
        Body:   `{"data": "slow"}`,
        Delay:  2 * time.Second,
    },
}))

API Reference

Functions

// New creates mock middleware
func New(routes Routes) mizu.Middleware

// WithOptions creates with configuration
func WithOptions(opts Options) mizu.Middleware

// Response helpers
func JSON(status int, data any) Response
func Text(status int, body string) Response
func Status(status int) Response
func File(path string) Response

Technical Details

Implementation Overview

The mock middleware is built on a thread-safe architecture using sync.RWMutex for concurrent access to mock responses. It supports both path-only and method-specific mocking patterns. Core Components:

Mock struct: Central registry holding mock responses with thread-safe access
Response matching: Two-tier matching system (method+path, then path-only)
Passthrough mode: Configurable behavior for unmatched requests

Request Flow:

Extract request path and method from incoming request
Acquire read lock for concurrent-safe access
Check method-specific mocks first (methods[method][path])
Fall back to path-only mocks (mocks[path])
Apply default response if configured
Either pass through to next handler or return 404

Response Types: The middleware provides helper functions for common response types:

JSON(): Marshal Go data structures to JSON with appropriate headers
Text(): Plain text responses
HTML(): HTML responses with proper content type
File(): Generic file responses with custom content types
Redirect(): HTTP redirects with location headers
Error(): Standardized error responses in JSON format

Thread Safety: All mock registration and retrieval operations are protected by read/write locks, making the middleware safe for concurrent use in multi-threaded environments.

Best Practices

Use environment variable to enable/disable
Keep mock data in separate files
Match production response structure
Add realistic delays for latency testing

Testing

The mock middleware includes comprehensive test coverage for all major functionality:

Test Case	Description	Expected Behavior
TestNew	Creates middleware with predefined mocks	Returns mocked JSON response instead of real handler
TestMock_Register	Registers a mock response for a path	Mock response is served for registered path
TestMock_RegisterMethod	Registers method-specific mock	POST request returns mocked response with status 201
TestMock_Clear	Clears all registered mocks	After clear, real handler is called instead of mock
TestWithOptions_DefaultResponse	Uses default response for unmatched paths	Returns default response (503) for any unmatched path
TestJSON	Creates JSON response helper	Response has correct status and JSON content type
TestText	Creates text response helper	Response contains correct text body and content type
TestHTML	Creates HTML response helper	Response has text/html content type
TestRedirect	Creates redirect response	Response has correct redirect status and Location header
TestError	Creates error response helper	Returns JSON error response with correct status
TestPrefix	Mocks all paths matching prefix	Prefixed paths return mock, non-prefixed pass through
TestPassthrough	Passes unmatched requests to next handler	Real handler is called when no mock matches

static - Static file serving
proxy - Reverse proxy

Overview

Authentication

Security

Rate Limiting & Resilience

Request Processing

Response Processing

Caching

URL Handling

Networking & Proxy

Request Context

Real-time

Static Files

Operations & Monitoring

Advanced

Connection & Protocol

Internationalization

External Integrations

Bot & Client Detection

Overview

Installation

Quick Start

Configuration

Routes Map

Examples

JSON Response

Multiple Routes

With Headers

From File

Conditional Mocking

Delay Response

API Reference

Functions

Technical Details

Implementation Overview

Best Practices

Testing

​Overview

​Installation

​Quick Start

​Configuration

​Routes Map

​Examples

​JSON Response

​Multiple Routes

​With Headers

​From File

​Conditional Mocking

​Delay Response

​API Reference

​Functions

​Technical Details

​Implementation Overview

​Best Practices

​Testing

​Related Middlewares

Overview

Installation

Quick Start

Configuration

Routes Map

Examples

JSON Response

Multiple Routes

With Headers

From File

Conditional Mocking

Delay Response

API Reference

Functions

Technical Details

Implementation Overview

Best Practices

Testing

Related Middlewares