GoAPIpretender

README

GoAPIpretender

A lightweight, configurable API mock server for Go tests.

Overview

GoAPIpretender is a mock HTTP server designed for testing API interactions in Go. It allows developers to:

• Simulate API responses without external dependencies
• Validate HTTP methods, paths, headers, parameters, and payloads
• Log validation errors without breaking tests (unless explicitly configured)
• Ensure API clients strictly follow expected contract

---

Installation

Use go get to install GoAPIpretender:

go get github.com/csrar/GoAPIpretender

---

Usage

1 - Basic Mock Server Setup

package main

import (
	"fmt"
	"net/http"
	"testing"

	"github.com/csrar/GoAPIpretender"
)

func TestAPI(t *testing.T) {
	mock := GoAPIpretender.NewConfiguredMockServer(GoAPIpretender.ServerMockConfig{
		Path: "/api/test",
		Method: "POST",
		ResponseStatus: http.StatusCreated,
		ResponseBody: []byte(`{"message": "success"}`),
		T: t, // ✅ Ensures validation errors fail the test
	})
	defer mock.Stop()

	url := mock.Start()
	req, _ := http.NewRequest("POST", url+"/api/test", nil)
	resp, _ := http.DefaultClient.Do(req)

	if resp.StatusCode != http.StatusCreated {
		t.Errorf("Expected 201 Created, got %d", resp.StatusCode)
	}
}

This test creates a mock server, validates the request, and ensures the response is correct.

---

Validation Behavior

GoAPIpretender validates incoming API requests based on the expected configuration.

Scenario	T is set (*testing.T)	T is NOT set
Request method is incorrect	❌ Test fails (t.Error())	⚠️ Logs error, returns configured response
Request path is incorrect	❌ Test fails	⚠️ Logs error, returns configured response
Missing/Incorrect headers	❌ Test fails	⚠️ Logs error, returns configured response
Missing query parameters	❌ Test fails	⚠️ Logs error, returns configured response
Payload does not match expected	❌ Test fails	⚠️ Logs error, returns configured response

Important: If T is not set, validation errors will NOT fail the test but will be logged.

If you want strict test failures, ensure T is set in ServerMockConfig. If T is not set, the test will not fail, but errors will be logged.

---

Configuring Mock API Behavior

2- Customizing Expected Requests

mock := GoAPIpretender.NewConfiguredMockServer(GoAPIpretender.ServerMockConfig{
	Path: "/api/data",
	Method: "GET",
	Headers: map[string]string{"Authorization": "Bearer token123"},
	Parameters: map[string]string{"id": "42"},
	Payload: []byte(`{"key":"value"}`),
	T: t,
})

This ensures only GET requests with valid headers, parameters, and payloads are accepted.

3- Customizing Responses

	mock.SetResponseStatus(http.StatusOK).
	SetResponseHeader(map[string]string{"Content-Type": "application/json"}).
	SetResponseBody([]byte(`{"message": "ok"}`))

The server now returns 200 OK with a JSON response.

---

Initializing Return Values Without Validations

In some cases, you may want to return a response without enforcing validations on method, path, headers, or payload. This can be useful in tests where users need to mock different responses from their services. This can be achieved by simply setting the desired response values without specifying expected request conditions.

mock := GoAPIpretender.NewDefaultMockServer().
	SetResponseStatus(http.StatusOK).
	SetResponseHeader(map[string]string{"Content-Type": "application/json"}).
	SetResponseBody([]byte(`{"message": "unvalidated response"}`))

This allows the mock server to always return the specified response, regardless of the request details.

Mock API Lifecycle

Start the Server

url := mock.Start()

Stop the Server

mock.Stop()

Always call Stop() after the test to clean up resources.

ServerMockConfig is Mutable

ServerMockConfig is a mutable object, meaning that if you modify its values during test execution, it may affect other tests running in parallel.

What This Means

• If multiple tests share the same instance of ServerMockConfig and modify values, it could lead to false test validations.
• This is especially important in parallel test execution (t.Parallel()).

Best Practice: Always Use a New Instance Per Test

To avoid conflicts, always create a new instance of ServerMockConfig for each test instead of reusing a shared instance.

func TestMockServer(t *testing.T) {
    config := GoAPIpretender.ServerMockConfig{
        Path: "/test",
        Method: "GET",
        ResponseStatus: http.StatusOK,
    }

    mock := GoAPIpretender.NewConfiguredMockServer(config)
    defer mock.Stop()

    url := mock.Start()
    // Your test logic here...
}

---

Builder Methods

Method	Description	Example
NewDefaultMockServer()	Creates a mock server with default settings	mock := GoAPIpretender.NewDefaultMockServer()
SetCustomHandler(handler http.HandlerFunc)	Sets a custom handler func, if provided all other validations and return values will be ignored	mock.SetCustomHandler(func(w http.ResponseWriter, r *http.Request) {})
SetMethod(method string)	Sets expected HTTP method	mock.SetMethod("POST")
SetPath(path string)	Sets expected request path	mock.SetPath("/api/test")
SetT(t *testing.T)	Attaches a test instance for failure logging	mock.SetT(t)
SetPayload(payload []byte)	Sets expected request body	mock.SetPayload([]byte({"key":"value"}))
SetHeaders(headers map[string]string)	Set expected headers. It overrides existing headers	mock.SetHeaders(map[string]string{"Content-Type": "application/json"})
SetResponseStatus(status int)	Sets response HTTP status code	mock.SetResponseStatus(201)
SetResponseHeader(headers map[string]string)	Sets response headers. It overrides existing headers	mock.SetResponseHeader(map[string]string{"Content-Type": "application/json"})
SetResponseBody(body []byte)	Sets response body	mock.SetResponseBody([]byte({"message":"ok"}))

---

Why Use GoAPIpretender?

• Zero external dependencies (uses Go’s built-in httptest.Server)

• Fully configurable (method, path, headers, query params, payloads, responses)

• Fast & lightweight (ideal for unit tests)

• Ensures API contract compliance

---

License

This project is licensed under the MIT License.

---

---

Need Help?

GitHub: GoAPIpretender Repo

Happy Testing!

Documentation

Index

• type ServerMock
  • func NewConfiguredMockServer(config ServerMockConfig) *ServerMock
  • func NewDefaultMockServer() *ServerMock
  • func (s *ServerMock) Server() *httptest.Server
  • func (s *ServerMock) SetCustomHandler(handler http.HandlerFunc) *ServerMock
  • func (s *ServerMock) SetHeaders(headers map[string]string) *ServerMock
  • func (s *ServerMock) SetJSONResponse(body string) (*ServerMock, error)
  • func (s *ServerMock) SetMethod(method string) *ServerMock
  • func (s *ServerMock) SetPath(path string) *ServerMock
  • func (s *ServerMock) SetPayload(payload string) *ServerMock
  • func (s *ServerMock) SetResponseBody(body string) *ServerMock
  • func (s *ServerMock) SetResponseHeader(headers map[string]string) *ServerMock
  • func (s *ServerMock) SetResponseStatus(status int) *ServerMock
  • func (s *ServerMock) SetT(t T) *ServerMock
  • func (s *ServerMock) Start() string
  • func (s *ServerMock) Stop()
• type ServerMockConfig
• type T

Types

type ServerMock

type ServerMock struct {
	// contains filtered or unexported fields
}

func NewConfiguredMockServer

func NewConfiguredMockServer(config ServerMockConfig) *ServerMock

func NewDefaultMockServer

func NewDefaultMockServer() *ServerMock

func (*ServerMock) Server

func (s *ServerMock) Server() *httptest.Server

func (*ServerMock) SetCustomHandler

func (s *ServerMock) SetCustomHandler(handler http.HandlerFunc) *ServerMock

func (*ServerMock) SetHeaders

func (s *ServerMock) SetHeaders(headers map[string]string) *ServerMock

func (*ServerMock) SetJSONResponse

func (s *ServerMock) SetJSONResponse(body string) (*ServerMock, error)

func (*ServerMock) SetMethod

func (s *ServerMock) SetMethod(method string) *ServerMock

func (*ServerMock) SetPath

func (s *ServerMock) SetPath(path string) *ServerMock

func (*ServerMock) SetPayload

func (s *ServerMock) SetPayload(payload string) *ServerMock

func (*ServerMock) SetResponseBody

func (s *ServerMock) SetResponseBody(body string) *ServerMock

func (*ServerMock) SetResponseHeader

func (s *ServerMock) SetResponseHeader(headers map[string]string) *ServerMock

func (*ServerMock) SetResponseStatus

func (s *ServerMock) SetResponseStatus(status int) *ServerMock

func (*ServerMock) SetT

func (s *ServerMock) SetT(t T) *ServerMock

func (*ServerMock) Start

func (s *ServerMock) Start() string

func (*ServerMock) Stop

func (s *ServerMock) Stop()

type ServerMockConfig

type ServerMockConfig struct {
	Path           string
	Method         string
	ContentType    string
	Payload        string
	Parameters     map[string]string
	Headers        map[string]string
	ResponseStatus int
	ResponseHeader map[string]string
	ResponseBody   string
	CustonHandler  http.HandlerFunc
	T              T
}

type T

type T interface {
	Error(args ...any)
	Errorf(format string, args ...any)
}