GOAT Integration Tests¶
GOAT (Go Application Testing) — фреймворк для интеграционного тестирования Go-микросервисов.
Включение генерации тестов¶
Простой вариант¶
Расширенная конфигурация¶
applications:
- name: api
goat_tests_config:
enabled: true
binary_path: /tmp/my-custom-path
transport: [api, sys]
Выбор пути конфигурации: use_envs vs OnlineConf bootstrap¶
GOAT-тесты поддерживают два пути загрузки конфигурации сервиса в тестовом окружении.
Recommended: use_envs: true (без OnlineConf bootstrap)¶
applications:
- name: api
use_envs: true
goat_tests_config:
enabled: true
binary_path: /tmp/api
transport: [api, sys]
При use_envs: true в составе goat_tests:
- Цель
generate-test-env-{app}исключается из зависимостейgoat-tests-{app} - Тестовый бинарник читает конфигурацию из переменных окружения (
OC_*), которые передаются черезgtt.NewExecutorBuilder().WithEnv(...) - MySQL и
onlineconf-updaterдля тестов не требуются
Reference-конфиг: test/docker-integration/configs/rest-envs-goat/project.yaml.
Alternative: use_envs: false (с OnlineConf bootstrap)¶
При use_envs: false цель goat-tests-{app} зависит от generate-test-env-{app}, которая:
- Запускает
make onlineconf-update-tests— ожидает файлtests/etc/onlineconf-updater.confи работающий MySQL - Запускает
go run github.com/Educentr/goat/cmd/testutil generate-env— генерируетtests/etc/onlineconf/onlineconf.env
Важно: генератор не создаёт ни tests/etc/onlineconf-updater.conf, ни SQL-bootstrap для тестового MySQL. Эта инфраструктура должна быть подготовлена вручную (или CI-скриптом). Для большинства проектов проще использовать use_envs: true.
Генерируемые файлы¶
После запуска генератора в директории tests/ появятся:
| Файл | Описание |
|---|---|
psg_app_gen.go |
Инициализация тестового окружения |
psg_base_suite_gen.go |
Базовый test suite |
psg_config_gen.go |
Конфигурация сервиса |
psg_helpers_gen.go |
HTTP клиент, retry логика |
psg_init_gen.go |
Интерфейс инициализации |
psg_main_test.go |
Точка входа для тестов |
Требования¶
- Go 1.27+
- Docker (для testcontainers)
- Скомпилированный бинарник приложения
Настройка проекта¶
1. Создайте init.go¶
Это обязательный файл, реализующий интерфейс TestEnvInitializer. Сгенерированный psg_init_gen.go подаёт defaultTestEnvInitializer{}, которая упадёт с panic-сообщением: пример в этом сообщении хардкодит psql/xray как иллюстрацию — для проектов без БД и внешних сервисов используйте минимальный шаблон ниже.
Реализация регистрируется инициализатором переменной:
а не присваиванием testEnvInit из init(): init() в сгенерированных проектах запрещён линтером (gochecknoinits) — неявный side-effect при импорте, зависящий от порядка инициализации пакетов. Инициализатор переменной срабатывает в тот же момент, но явно называет, кто кого подменяет; SetTestEnvInitializer возвращает переданное значение именно для того, чтобы вызов можно было записать как инициализатор. Чтение (GetEnv() из сгенерированного TestMain) происходит после того, как инициализация переменных пакета завершилась, так что подмена не теряется.
Минимальный init.go (без БД и внешних сервисов)¶
Подходит для сервисов, в которых goat-тесты только проверяют HTTP/gRPC контракт через бинарник, без зависимостей от postgres/xray/redis:
package tests
import (
gtt "github.com/Educentr/goat"
"github.com/Educentr/goat/services"
"github.com/Educentr/goat/testutil"
)
type testEnvInitializerImpl struct{}
func (t *testEnvInitializerImpl) InitTestEnv() (testutil.TestAppConfig, *gtt.Env) {
// Используйте сгенерированную NewYourProjectConfig() — имя зависит от main.name
// (для name: "my-service" → NewMyServiceConfig)
cfg := NewYourProjectConfig()
// Пустой ServicesMap — никаких внешних сервисов в тестовом окружении
manager := services.NewManager(services.NewServicesMap(), services.DefaultManagerConfig())
env := gtt.NewEnv(gtt.EnvConfig{}, manager)
return cfg, env
}
var _ = SetTestEnvInitializer(&testEnvInitializerImpl{})
При таком init.go также нужно реализовать NewExecutor() — простейший вариант для use_envs: true проектов: загрузить переменные из .env-{app}.example через testutil.LoadEnvFile() и передать в WithEnv().
Полный пример (с postgres и миграциями)¶
package tests
import (
"context"
"database/sql"
"fmt"
"os"
"path/filepath"
gtt "github.com/Educentr/goat"
"github.com/Educentr/goat-services/psql"
"github.com/Educentr/goat/services"
"github.com/Educentr/goat/testutil"
)
type testEnvInitializerImpl struct{}
type myTestConfig struct {
*YourProjectConfig
}
func (c *myTestConfig) NewExecutor(env *gtt.Env, mockAddress string) *gtt.Executor {
envVars := c.loadEnvVars()
c.configureDB(envVars, env)
return gtt.NewExecutorBuilder(c.BinaryPath()).
WithEnv(envVars).
Build()
}
func (c *myTestConfig) loadEnvVars() map[string]string {
envVars, _ := testutil.LoadEnvFile("tests/etc/onlineconf/onlineconf.env")
envVars["ONLINECONFIG_FROM_ENV"] = "true"
return envVars
}
func (c *myTestConfig) configureDB(envVars map[string]string, env *gtt.Env) {
pg := services.MustGetTyped[*psql.Env](env.Manager(), "postgres")
svc := c.ServiceName()
envVars[fmt.Sprintf("OC_%s__db__main", svc)] = fmt.Sprintf("%s:%s", pg.DBHost, pg.DBPort)
envVars[fmt.Sprintf("OC_%s__db__main__User", svc)] = pg.DBUser
envVars[fmt.Sprintf("OC_%s__db__main__Password", svc)] = pg.DBPass
envVars[fmt.Sprintf("OC_%s__db__main__DB", svc)] = pg.DBName
}
func (c *myTestConfig) ApplyMigrations(ctx context.Context, db *sql.DB) error {
migrationsPath, _ := filepath.Abs(filepath.Join("..", "etc/database/postgres"))
migrationFiles := []string{"01_schema.sql"}
for _, file := range migrationFiles {
content, err := os.ReadFile(filepath.Join(migrationsPath, file))
if err != nil {
continue
}
if _, err := db.ExecContext(ctx, string(content)); err != nil {
return fmt.Errorf("apply migration %s: %w", file, err)
}
}
return nil
}
func (c *myTestConfig) CleanupTables(ctx context.Context, db *sql.DB) error {
tables := []string{"users", "sessions"}
for _, table := range tables {
if _, err := db.ExecContext(ctx, fmt.Sprintf("TRUNCATE TABLE %s RESTART IDENTITY CASCADE", table)); err != nil {
return fmt.Errorf("truncate %s: %w", table, err)
}
}
return nil
}
func (t *testEnvInitializerImpl) InitTestEnv() (testutil.TestAppConfig, *gtt.Env) {
config := &myTestConfig{YourProjectConfig: NewYourProjectConfig()}
services.MustRegisterServiceFuncTyped("postgres", psql.Run)
servicesMap := services.NewServicesMap("postgres")
manager := services.NewManager(servicesMap, services.DefaultManagerConfig())
env := gtt.NewEnv(gtt.EnvConfig{}, manager)
return config, env
}
var _ = SetTestEnvInitializer(&testEnvInitializerImpl{})
Написание тестов¶
Структура test suite¶
package tests
import (
"net/http"
"testing"
"github.com/stretchr/testify/suite"
)
type MyFeatureTestSuite struct {
BaseTestSuite
}
func (s *MyFeatureTestSuite) TestMyFeature() {
// 1. Подготовка данных
// 2. Выполнение запроса
resp, body := s.client.Get(s.T(), "/my/endpoint")
// 3. Проверка результата
s.Require().Equal(http.StatusOK, resp.StatusCode)
}
func TestMyFeatureTestSuite(t *testing.T) {
suite.Run(t, new(MyFeatureTestSuite))
}
HTTP клиент¶
// GET запрос
resp, body := s.client.Get(s.T(), "/endpoint")
// POST запрос
reqBody := map[string]interface{}{"field": "value"}
resp, body := s.client.Post(s.T(), "/endpoint", reqBody)
// С авторизацией
s.client.WithAuth(token)
resp, body := s.client.Get(s.T(), "/protected")
Методы BaseTestSuite¶
| Метод | Описание |
|---|---|
s.ctx |
Context для операций |
s.env |
GOAT Environment |
s.client |
HTTP клиент |
s.Mocks() |
Mock-серверы |
Mock-серверы для внешних API¶
Если приложение использует ogen_client:
package tests
import (
"context"
"net/http"
externalapi "github.com/your-org/your-project/pkg/rest/external/v1"
externalmock "github.com/your-org/your-project/pkg/mocks/external"
"go.uber.org/mock/gomock"
)
type MockServers struct {
ExternalHandler *externalmock.MockHandler
}
func HTTPMocksSetup(mocks *MockServers) func(server *http.ServeMux, ctl *gomock.Controller) {
return func(server *http.ServeMux, ctl *gomock.Controller) {
mocks.ExternalHandler = externalmock.NewMockHandler(ctl)
externalServer, _ := externalapi.NewServer(mocks.ExternalHandler, nil)
server.Handle("/external/", externalServer)
}
}
Использование в тестах¶
func (s *MyTestSuite) TestExternalAPICall() {
s.Mocks().ExternalHandler.EXPECT().
GetData(gomock.Any()).
Return(&externalapi.DataResponse{Status: "success"}, nil).
Times(1)
resp, body := s.client.Get(s.T(), "/my-endpoint")
s.Require().Equal(http.StatusOK, resp.StatusCode)
}
Запуск тестов¶
Через Makefile¶
make goat-tests # Сборка и запуск
make goat-tests-verbose # С подробным выводом
make build_for_test-api # Только сборка бинарника
Важно: при
goat_tests: trueхотя бы у одного приложения цельmake testначинает зависеть отmake goat-tests. Если в текущем окружении не настроена инфраструктура для goat-тестов (например, нет Docker), используйтеmake unit-testsдля запуска только unit-тестов без интеграции.
Напрямую¶
# Сборка бинарника
CGO_ENABLED=1 go build -cover -race -o /tmp/api ./cmd/api
# Запуск тестов
go test -v ./tests/...
# Конкретный suite
go test -v -run TestAuthTestSuite ./tests/...
# Конкретный тест
go test -v -run TestAuthTestSuite/TestLogin ./tests/...
Структура файлов¶
your-project/
├── cmd/api/
│ └── main.go
├── tests/
│ ├── psg_*.go # [generated]
│ ├── init.go # [manual] Ваша реализация
│ ├── factories.go # [manual] Фабрики данных
│ ├── fixtures.go # [manual] Константы
│ ├── assertions.go # [manual] Assertion helpers
│ ├── auth_test.go # [manual] Ваши тесты
│ └── etc/onlineconf/ # Тестовая конфигурация
└── etc/database/postgres/ # SQL миграции
Best Practices¶
- Используйте фабрики для создания тестовых данных
- Используйте fixtures для констант
- Наследуйте BaseTestSuite
- Очищайте данные между тестами (CleanupTables)
- Понятные имена тестов:
TestFeature_WhenCondition_ExpectedResult
Troubleshooting¶
"API did not become ready"¶
- Проверьте бинарник:
ls -la /tmp/api - Docker запущен
- Порты не заняты
- Логи:
tail -f /tmp/yourproject-test-*.log
"TestEnvInitializer not implemented"¶
- Создайте
tests/init.go - Реализуйте интерфейс
- Зарегистрируйте реализацию:
var _ = SetTestEnvInitializer(&testEnvInitializerImpl{})