Files
TREK/server/tests/integration/api-docs.test.ts
T
Maurice b11d8d492c test(db): run the session revocation, api docs, app config and help suites on the real database module
They boot the app without the SQLite snapshot mock, so they run in the
Postgres lane as well. sessionRowsOf reads a user's session rows through
a booted app's ORM, next to sessionRows for the suites that still hand in
a better-sqlite3 handle.
2026-11-17 15:50:49 +01:00

102 lines
4.4 KiB
TypeScript

/**
* API-DOCS (#1412) — the flag-gated Swagger surface: /api/docs (UI),
* /api/docs-json (raw OpenAPI 3 spec incl. the Zod-derived request bodies),
* off-by-default behaviour, and the CSP staying intact on the docs routes.
* Boots the real buildApp() like bootstrap.test.ts.
*/
import { buildApp } from '../../src/bootstrap';
import { apiDocsEnabled } from '../../src/nest/common/api-docs.kill-switch';
import { resetDatabase } from '../helpers/reset-database';
import { MikroORM } from '@mikro-orm/core';
import type { INestApplication } from '@nestjs/common';
import request from 'supertest';
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
describe('API-DOCS (#1412) — flag-gated OpenAPI surface', () => {
let app: INestApplication;
let instance: import('express').Application;
let prevFlag: string | undefined;
beforeAll(async () => {
prevFlag = process.env.TREK_API_DOCS_ENABLED;
process.env.TREK_API_DOCS_ENABLED = 'true';
app = await buildApp();
instance = app.getHttpAdapter().getInstance();
await resetDatabase(app.get(MikroORM));
});
afterAll(async () => {
if (prevFlag === undefined) delete process.env.TREK_API_DOCS_ENABLED;
else process.env.TREK_API_DOCS_ENABLED = prevFlag;
await app.close();
});
it('DOCS-001 — the kill switch parses the boolean-like env family', () => {
const prev = process.env.TREK_API_DOCS_ENABLED;
try {
process.env.TREK_API_DOCS_ENABLED = 'true';
expect(apiDocsEnabled()).toBe(true);
process.env.TREK_API_DOCS_ENABLED = ' TRUE ';
expect(apiDocsEnabled()).toBe(true);
process.env.TREK_API_DOCS_ENABLED = 'false';
expect(apiDocsEnabled()).toBe(false);
// '1' counts as truthy since the unified boolean coercion (app-config).
process.env.TREK_API_DOCS_ENABLED = '1';
expect(apiDocsEnabled()).toBe(true);
delete process.env.TREK_API_DOCS_ENABLED;
expect(apiDocsEnabled()).toBe(false);
} finally {
if (prev === undefined) delete process.env.TREK_API_DOCS_ENABLED;
else process.env.TREK_API_DOCS_ENABLED = prev;
}
});
it('DOCS-002 — /api/docs serves the Swagger UI with the CSP intact', async () => {
const res = await request(instance).get('/api/docs').redirects(1);
expect(res.status).toBe(200);
expect(res.headers['content-type']).toContain('text/html');
expect(res.headers['content-security-policy']).toBeDefined();
});
it('DOCS-003 — /api/docs-json is a full OpenAPI 3 document over all controllers', async () => {
const res = await request(instance).get('/api/docs-json');
expect(res.status).toBe(200);
expect(res.body.openapi).toMatch(/^3\./);
// Reflection survived every controller: a few far-apart domains are present.
expect(res.body.paths['/api/trips']).toBeDefined();
expect(res.body.paths['/api/admin/addons/{id}']).toBeDefined();
expect(res.body.components.securitySchemes.session).toBeDefined();
});
it('DOCS-004 — Zod request bodies are lifted into the spec (no double annotation)', async () => {
const res = await request(instance).get('/api/docs-json');
// collections create validates with CollectionCreateDto (createZodDto over
// collectionCreateRequestSchema) via the global ZodValidationPipe — the DTO
// metatype must surface as a $ref to a component object schema.
const create = res.body.paths['/api/addons/collections']?.post;
expect(create).toBeDefined();
const ref = create.requestBody?.content?.['application/json']?.schema?.$ref as string | undefined;
expect(ref).toMatch(/^#\/components\/schemas\//);
const schema = res.body.components.schemas[ref!.split('/').pop()!];
expect(schema?.type).toBe('object');
expect(schema?.properties?.name).toBeDefined();
});
it('DOCS-005 — without the flag the docs routes do not exist', async () => {
const prev = process.env.TREK_API_DOCS_ENABLED;
delete process.env.TREK_API_DOCS_ENABLED;
let offApp: INestApplication | undefined;
try {
offApp = await buildApp();
const off = offApp.getHttpAdapter().getInstance();
expect((await request(off).get('/api/docs')).status).toBe(404);
expect((await request(off).get('/api/docs-json')).status).toBe(404);
} finally {
if (offApp) await offApp.close();
if (prev === undefined) delete process.env.TREK_API_DOCS_ENABLED;
else process.env.TREK_API_DOCS_ENABLED = prev;
}
});
});