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:
1 parent
157d79932a
commit
bd6f349dc4
21 files changed
+1992
-11
No files matched your search
@@ -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`.
|
||||
Reference in new issue
Block a user