api: логирование через pino

Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни
trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в
проде,
автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для
тестов —
LocalLoggerModule.forTesting() со своим TestingLogger и матчерами.

Документация по логированию — в docs/55-logging.
This commit is contained in:
arswarog committed 2026-10-27 10:44:15 +03:00
1 parent 157d79932a
commit bd6f349dc4
21 files changed
+1992 -11

No files matched your search

+159
View File
@@ -0,0 +1,159 @@
# Тестирование логирования
## Подключение
Для тестов следует подключать специальный модуль — **`LocalLoggerModule.forTesting()`**. Он
сохраняет логи в памяти и предоставляет к ним доступ через `TestingLogger`.
Это позволяет:
- перехватывать все вызовы логгера внутри тестируемого кода;
- сохранять их в память вместо вывода в консоль;
- проверять, какие именно логи были собраны за время теста.
Пример подключения через NestJS `TestingModule`:
```ts
let logger: TestingLogger;
beforeEach(async () => {
const module = await Test.createTestingModule({
imports: [LocalLoggerModule.forTesting()],
}).compile();
logger = module.get(TestingLogger);
});
```
После такого подключения любые вызовы вида:
```ts
this.logger.log('Brand created');
this.logger.error('Brand update failed');
```
будут сохранены внутри `TestingLogger`, и вы сможете проверить их в тестах при помощи матчеров:
```ts
logger.withMessage('Brand created').withLevel('info').toBeLoggedOnce();
logger.withMessage('Brand update failed').withLevel('error').toBeLogged();
```
## Цепочка фильтров
Методы фильтрации (`withMessage`, `withLevel`, `withContext`, `withDetails`) можно вызывать
цепочкой, для более точного сопоставления логов:
```ts
logger
.withMessage('Brand created')
.withLevel('info')
.withContext('Brands')
.withDetails({ user: 5 })
.toBeLoggedOnce();
```
Метод `withDetails` поддерживает частичное сравнение объекта, а также может проверять поля `level`,
`context` и `message`:
```ts
logger
.withMessage('Brand created')
.withDetails({
level: 'info',
context: 'Brands',
user: 5,
})
.toBeLoggedOnce();
```
Если нужны только поля из фильтра и ничего лишнего в `details`, к цепочке добавляется
`strictDetails()`.
### Просмотр найденных записей
Если нужно отладить фильтр и просмотреть, какие записи были найдены по текущему фильтру, можно
использовать метод `showLogs()`:
```ts
logger.withLevel('error').showLogs().toBeLogged();
```
### Методы проверки
| Метод | Описание |
| -------------------- | --------------------------------------------------------- |
| `toBeLogged()` | Проверяет, что хотя бы одна запись соответствует фильтру. |
| `toBeNotLogged()` | Проверяет, что таких записей нет. |
| `toBeLoggedOnce()` | Проверяет, что запись встречается ровно один раз. |
| `toBeLoggedTimes(n)` | Проверяет, что запись встречается `n` раз. |
Все методы выбрасывают ошибку, если условие не выполняется.
> **Важно:** Методы проверки **обязательно** должны вызываться, иначе проверки так и не будет.
### Группирование проверок
Если в тесте нужно проверить несколько событий с общим набором полей, можно использовать такой
приём:
```ts
const brandsLogger = logger.withContext('Brands');
brandsLogger.withMessage('Brand created').toBeLoggedTimes(2);
brandsLogger.withMessage('Brand update failed').toBeLoggedOnce();
```
Это удобно для группировки проверок по контексту или другим общим параметрам.
## Примеры использования
### Проверка бизнес-события
```ts
it('должен логировать создание бренда', () => {
service.createBrand({ user: 7 });
logger.withMessage('Brand created').withLevel('info').withDetails({ user: 7 }).toBeLoggedOnce();
});
```
### Проверка ошибок
```ts
it('должен логировать ошибку при невалидном статусе', () => {
service.updateBrandStatus(42, 'invalid');
logger.withMessage('Brand update failed').withLevel('error').toBeLogged();
});
```
### Проверка отсутствия логов
```ts
it('не должен логировать ничего при успешном выполнении без событий', () => {
service.doNothing();
logger.any().toBeNotLogged();
});
```
### Очистка
```ts
beforeEach(() => {
logger.clear();
});
```
Используйте `clear()` для сброса состояния между тестами, если экземпляр `TestingLogger`
переиспользуется в нескольких сценариях.
## Рекомендации
- `TestingLogger` предназначен **только для тестов** — в рабочем коде используется обычный `Logger`.
- Проверяйте **факт логирования**, а не реализацию — тесты должны оставаться устойчивыми к
внутренним изменениям.
- Используйте `toBeNotLogged()` для сценариев, где событие **не должно** быть зафиксировано.
- Готовый пример работы с `TestingLogger` — `apps/api/src/logger/testing/testing-logger.spec.ts`.