Как писать unit-тесты для обработчиков Echo с помощью httptest?

Тестирование хендлеров Echo через httptest

Echo спроектирован так, что хендлеры принимают echo.Context — интерфейс, который легко создать в тестах. Стандартная библиотека net/http/httptest предоставляет httptest.NewRecorder() и httptest.NewRequest(), а Echo добавляет e.NewContext(req, rec) для сборки контекста.

Базовый паттерн

package handlers_test

import (
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"strings"
	"testing"

	"github.com/labstack/echo/v4"
	"github.com/stretchr/testify/assert"
)

func TestGetUser(t *testing.T) {
	e := echo.New()

	req := httptest.NewRequest(http.MethodGet, "/users/42", nil)
	rec := httptest.NewRecorder()

	c := e.NewContext(req, rec)
	c.SetParamNames("id")
	c.SetParamValues("42")

	// Вызываем хендлер напрямую
	if assert.NoError(t, getUser(c)) {
		assert.Equal(t, http.StatusOK, rec.Code)

		var body map[string]string
		json.Unmarshal(rec.Body.Bytes(), &body)
		assert.Equal(t, "42", body["id"])
	}
}

Тест POST с JSON-телом

func TestCreateUser(t *testing.T) {
	e := echo.New()

	payload := `{"name":"Alice","email":"alice@example.com"}`
	req := httptest.NewRequest(
		http.MethodPost,
		"/users",
		strings.NewReader(payload),
	)
	req.Header.Set(echo.MIMEApplicationJSON, "application/json")
	req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON)

	rec := httptest.NewRecorder()
	c := e.NewContext(req, rec)

	if assert.NoError(t, createUser(c)) {
		assert.Equal(t, http.StatusCreated, rec.Code)
		assert.Contains(t, rec.Body.String(), "Alice")
	}
}

Тест с middleware (через ServeHTTP)

Если хендлер требует данные, выставляемые middleware (например, JWT claims), используйте полный HTTP-стек через e.ServeHTTP:

func TestAuthenticatedEndpoint(t *testing.T) {
	e := echo.New()
	e.Use(middleware.JWT([]byte("secret")))
	e.GET("/profile", profileHandler)

	token := "eyJ..." // валидный JWT для тестов
	req := httptest.NewRequest(http.MethodGet, "/profile", nil)
	req.Header.Set("Authorization", "Bearer "+token)
	rec := httptest.NewRecorder()

	e.ServeHTTP(rec, req)
	assert.Equal(t, http.StatusOK, rec.Code)
}

Мокирование зависимостей

// Интерфейс репозитория
type UserRepo interface {
	FindByID(id string) (*User, error)
}

// Мок для тестов
type mockUserRepo struct {
	user *User
	err  error
}
func (m *mockUserRepo) FindByID(id string) (*User, error) { return m.user, m.err }

// Хендлер принимает зависимость через замыкание
func makeGetUserHandler(repo UserRepo) echo.HandlerFunc {
	return func(c echo.Context) error {
		u, err := repo.FindByID(c.Param("id"))
		if err != nil {
			return echo.ErrNotFound
		}
		return c.JSON(http.StatusOK, u)
	}
}

func TestGetUserWithMock(t *testing.T) {
	mock := &mockUserRepo{user: &User{Name: "Bob"}}
	h := makeGetUserHandler(mock)

	e := echo.New()
	req := httptest.NewRequest(http.MethodGet, "/", nil)
	rec := httptest.NewRecorder()
	c := e.NewContext(req, rec)
	c.SetParamNames("id")
	c.SetParamValues("1")

	assert.NoError(t, h(c))
	assert.Equal(t, http.StatusOK, rec.Code)
}

Подводные камни

• SetParamNames/SetParamValues обязательны: если не вызвать их перед хендлером, c.Param("id") вернёт пустую строку — тест пройдёт, но не проверит то, что нужно.
• Content-Type для Bind: забытый заголовок Content-Type: application/json приводит к тому, что c.Bind() не разбирает JSON и возвращает пустую структуру без ошибки.
• e.NewContext vs ServeHTTP: прямой вызов хендлера обходит middleware — тесты с JWT/CORS/Recover требуют e.ServeHTTP.
• Глобальное состояние echo.New(): создавайте новый echo.New() в каждом тесте или используйте t.Cleanup(), иначе маршруты между тестами накапливаются.
• rec.Body после хендлера: тело пишется в буфер только после завершения хендлера. Чтение до этого даст пустой результат.
• Ошибки хендлера не рендерятся автоматически: если хендлер возвращает error, статус-код в recorder будет 200 — нужно явно проверять возвращённую ошибку или использовать e.ServeHTTP.

• Давать ответ про тестирование Echo handler-ов только на уровне определения, не показывая поведение в реальном приложении.
• Игнорировать границы ответственности вокруг темы «тестирование Echo handler-ов»: кто отменяет работу, кто владеет ресурсом и где формируется ответ клиенту.
• Не связывать тестирование Echo handler-ов с observability, тестированием или безопасностью, когда это влияет на продакшен-поведение.

• Точно объясняет, что именно делает тестирование Echo handler-ов и где это используется в Go-коде.
• Связывает тестирование Echo handler-ов с корректным lifecycle запроса, отменой, конкурентностью или конфигурацией сервера там, где это уместно.
• Не изобретает API и опирается на реальные контракты официальной документации.