DEMO docs

docs/50-developing/20-database.md

@@ -0,0 +1,110 @@
+# Тестирование с использованием реального бэкенда
+
+Поднимается полноценнный nest сервер, затем для каждого теста БД сбрасывается и восстанавливается из
+снапшота (`/test-data/db/`)
+
+### CI/CD
+
+Для каждого прогона
+
+-   создаётся база тестовая данных
+-   запускаются тесты с бэком
+-   тестовая база удаляется
+
+Для CI/CD отдельных настроек не требуется
+
+### Настройка
+
+Настройки для тестов хранятся в файле `.env.test`. Пример файла:
+
+```env
+DB_USERNAME=test_user
+DB_PASSWORD=secret
+DB_DATABASE=test_db
+```
+
+Все недостающие значения будут взяты из `.env`.
+
+### Локальный запуск
+
+При запуске тестов можно использовать команды
+
+-   `yarn test:db` запустит только тесты с БД
+-   `yarn test` запустит все тесты в проекте
+
+### Написание тестов
+
+Тесты должны иметь расширение `.db-spec.ts`.
+
+Для создания и запуска бэка используется утилита `createTestingBackend()`. В возвращаемом ей
+интерфейсе есть:
+
+-   метод `resetState()` - нужно запускать перед каждым тестом
+-   метод `destroy()` - вызывать в конце группы тестов
+-   поле `http` - результат вызова `INestApplication.getHttpServer()`.
+
+Также есть утилита `authenticate`, которую можно использовать для входа.
+
+Пример управления состоянием:
+
+```ts
+let app: ITestingBackend;
+
+beforeAll(async () => {
+    app = await createTestingBackend();
+});
+
+afterAll(async () => {
+    await app.destroy();
+});
+
+beforeEach(async () => {
+    await app.resetState();
+});
+```
+
+Пример теста:
+
+```ts
+it('при создании AppForm имеет статус draft и не удалена', async () => {
+    const api = supertest(app.http);
+
+    const response = await api
+        .post('/v1/contests/1/forms')
+        .set('Cookie', await authenticate(api, 'admin'))
+        .send(exampleValidForm)
+        .expect(201);
+
+    expect(response.body).toMatchObject({
+        draft: true,
+        deleted: false,
+    });
+});
+```
+
+### Тестирование изолированной части бэкенда
+
+Для unit-тестов определённой части бэкенда можно использовать утилиту `createTestingHarness(app)`.
+
+Пример:
+
+```ts
+const module = await Test.createTestingModule({
+    providers: [UsersDal, TimeService, createMockConfigProvider(authConfigToken)],
+    imports: [
+        TypeOrmModule.forRoot({
+            ...testOrmCredentials,
+            entities: [User, Contest, AuthToken],
+            synchronize: false,
+            logging: false,
+        }),
+        TypeOrmModule.forFeature([User]),
+    ],
+}).compile();
+
+app = module.createNestApplication();
+await app.init();
+
+const harness = await createTestingHarness(app);
+harness.resetState(); // имеет тот же интерфейс, что createTestingBackend
+```