> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mock

> Request mocking middleware for testing and development.

## 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

```go theme={null}
import "github.com/go-mizu/mizu/middlewares/mock"
```

## Quick Start

```go theme={null}
app := mizu.New()

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

## Configuration

### Routes Map

```go theme={null}
type Routes map[string]Response

// Pattern: "METHOD /path"
```

## Examples

### JSON Response

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

### Multiple Routes

```go theme={null}
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

```go theme={null}
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

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

### Conditional Mocking

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

### Delay Response

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

## API Reference

### Functions

```go theme={null}
// 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:**

1. Extract request path and method from incoming request
2. Acquire read lock for concurrent-safe access
3. Check method-specific mocks first (`methods[method][path]`)
4. Fall back to path-only mocks (`mocks[path]`)
5. Apply default response if configured
6. 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              |

## Related Middlewares

* [static](/middlewares/static) - Static file serving
* [proxy](/middlewares/proxy) - Reverse proxy