feat: добавить Image Gateway с кешем Souin
- добавлена сборка Caddy с Souin, Otter и NutsDB - добавлена конфигурация dev, prod и test Docker Compose - настроено кеширование через Otter L1 и NutsDB L2 - добавлены e2e-тесты Bun для кеша, restart и purge - добавлена документация по запуску, API кеша и тестам
This commit is contained in:
143
docs/e2e-tests.md
Normal file
143
docs/e2e-tests.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# E2E тесты
|
||||
|
||||
Автоматические e2e-тесты проверяют реальную связку `Caddy + Souin + Otter + NutsDB + imgproxy` через Docker Compose.
|
||||
|
||||
## Запуск Локально
|
||||
|
||||
```bash
|
||||
./scripts/test-e2e.sh
|
||||
```
|
||||
|
||||
На хосте нужны только Docker и Docker Compose. Bun устанавливать не нужно: тесты запускаются внутри контейнера `oven/bun:1`.
|
||||
|
||||
Тестовый стек не публикует порты на хост, поэтому он не конфликтует с dev-стеком на `8888` и `2019`.
|
||||
|
||||
## Что Проверяется
|
||||
|
||||
- Caddy собирается с Souin, Otter и NutsDB storage modules.
|
||||
- Souin не падает обратно на default in-memory storage.
|
||||
- Первый запрос дает `Cache-Status: Souin; fwd=uri-miss; stored`.
|
||||
- Повторный запрос отдается из L1 in-memory кеша: `detail=OTTER`.
|
||||
- После `docker compose restart caddy` кеш сохраняется и читается из L2 disk storage: `detail=NUTS`.
|
||||
- `PURGE /souin-api/souin/flush` возвращает `204`.
|
||||
- После purge новые записи в кеш продолжают работать.
|
||||
- В логах Caddy нет `NUTS-INSERTION-ERROR`.
|
||||
|
||||
## Почему Не Используется Внешний Источник
|
||||
|
||||
Тесты не ходят в `picsum.photos` или другие внешние сервисы. Вместо этого отдельный `fixture`-сервис внутри Docker network отдает статичную PNG-картинку.
|
||||
|
||||
Это делает тесты стабильными:
|
||||
|
||||
- нет зависимости от интернета;
|
||||
- нет случайной смены изображения или `ETag`;
|
||||
- нет внешних rate limits;
|
||||
- одинаковое поведение локально и в CI.
|
||||
|
||||
## Состав Тестового Стека
|
||||
|
||||
Файл: `docker-compose.test.yml`.
|
||||
|
||||
Сервисы:
|
||||
|
||||
| Сервис | Назначение |
|
||||
|---|---|
|
||||
| `fixture` | HTTP-сервис со статичной картинкой `/image.png` |
|
||||
| `imgproxy` | Обрабатывает изображение из `fixture` |
|
||||
| `caddy` | Gateway с Souin cache, Otter L1 и NutsDB L2 |
|
||||
| `tester` | Контейнер `oven/bun:1`, запускает `bun test` |
|
||||
|
||||
Тесты обращаются к сервисам по внутренним Docker DNS именам:
|
||||
|
||||
```text
|
||||
http://caddy:8888
|
||||
http://caddy:2019
|
||||
http://fixture:8080/image.png
|
||||
```
|
||||
|
||||
## Структура Файлов
|
||||
|
||||
```text
|
||||
scripts/test-e2e.sh Entry point для локального запуска и CI
|
||||
docker-compose.test.yml Изолированный Docker Compose стек для тестов
|
||||
tests/fixture/server.js Fixture HTTP server на Bun
|
||||
tests/e2e/helpers.js Общие HTTP helpers и assertions
|
||||
tests/e2e/cache-prime.test.js MISS -> stored, HIT -> OTTER
|
||||
tests/e2e/cache-persistence.test.js restart caddy -> HIT -> NUTS
|
||||
tests/e2e/cache-purge.test.js flush -> новые записи продолжают работать
|
||||
```
|
||||
|
||||
## Как Работает Скрипт
|
||||
|
||||
`scripts/test-e2e.sh` выполняет полный lifecycle:
|
||||
|
||||
```bash
|
||||
docker compose -p <project> -f docker-compose.test.yml down -v --remove-orphans
|
||||
docker compose -p <project> -f docker-compose.test.yml up -d --build caddy imgproxy fixture
|
||||
docker compose -p <project> -f docker-compose.test.yml run --rm tester bun test tests/e2e/cache-prime.test.js
|
||||
docker compose -p <project> -f docker-compose.test.yml restart caddy
|
||||
docker compose -p <project> -f docker-compose.test.yml run --rm tester bun test tests/e2e/cache-persistence.test.js
|
||||
docker compose -p <project> -f docker-compose.test.yml run --rm tester bun test tests/e2e/cache-purge.test.js
|
||||
docker compose -p <project> -f docker-compose.test.yml down -v --remove-orphans
|
||||
```
|
||||
|
||||
При ошибке скрипт печатает логи compose-стека и затем удаляет контейнеры и volumes.
|
||||
|
||||
## Compose Project Name
|
||||
|
||||
По умолчанию используется project name:
|
||||
|
||||
```text
|
||||
image-gateway-test-local
|
||||
```
|
||||
|
||||
В CI скрипт автоматически учитывает `CI_JOB_ID` или `GITHUB_RUN_ID`, если они есть.
|
||||
|
||||
Можно задать имя явно:
|
||||
|
||||
```bash
|
||||
COMPOSE_PROJECT_NAME=image-gateway-test ./scripts/test-e2e.sh
|
||||
```
|
||||
|
||||
Это полезно для параллельных запусков или отладки нескольких test stack одновременно.
|
||||
|
||||
## Подключение В CI
|
||||
|
||||
CI job должен запускать тот же entrypoint:
|
||||
|
||||
```bash
|
||||
./scripts/test-e2e.sh
|
||||
```
|
||||
|
||||
Требования к runner:
|
||||
|
||||
- Docker;
|
||||
- Docker Compose plugin;
|
||||
- доступ к Docker daemon;
|
||||
- возможность собирать Docker images.
|
||||
|
||||
Bun, Node.js и npm на runner не нужны.
|
||||
|
||||
## Отладка
|
||||
|
||||
Если тест упал, сначала смотрите вывод `scripts/test-e2e.sh`: он печатает логи всех сервисов перед cleanup.
|
||||
|
||||
Для ручной отладки можно поднять стек без скрипта:
|
||||
|
||||
```bash
|
||||
docker compose -p image-gateway-debug -f docker-compose.test.yml up -d --build caddy imgproxy fixture
|
||||
docker compose -p image-gateway-debug -f docker-compose.test.yml run --rm tester bun test tests/e2e/cache-prime.test.js
|
||||
docker compose -p image-gateway-debug -f docker-compose.test.yml logs caddy
|
||||
docker compose -p image-gateway-debug -f docker-compose.test.yml down -v --remove-orphans
|
||||
```
|
||||
|
||||
## Когда Расширять Набор
|
||||
|
||||
Текущий набор покрывает критичные регрессии кеша. Следующие полезные сценарии:
|
||||
|
||||
- purge по regex;
|
||||
- разные resize-параметры создают разные cache keys;
|
||||
- разные source URL не конфликтуют;
|
||||
- невалидный upstream не кешируется;
|
||||
- `docker compose down` без `-v` сохраняет volume;
|
||||
- `docker compose down -v` удаляет кеш.
|
||||
Reference in New Issue
Block a user