13. Testing, logging y observabilidad en NestJS

{
  "jsc": {
    "target": "es2022",
    "parser": { "syntax": "typescript", "decorators": true },
    "transform": { "legacyDecorator": true, "decoratorMetadata": true },
    "keepClassNames": true
  },
  "module": { "type": "commonjs" }
}
// Y en jest.config.ts:  transform: { '^.+\\.ts$': '@swc/jest' }

import { EntityManager, EntityRepository } from '@mikro-orm/postgresql';
/** Convierte cada método de T en un jest.Mock, conservando el resto. */
export type Mocked<T> = { [K in keyof T]: T[K] extends (...a: never[]) => unknown ? jest.Mock : T[K] };
type Metodos = 'find' | 'findOne' | 'findOneOrFail' | 'findAndCount' | 'count' | 'create'
  | 'assign' | 'persist' | 'remove' | 'persistAndFlush' | 'removeAndFlush' | 'flush'
  | 'nativeDelete' | 'getReference' | 'transactional' | 'fork' | 'clear';
export type MockEm = Mocked<Pick<EntityManager, Metodos>>;
export function createMockEntityManager(): MockEm {
  const em = {
    find: jest.fn().mockResolvedValue([]),
    findOne: jest.fn().mockResolvedValue(null),
    findOneOrFail: jest.fn(),
    findAndCount: jest.fn().mockResolvedValue([[], 0]),
    count: jest.fn().mockResolvedValue(0),
    create: jest.fn((_e: unknown, data: object) => ({ ...data })),   // no toca la BD
    assign: jest.fn((e: object, data: object) => Object.assign(e, data)),
    flush: jest.fn().mockResolvedValue(undefined),
    persistAndFlush: jest.fn().mockResolvedValue(undefined),
    removeAndFlush: jest.fn().mockResolvedValue(undefined),
    nativeDelete: jest.fn().mockResolvedValue(1),
    getReference: jest.fn((_e: unknown, id: unknown) => ({ id })),
    clear: jest.fn(),
  } as unknown as MockEm;
  em.persist = jest.fn(() => em);   // fluent: em.persist(a).persist(b)
  em.remove  = jest.fn(() => em);
  em.fork    = jest.fn(() => em);   // en un unitario basta con devolverse a sí mismo
  // CLAVE: el callback transaccional TIENE que ejecutarse.
  em.transactional = jest.fn(async (cb: (em: MockEm) => unknown) => cb(em));
  return em;
}
/** Doble de repositorio: los mismos lectores, más el EM accesible desde él. */
export const createMockRepository = <T extends object>(em = createMockEntityManager()) => ({
  find: em.find, findOne: em.findOne, findOneOrFail: em.findOneOrFail,
  findAndCount: em.findAndCount, count: em.count, create: em.create,
  findAll: jest.fn().mockResolvedValue([]),
  getEntityManager: jest.fn(() => em),      // repo.getEntityManager().flush()
}) as unknown as Mocked<EntityRepository<T>>;
// En el módulo de test, con el token que registra @mikro-orm/nestjs:
//   { provide: getRepositoryToken(Task), useValue: createMockRepository<Task>(em) }
//   { provide: EntityManager, useValue: em }

@Injectable()
export class ProjectsService {
  constructor(
    private readonly em: EntityManager,
    private readonly notifications: NotificationsService,
    private readonly clock: Clock,          // inyectado: nunca new Date() directo
  ) {}
  /**
   * Reglas: 1) debe existir; 2) solo el propietario cierra; 3) no puede quedar
   * ninguna tarea sin terminar ni cancelar; 4) no se cierra dos veces;
   * 5) se registra la fecha y se notifica a los miembros.
   */
  async close(projectId: string, userId: string): Promise<Project> {
    const project = await this.em.transactional(async (em) => {
      const found = await em.findOne(Project, { id: projectId }, { populate: ['tasks'] });
      if (!found) throw new NotFoundException(`Proyecto ${projectId} no encontrado`);
      if (found.owner.id !== userId) {
        throw new ForbiddenException('Solo el propietario puede cerrar el proyecto');
      }
      if (found.status === ProjectStatus.Closed) {
        throw new BadRequestException('El proyecto ya está cerrado');
      }
      const pendientes = found.tasks.getItems()
        .filter((t) => t.status !== TaskStatus.Done && t.status !== TaskStatus.Cancelled);
      if (pendientes.length > 0) {
        throw new BadRequestException(`Quedan ${pendientes.length} tareas sin cerrar: `
          + pendientes.map((t) => t.title).join(', '));
      }
      found.status = ProjectStatus.Closed;
      found.closedAt = this.clock.now();
      await em.flush();
      return found;
    });
    // Fuera de la transacción a propósito: un fallo del correo
    // no debe deshacer el cierre del proyecto.
    await this.notifications.projectClosed(project);
    return project;
  }
}

const AHORA = new Date('2026-03-15T10:00:00.000Z');
// Fábricas locales con valores por defecto: cada test declara SOLO lo que le
// importa, y ese delta documenta el caso (ver 13.12).
const unProyecto = (over: Partial<Project> = {}) => ({
  id: 'p-1', name: 'Migración a Nest', status: ProjectStatus.Active, closedAt: null,
  owner: { id: 'u-1' }, tasks: { getItems: () => [] }, ...over,
}) as unknown as Project;
const conTareas = (...estados: TaskStatus[]) => ({
  getItems: () => estados.map((status, i) => ({ id: `t-${i}`, title: `Tarea ${i}`, status })),
}) as never;
describe('ProjectsService.close', () => {
  let service: ProjectsService;
  let em: MockEm;
  let notifications: { projectClosed: jest.Mock };

  beforeEach(async () => {
    em = createMockEntityManager();
    notifications = { projectClosed: jest.fn().mockResolvedValue(undefined) };
    const module = await Test.createTestingModule({
      providers: [ProjectsService,
        { provide: EntityManager, useValue: em },
        { provide: NotificationsService, useValue: notifications },
        { provide: Clock, useValue: { now: () => AHORA } },   // reloj fijo
      ],
    }).compile();
    service = module.get(ProjectsService);
  });

  afterEach(() => jest.clearAllMocks());

  it('cierra un proyecto sin pendientes, fija la fecha y notifica', async () => {
    const project = unProyecto({ tasks: conTareas(TaskStatus.Done, TaskStatus.Cancelled) });
    em.findOne.mockResolvedValue(project);
    const result = await service.close('p-1', 'u-1');
    expect(result.status).toBe(ProjectStatus.Closed);
    expect(result.closedAt).toEqual(AHORA);
    expect(em.flush).toHaveBeenCalled();
    expect(notifications.projectClosed).toHaveBeenCalledWith(project);
    // Propiedad estructural: la escritura ocurre dentro de la transacción.
    expect(em.transactional).toHaveBeenCalledTimes(1);
  });

  it('caso límite: un proyecto sin ninguna tarea se puede cerrar', async () => {
    em.findOne.mockResolvedValue(unProyecto({ tasks: conTareas() }));
    await expect(service.close('p-1', 'u-1'))
      .resolves.toMatchObject({ status: ProjectStatus.Closed });
  });

  it('lanza NotFoundException y no escribe ni notifica', async () => {
    em.findOne.mockResolvedValue(null);
    // Tipo Y mensaje: el tipo fija el status HTTP, el mensaje es contrato.
    await expect(service.close('p-404', 'u-1')).rejects.toThrow(NotFoundException);
    await expect(service.close('p-404', 'u-1')).rejects.toThrow('Proyecto p-404 no encontrado');
    expect(em.flush).not.toHaveBeenCalled();
    expect(notifications.projectClosed).not.toHaveBeenCalled();
  });

  it('lanza ForbiddenException si quien cierra no es el propietario', async () => {
    em.findOne.mockResolvedValue(unProyecto());
    await expect(service.close('p-1', 'u-2')).rejects.toBeInstanceOf(ForbiddenException);
    expect(em.flush).not.toHaveBeenCalled();
  });

  it('enumera las tareas pendientes, y no permite cerrar dos veces', async () => {
    em.findOne.mockResolvedValue(unProyecto({
      tasks: conTareas(TaskStatus.Done, TaskStatus.InProgress, TaskStatus.Todo) }));
    await expect(service.close('p-1', 'u-1'))
      .rejects.toThrow(/Quedan 2 tareas sin cerrar: Tarea 1, Tarea 2/);
    em.findOne.mockResolvedValue(unProyecto({ status: ProjectStatus.Closed }));
    await expect(service.close('p-1', 'u-1')).rejects.toThrow(BadRequestException);
  });

  it('si falla la notificación, el cierre YA está persistido', async () => {
    em.findOne.mockResolvedValue(unProyecto({ tasks: conTareas(TaskStatus.Done) }));
    notifications.projectClosed.mockRejectedValue(new Error('SMTP caído'));
    // Documentar la decisión: el error se propaga pero el proyecto queda cerrado.
    await expect(service.close('p-1', 'u-1')).rejects.toThrow('SMTP caído');
    expect(em.flush).toHaveBeenCalled();
  });
});

/** ExecutionContext falso: solo lo que consumen tus enhancers. */
export function mockExecutionContext(opts: {
  user?: unknown; params?: object; query?: object; body?: unknown;
  headers?: Record<string, string>; method?: string; url?: string;
  handler?: () => void; controller?: Function;
} = {}) {
  const req = {
    user: opts.user, params: opts.params ?? {}, query: opts.query ?? {},
    body: opts.body, headers: opts.headers ?? {},
    method: opts.method ?? 'GET', url: opts.url ?? '/', route: { path: opts.url ?? '/' },
  };
  const res = { statusCode: 200, setHeader: jest.fn(), status: jest.fn().mockReturnThis(),
                json: jest.fn().mockReturnThis() };
  return {
    switchToHttp: () => ({ getRequest: () => req, getResponse: () => res, getNext: () => jest.fn() }),
    // getHandler y getClass son lo que lee el Reflector para los decoradores.
    getHandler: () => opts.handler ?? function handler() {},
    getClass: () => opts.controller ?? class TestController {},
    getType: () => 'http', getArgs: () => [req, res], getArgByIndex: (i: number) => [req, res][i],
    switchToRpc: jest.fn(), switchToWs: jest.fn(),
  } as unknown as ExecutionContext & { __req: typeof req; __res: typeof res };
}
/** CallHandler falso: controla lo que "devuelve el controlador". */
export const mockCallHandler = (value: unknown = { ok: true }): CallHandler =>
  ({ handle: jest.fn(() => of(value)) });
export const failingCallHandler = (error: Error): CallHandler =>
  ({ handle: jest.fn(() => throwError(() => error)) });

describe('RolesGuard', () => {
  let guard: RolesGuard;
  let reflector: { getAllAndOverride: jest.Mock };

  beforeEach(() => {
    // El Reflector es la única dependencia: mockearlo es trivial y hace
    // explícito qué metadatos espera el guard.
    reflector = { getAllAndOverride: jest.fn() };
    guard = new RolesGuard(reflector as unknown as Reflector);
  });

  it('permite el paso si el endpoint no exige roles', () => {
    reflector.getAllAndOverride.mockReturnValue(undefined);
    expect(guard.canActivate(mockExecutionContext({ user: { roles: [] } }))).toBe(true);
  });

  it('permite el paso si el usuario tiene alguno de los roles exigidos', () => {
    reflector.getAllAndOverride.mockReturnValue([Role.Admin, Role.Manager]);
    const ctx = mockExecutionContext({ user: { id: 'u-1', roles: [Role.Manager] } });
    expect(guard.canActivate(ctx)).toBe(true);
  });

  it.each([
    ['sin ninguno de los roles', { id: 'u-1', roles: [Role.User] }],
    ['sin roles',                { id: 'u-1', roles: [] }],
    ['sin usuario (guard mal ordenado)', undefined],
  ])('deniega el paso con ForbiddenException: %s', (_caso, user) => {
    reflector.getAllAndOverride.mockReturnValue([Role.Admin]);
    // Denegar lanzando (y no devolviendo false) permite dar un mensaje útil.
    expect(() => guard.canActivate(mockExecutionContext({ user })))
      .toThrow(ForbiddenException);
  });

  it('lee los metadatos del handler Y de la clase, en ese orden', () => {
    reflector.getAllAndOverride.mockReturnValue([Role.Admin]);
    const handler = function borrar() {};
    class ProjectsController {}
    guard.canActivate(mockExecutionContext({ user: { roles: [Role.Admin] }, handler,
                                             controller: ProjectsController }));
    // Contrato real: @Roles() a nivel de método debe ganar al de clase.
    expect(reflector.getAllAndOverride).toHaveBeenCalledWith(ROLES_KEY,
      [handler, ProjectsController]);
  });
});

describe('ParseSlugPipe', () => {
  const pipe = new ParseSlugPipe();
  const meta = { type: 'param', data: 'slug' } as ArgumentMetadata;

  it.each([['mi-proyecto', 'mi-proyecto'], ['  Mi Proyecto  ', 'mi-proyecto'],
           ['Año_2026', 'ano-2026']])('normaliza %s', (entrada, esperado) => {
    expect(pipe.transform(entrada, meta)).toBe(esperado);
  });

  it.each(['', '   ', '---', '\u0000', 'a'.repeat(256), '../../etc/passwd'])
    ('rechaza %j con BadRequestException', (entrada) => {
      // Los casos límite de un pipe son su razón de existir: son la frontera
      // entre datos del exterior y tu dominio.
      expect(() => pipe.transform(entrada, meta)).toThrow(BadRequestException);
    });
});

describe('TimeoutInterceptor', () => {
  // Con temporizadores reales el test tardaría lo que el timeout; con
  // temporizadores falsos avanzamos el reloj y tarda microsegundos.
  beforeEach(() => jest.useFakeTimers());

  afterEach(() => jest.useRealTimers());

  it('deja pasar la respuesta si llega a tiempo', async () => {
    const res$ = new TimeoutInterceptor(5000)
      .intercept(mockExecutionContext(), mockCallHandler({ id: 't-1' }));
    await expect(firstValueFrom(res$)).resolves.toEqual({ id: 't-1' });
  });

  it('convierte el timeout en RequestTimeoutException (408, no 500)', async () => {
    const lento: CallHandler = { handle: () => timer(10_000).pipe(map(() => 'tarde')) };
    const promesa = firstValueFrom(
      new TimeoutInterceptor(5000).intercept(mockExecutionContext(), lento));
    jest.advanceTimersByTime(5001);
    await expect(promesa).rejects.toBeInstanceOf(RequestTimeoutException);
  });
});
describe('DomainExceptionFilter', () => {

  it('traduce un error de dominio a una respuesta HTTP estable', () => {
    const ctx = mockExecutionContext({ url: '/projects/p-1/close' });
    const host = { switchToHttp: ctx.switchToHttp } as unknown as ArgumentsHost;
    new DomainExceptionFilter().catch(new TaskAlreadyDoneError('t-1'), host);
    const res = ctx.switchToHttp().getResponse();
    expect(res.status).toHaveBeenCalledWith(409);
    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
      statusCode: 409, code: 'TASK_ALREADY_DONE', path: '/projects/p-1/close',
    }));
    // El contrato de error también es contrato: si tu frontend enrama por
    // "code", cambiarlo rompe clientes igual que cambiar una ruta.
  });
});

describe('TasksController (HTTP aislado)', () => {
  let app: INestApplication;
  const service = { findAll: jest.fn(), create: jest.fn() };
  beforeAll(async () => {
    const mod = await Test.createTestingModule({
      controllers: [TasksController],
      providers: [{ provide: TasksService, useValue: service }],
    })
      // Sin base de datos ni JWT reales, pero con enrutado y validación reales.
      .overrideGuard(JwtAuthGuard).useValue({ canActivate: (c: ExecutionContext) => {
        c.switchToHttp().getRequest().user = { id: 'u-1', roles: [Role.User] };
        return true;
      } })
      .compile();
    app = mod.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
    await app.init();
  });
  afterAll(() => app.close());

  it('convierte y valida la query: page=abc es 400', async () => {
    await request(app.getHttpServer()).get('/tasks?page=abc').expect(400);
    expect(service.findAll).not.toHaveBeenCalled();
  });

  it('aplica los valores por defecto del DTO y transforma tipos', async () => {
    service.findAll.mockResolvedValue({ items: [], total: 0 });
    await request(app.getHttpServer()).get('/tasks?page=2').expect(200);
    // page llega como NUMBER 2, no como string: eso es lo que aporta
    // este test y lo que un unitario con new TasksController() no ve.
    expect(service.findAll).toHaveBeenCalledWith('u-1',
      expect.objectContaining({ page: 2, limit: 20 }));
  });

  it('devuelve 201 y elimina propiedades no declaradas (whitelist)', async () => {
    service.create.mockImplementation((_u, dto) => ({ id: 't-1', ...dto }));
    const { body } = await request(app.getHttpServer()).post('/tasks')
      .send({ title: 'Escribir tests', isAdmin: true }).expect(201);
    expect(body).not.toHaveProperty('isAdmin');
  });
});

// globalSetup arranca UN contenedor para toda la ejecución y exporta la URL;
// cada worker de Jest se conecta a él con su propio ESQUEMA (ver 13.7.3).
export default async function globalSetup() {
  const container = await new PostgreSqlContainer('postgres:16-alpine')
    .withTmpFs({ '/var/lib/postgresql/data': 'rw' })   // datos en RAM: mucho más rápido
    .withCommand(['postgres', '-c', 'fsync=off', '-c', 'full_page_writes=off'])
    .start();
  process.env.TEST_DB_URL = container.getConnectionUri();
  (globalThis as { __PG__?: unknown }).__PG__ = container;   // lo cierra globalTeardown
}
export async function createTestOrm(): Promise<MikroORM> {
  const orm = await MikroORM.init({
    ...config,
    clientUrl: process.env.TEST_DB_URL,
    schema: `w${process.env.JEST_WORKER_ID ?? '1'}`,   // aislamiento por worker
    debug: process.env.SQL_DEBUG === '1' ? ['query', 'query-params'] : false,
    allowGlobalContext: false,   // fuerza em.fork() y detecta EM compartidos
  });
  await orm.schema.createSchema();       // el esquema del worker
  await orm.schema.refreshDatabase();    // drop + create, rápido y determinista
  return orm;
}

describe('TasksRepository (integración)', () => {
  let orm: MikroORM; let em: EntityManager; let repo: TasksRepository;
  let project: Project;
  beforeAll(async () => { orm = await createTestOrm(); });
  afterAll(async () => { await orm.close(true); });

  beforeEach(async () => {
    await truncateAll(orm);
    em = orm.em.fork();
    repo = em.getRepository(Task) as TasksRepository;
    // Datos con factorías (13.12): explícitos y mínimos.
    const owner = em.create(User, userFactory({ email: 'ana@example.com' }));
    project = em.create(Project, projectFactory({ owner, name: 'Migración' }));
    em.create(Task, taskFactory({ project, title: 'Diseñar esquema',
      status: TaskStatus.Done, tags: ['db'], dueDate: new Date('2026-01-10') }));
    em.create(Task, taskFactory({ project, title: 'Escribir tests',
      status: TaskStatus.Todo, tags: ['db', 'qa'], dueDate: new Date('2026-02-20') }));
    em.create(Task, taskFactory({ project, title: 'Revisar PR',
      status: TaskStatus.Todo, tags: [], dueDate: null }));
    await em.flush();
    em.clear();
  });

  it('filtra por estado y etiqueta, ordena y pagina', async () => {
    const [items, total] = await repo.search(
      { projectId: project.id, status: TaskStatus.Todo, tag: 'db' },
      { page: 1, limit: 10, orderBy: 'dueDate', dir: QueryOrder.ASC });
    expect(total).toBe(1);
    expect(items[0].title).toBe('Escribir tests');
  });

  it('ordena por dueDate dejando los NULL al final (contrato explícito)', async () => {
    const [items] = await repo.search({ projectId: project.id },
      { page: 1, limit: 10, orderBy: 'dueDate', dir: QueryOrder.ASC_NULLS_LAST });
    // Sin NULLS LAST, PostgreSQL pone los NULL primero en ASC y SQLite al
    // final: exactamente el tipo de diferencia que solo ve un test real.
    expect(items.map((t) => t.title))
      .toEqual(['Diseñar esquema', 'Escribir tests', 'Revisar PR']);
  });

  it('carga la relación sin N+1: una sola consulta con populate', async () => {
    const consultas: string[] = [];
    // El logger del ORM es la forma fiable de contar consultas.
    orm.config.set('logger', (msg: string) => consultas.push(msg));
    orm.config.set('debug', ['query']);
    const tareas = await em.fork().find(Task, {}, { populate: ['project.owner'] });
    expect(tareas).toHaveLength(3);
    expect(tareas[0].project.owner.email).toBe('ana@example.com');
    // 3 tareas cargadas con 2 consultas (tasks + join de project/owner),
    // no con 1 + 3 + 3. Este test se rompe el día que alguien quita el populate.
    expect(consultas.filter((q) => q.includes('select')).length).toBeLessThanOrEqual(3);
    orm.config.set('debug', false);
  });

  it('respeta la restricción de unicidad (título único por proyecto)', async () => {
    const otro = em.fork();
    otro.create(Task, taskFactory({ project: otro.getReference(Project, project.id),
                                    title: 'Revisar PR' }));
    // UniqueConstraintViolationException, no un Error genérico: el servicio
    // puede capturarla y devolver 409 en lugar de 500.
    await expect(otro.flush()).rejects.toBeInstanceOf(UniqueConstraintViolationException);
  });

  it('borra en cascada las tareas al borrar el proyecto', async () => {
    const em2 = orm.em.fork();
    await em2.removeAndFlush(await em2.findOneOrFail(Project, { id: project.id }));
    await expect(orm.em.fork().count(Task, {})).resolves.toBe(0);
  });
});

import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
// Jest ejecuta globalSetup UNA vez por ejecución, en el proceso padre, antes de
// crear ningún worker. Es el único punto donde "una vez" significa de verdad
// una vez: todo lo que esté en un beforeAll ocurre una vez POR ARCHIVO.
export default async function globalSetup(): Promise<void> {
  let contenedor = new PostgreSqlContainer('postgres:16-alpine')
    .withDatabase('taskflow_test').withUsername('test').withPassword('test')
    // Datos en RAM y durabilidad desactivada: NO queremos que sobrevivan a un
    // corte de luz, queremos que los INSERT vayan rápido. En producción esto
    // sería negligencia; aquí es la optimización que más tiempo ahorra.
    .withTmpFs({ '/var/lib/postgresql/data': 'rw,noexec,nosuid,size=1024m' })
    .withCommand(['postgres', '-c', 'fsync=off', '-c', 'full_page_writes=off',
                  '-c', 'synchronous_commit=off', '-c', 'max_connections=200']);
  // REUTILIZACIÓN: solo en local. Exige testcontainers.reuse.enable=true en
  // ~/.testcontainers.properties. En CI el runner es efímero: reutilizar no
  // ahorra nada y arriesga arrastrar estado de otra rama.
  if (!process.env.CI) contenedor = contenedor.withReuse();
  const iniciado: StartedPostgreSqlContainer = await contenedor.start();
  process.env.TEST_DB_URL = iniciado.getConnectionUri();
  // globalSetup y globalTeardown se ejecutan en el MISMO contexto, así que
  // globalThis es la forma soportada de pasarse el objeto entre ambos.
  (globalThis as Record<string, unknown>).__PG_CONTAINER__ = iniciado;
  // Migraciones una sola vez sobre la plantilla (ver 13.7.5).
  await prepararPlantilla(iniciado.getConnectionUri());
}

export default async function globalTeardown(): Promise<void> {
  const c = (globalThis as Record<string, unknown>).__PG_CONTAINER__ as
    { stop: (o?: object) => Promise<void> } | undefined;
  // Con withReuse() el contenedor NO debe pararse: se deja vivo a propósito
  // para la siguiente ejecución. Ryuk lo recogerá cuando expire.
  if (c && process.env.CI) await c.stop({ timeout: 5000 });
}
// jest.integration.config.ts
//   globalSetup:    '<rootDir>/test/setup/global-setup.ts',
//   globalTeardown: '<rootDir>/test/setup/global-teardown.ts',
//   testRegex: '.*\\.int-spec\\.ts$',
//   maxWorkers: '50%',   // cada worker tendrá su propia base de datos

// Patrón: el test corre DENTRO de una transacción que nunca se confirma.
// Es la estrategia más rápida que existe y la que produce tests más limpios,
// siempre que el código bajo test no gestione sus propias transacciones.
export function useTransactionalEm(getOrm: () => MikroORM) {
  let em: EntityManager;
  beforeEach(async () => {
    em = getOrm().em.fork();
    await em.begin();          // BEGIN explícito sobre la conexión de ESTE fork
  });
  afterEach(async () => {
    // Si el test dejó la transacción marcada como fallida, rollback igualmente.
    if (em.isInTransaction()) await em.rollback();
    em.clear();
  });
  return () => em;
}
// Uso:
describe('TasksService (integración, rollback por test)', () => {
  const em = useTransactionalEm(() => orm);
  it('no deja rastro entre tests', async () => {
    em().create(Task, taskFactory({ title: 'Efímera' }));
    await em().flush();        // INSERT real, dentro de la transacción abierta
    await expect(em().count(Task, {})).resolves.toBe(1);
  });
  it('empieza con la tabla vacía', async () => {
    await expect(em().count(Task, {})).resolves.toBe(0);   // el rollback ya ocurrió
  });
});

// PostgreSQL permite clonar una base de datos entera copiando ficheros:
//   CREATE DATABASE destino TEMPLATE origen;
// Es mucho más rápido que volver a ejecutar el DDL o las migraciones, y da
// aislamiento perfecto: cada worker (o cada test caro) tiene su propia base.
export async function prepararPlantilla(url: string): Promise<void> {
  const orm = await MikroORM.init({ ...config, clientUrl: url });
  await orm.migrator.up();          // las migraciones REALES, una sola vez
  await orm.seeder.seed(DatosDeReferenciaSeeder);   // países, roles, planes...
  await orm.close(true);
}
export async function clonarPlantilla(nombre: string): Promise<string> {
  const admin = new Client({ connectionString: process.env.TEST_DB_URL });
  await admin.connect();
  // La plantilla no puede tener conexiones abiertas mientras se clona: por eso
  // prepararPlantilla() cierra el ORM antes de terminar.
  await admin.query(`DROP DATABASE IF EXISTS "${nombre}"`);
  await admin.query(`CREATE DATABASE "${nombre}" TEMPLATE "taskflow_test"`);
  await admin.end();
  return process.env.TEST_DB_URL!.replace(/\/[^/]+$/, `/${nombre}`);
}
// En cada worker:  const url = await clonarPlantilla(`w${process.env.JEST_WORKER_ID}`);
// Ventaja añadida: al clonar una plantilla migrada, la suite verifica en cada
// ejecución que las migraciones se aplican sin errores. refreshDatabase() no.

describe('TransfersService.transferir (atomicidad)', () => {
  let orm: MikroORM; let service: TransfersService; let ledger: { registrar: jest.Mock };

  beforeEach(async () => {
    await truncateAll(orm);
    const em = orm.em.fork();
    em.create(Cuenta, { id: 'a', saldo: 1000 });
    em.create(Cuenta, { id: 'b', saldo: 0 });
    await em.flush();
  });

  it('el fallo del ledger no deja movimientos ni saldos a medias', async () => {
    ledger.registrar.mockRejectedValueOnce(new Error('ledger no disponible'));
    await expect(service.transferir('a', 'b', 100)).rejects.toThrow();
    const em = orm.em.fork();
    // Las TRES afirmaciones importan: origen intacto, destino intacto y
    // ningún movimiento huérfano. Un rollback parcial fallaría solo en una.
    expect((await em.findOneOrFail(Cuenta, 'a')).saldo).toBe(1000);
    expect((await em.findOneOrFail(Cuenta, 'b')).saldo).toBe(0);
    await expect(em.count(Movimiento, {})).resolves.toBe(0);
  });

  it('un fallo del driver en el segundo flush revierte el primero', async () => {
    const em = orm.em.fork();
    const real = em.flush.bind(em);
    let n = 0;
    // Spy PARCIAL: la primera escritura ocurre de verdad (así hay algo que
    // revertir) y la segunda simula una caída de la conexión.
    jest.spyOn(em, 'flush').mockImplementation(async () => {
      if (++n === 2) throw new Error('Connection terminated unexpectedly');
      return real();
    });
    await expect(service.transferirCon(em, 'a', 'b', 100)).rejects.toThrow();
    await expect(orm.em.fork().count(Movimiento, {})).resolves.toBe(0);
  });

  it('la transacción sobrevive a un statement_timeout como error, no como cuelgue', async () => {
    const em = orm.em.fork();
    await em.begin();
    await em.getConnection().execute("SET LOCAL statement_timeout = '50ms'");
    // Verificamos el contrato de errores: un timeout debe llegar al servicio
    // como excepción capturable, no dejar la conexión en estado indefinido.
    await expect(em.getConnection().execute('SELECT pg_sleep(1)')).rejects.toThrow();
    await em.rollback();
    expect(em.isInTransaction()).toBe(false);
  });
});

// Entidad:  @Property({ version: true }) version!: number;
describe('Bloqueo optimista sobre Task', () => {
  it('la segunda escritura concurrente falla con OptimisticLockError', async () => {
    const id = (await crearTarea(orm, { title: 'Original' })).id;
    // DOS contextos independientes = dos conexiones y dos Identity Map.
    const emA = orm.em.fork(); const emB = orm.em.fork();
    const a = await emA.findOneOrFail(Task, id);
    const b = await emB.findOneOrFail(Task, id);
    expect(a.version).toBe(b.version);        // ambos leyeron la versión 1

    a.title = 'Cambio de Ana';
    await emA.flush();                        // UPDATE ... WHERE version = 1 → ok, ahora 2

    b.title = 'Cambio de Bruno';
    // El UPDATE de B lleva WHERE version = 1 y afecta a 0 filas: el ORM lo
    // detecta y lanza. Sin versión, este UPDATE habría machacado el cambio de
    // Ana en silencio: la actualización perdida, el bug invisible por excelencia.
    await expect(emB.flush()).rejects.toBeInstanceOf(OptimisticLockError);
    expect((await orm.em.fork().findOneOrFail(Task, id)).title).toBe('Cambio de Ana');
  });

  it('el servicio traduce el conflicto a 409 y no a 500', async () => {
    // Un OptimisticLockError sin capturar sale como 500: el cliente creería
    // que el servidor está roto y reintentaría con la misma versión caducada.
    await expect(simularConflicto(orm, service)).rejects.toBeInstanceOf(ConflictException);
  });

  it('reintenta automáticamente y converge: dos incrementos, ninguno perdido', async () => {
    const id = (await crearContador(orm, { valor: 0 })).id;
    // Promise.all lanza ambas operaciones sobre el mismo bucle de eventos:
    // se solapan de verdad, no es una simulación.
    await Promise.all([service.incrementar(id), service.incrementar(id)]);
    // Con reintento sobre OptimisticLockError el resultado es 2. Sin él, uno
    // de los dos incrementos se pierde y el test devuelve 1: exactamente el
    // fallo que en producción descuadra un inventario o un saldo.
    expect((await orm.em.fork().findOneOrFail(Contador, id)).valor).toBe(2);
  });

  it('con bloqueo pesimista, la segunda transacción espera en lugar de fallar', async () => {
    // PESSIMISTIC_WRITE emite SELECT ... FOR UPDATE: la fila queda bloqueada
    // hasta el commit. Es la alternativa cuando el conflicto es FRECUENTE y
    // reintentar sale más caro que esperar. Imposible de testear en SQLite.
    const id = (await crearContador(orm, { valor: 0 })).id;
    await orm.em.fork().transactional(async (em) => {
      await em.findOneOrFail(Contador, id, { lockMode: LockMode.PESSIMISTIC_WRITE });
      const otro = orm.em.fork();
      // El segundo lector se queda esperando; con NOWAIT falla de inmediato,
      // que es lo que permite afirmarlo en un test sin colgarlo para siempre.
      await expect(otro.findOne(Contador, id,
        { lockMode: LockMode.PESSIMISTIC_WRITE_OR_FAIL })).rejects.toThrow();
    });
  });
});

// NIVEL 1 · Productor. El doble de la cola es trivial y la aserción es el
// CONTRATO del mensaje: quien lo consuma dependerá de esa forma exacta.
describe('ReportsService (productor)', () => {
  const queue = { add: jest.fn().mockResolvedValue({ id: 'job-1' }) };
  it('encola la generación con idempotencia y reintentos', async () => {
    await service.solicitarInforme('p-1', 'u-1');
    expect(queue.add).toHaveBeenCalledWith('generar-informe',
      { projectId: 'p-1', userId: 'u-1' },
      expect.objectContaining({
        // jobId estable: si el usuario pulsa el botón tres veces, BullMQ
        // deduplica. Sin esto se generan tres informes y se cobran tres veces.
        jobId: 'informe:p-1:u-1',
        attempts: 3, backoff: { type: 'exponential', delay: 1000 },
        removeOnComplete: 100, removeOnFail: 500,
      }));
  });
});
// NIVEL 2 · Consumidor. Es una clase normal: se prueba invocando su método
// con un Job falso. No hace falta Redis para verificar la LÓGICA.
describe('ReportProcessor (consumidor)', () => {
  const job = (data: object, over: object = {}) =>
    ({ id: 'job-1', name: 'generar-informe', data, attemptsMade: 0,
       updateProgress: jest.fn(), log: jest.fn(), ...over }) as unknown as Job;

  it('genera el informe y notifica al usuario', async () => {
    const res = await processor.process(job({ projectId: 'p-1', userId: 'u-1' }));
    expect(res).toMatchObject({ url: expect.stringContaining('p-1') });
    expect(mailer.enviar).toHaveBeenCalledTimes(1);
  });

  it('es idempotente: reprocesar un trabajo no duplica el informe', async () => {
    // Un worker puede morir tras terminar y antes de confirmar: BullMQ
    // reentrega. La entrega es "al menos una vez", NUNCA "exactamente una".
    // Si tu consumidor no es idempotente, tienes un bug latente garantizado.
    await processor.process(job({ projectId: 'p-1', userId: 'u-1' }));
    await processor.process(job({ projectId: 'p-1', userId: 'u-1' }));
    await expect(orm.em.fork().count(Informe, { project: 'p-1' })).resolves.toBe(1);
  });

  it('en el último intento marca el informe como fallido y avisa', async () => {
    generador.generar.mockRejectedValue(new Error('sin memoria'));
    // attemptsMade = 2 con attempts = 3: este es el ÚLTIMO intento. La rama
    // "ya no habrá reintentos" es la que nadie prueba y la que deja al
    // usuario esperando un correo que no llegará jamás.
    await expect(processor.process(job({ projectId: 'p-1' }, { attemptsMade: 2 })))
      .rejects.toThrow('sin memoria');
    expect(mailer.enviarFallo).toHaveBeenCalled();
  });
});

// Solo UN test de este tipo por cola: es el que verifica el cableado
// (nombre de cola, registro del procesador, serialización de la carga útil).
// Los casos de negocio se cubren en el nivel 2, que es cien veces más rápido.
describe('Cola de informes (integración)', () => {
  let redis: StartedRedisContainer; let queue: Queue; let events: QueueEvents;
  beforeAll(async () => {
    redis = await new RedisContainer('redis:7-alpine').start();
    // ... arrancar el módulo de Nest apuntando a redis.getConnectionUrl()
    events = new QueueEvents('informes', { connection });
    await events.waitUntilReady();
  }, 60_000);                    // el timeout por defecto de 5 s no basta
  afterAll(async () => { await events.close(); await queue.close(); await redis.stop(); });

  it('procesa el trabajo publicado por el endpoint', async () => {
    await http().post('/api/v1/projects/p-1/report').set(auth).expect(202);
    const [job] = await queue.getJobs(['waiting', 'active', 'delayed']);
    // ESPERAR AL EVENTO, jamás un setTimeout arbitrario: un sleep de 500 ms
    // es lento cuando sobra y es intermitente cuando falta.
    const resultado = await job.waitUntilFinished(events, 20_000);
    expect(resultado.url).toMatch(/^https:\/\//);
    await expect(orm.em.fork().count(Informe, {})).resolves.toBe(1);
  });
});

describe('withRetry (backoff exponencial)', () => {
  beforeEach(() => {
    jest.useFakeTimers({
      now: new Date('2026-03-15T10:00:00.000Z'),
      // CRÍTICO en Node: si falsificas nextTick y setImmediate, el driver de
      // PostgreSQL, los sockets y las propias promesas dejan de progresar y
      // el test se cuelga sin mensaje. Excluirlos es casi siempre correcto.
      doNotFake: ['nextTick', 'setImmediate'],
    });
  });
  afterEach(() => jest.useRealTimers());   // sin esto, contaminas los tests siguientes

  it('reintenta 3 veces con 1 s, 2 s y 4 s de espera', async () => {
    const op = jest.fn()
      .mockRejectedValueOnce(new Error('503')).mockRejectedValueOnce(new Error('503'))
      .mockResolvedValue('ok');
    const promesa = withRetry(op, { intentos: 3, baseMs: 1000 });
    // advanceTimersByTimeAsync (Jest 29+) vacía también la cola de microtareas:
    // la versión síncrona avanza el reloj pero deja los await sin resolver, y
    // el test se queda esperando para siempre. Es el error más común aquí.
    await jest.advanceTimersByTimeAsync(1000);
    expect(op).toHaveBeenCalledTimes(2);
    await jest.advanceTimersByTimeAsync(2000);
    await expect(promesa).resolves.toBe('ok');
    expect(op).toHaveBeenCalledTimes(3);
  });

  it('no deja temporizadores pendientes al terminar', async () => {
    await withRetry(jest.fn().mockResolvedValue('ok'), { intentos: 3 });
    // Un timer huérfano es una fuga: en producción mantiene vivo el proceso e
    // impide un apagado limpio; en Jest provoca el aviso "did not exit".
    expect(jest.getTimerCount()).toBe(0);
  });

  it('el timestamp escrito es exactamente el momento congelado', async () => {
    jest.setSystemTime(new Date('2026-12-31T23:59:59.000Z'));
    const t = await service.crear({ title: 'Nochevieja' });
    expect(t.createdAt.toISOString()).toBe('2026-12-31T23:59:59.000Z');
  });
});

@Injectable()
export class NightlyService {
  @Cron('0 3 * * *', { name: 'purga-nocturna', timeZone: 'Europe/Madrid' })
  async handleCron(): Promise<void> { await this.purgar(); }
  // La LÓGICA vive aquí, en un método público, testeable y reutilizable
  // desde un comando de CLI o desde un endpoint de administración.
  async purgar(): Promise<number> { /* ... */ }
}
describe('NightlyService', () => {
  it('purga las tareas archivadas hace más de 90 días', async () => {
    // 1· El QUÉ: un test normal, sin cron, sin esperas, con reloj fijo.
    clock.set('2026-06-01T03:00:00Z');
    await crear(em, taskFactory({ archivedAt: DIA('2026-01-01') }),   // 151 días
                   taskFactory({ archivedAt: DIA('2026-05-15') }),   // 17 días
                   taskFactory({ archivedAt: null }));
    await expect(service.purgar()).resolves.toBe(1);
    await expect(em.fork().count(Task, {})).resolves.toBe(2);
  });

  it('está programado a las 03:00 con la zona horaria correcta', async () => {
    // 2· El CUÁNDO: es configuración, y una configuración mal escrita es un
    // bug silencioso. Con timeZone mal puesta, la purga se ejecuta a las 02:00
    // en invierno y a las 04:00 en verano, o dos veces la noche del cambio.
    const job = registry.getCronJob('purga-nocturna');
    expect(job.cronTime.source).toBe('0 3 * * *');
    expect(job.cronTime.timeZone).toBe('Europe/Madrid');
    // Con la próxima ejecución también se puede afirmar sobre fechas concretas:
    expect(job.nextDate().toISO()).toContain('T03:00:00');
  });

  it('el disparo manual del trabajo invoca la lógica (cableado)', async () => {
    // 3· El CABLEADO: fireOnTick() ejecuta el callback registrado sin esperar
    // al horario. Comprueba que el decorador apunta al método correcto, que es
    // lo único que los dos tests anteriores no cubren. La API pertenece a la
    // librería 'cron' que usa @nestjs/schedule: confirma su nombre en tu versión.
    const espia = jest.spyOn(service, 'purgar').mockResolvedValue(0);
    await registry.getCronJob('purga-nocturna').fireOnTick();
    expect(espia).toHaveBeenCalledTimes(1);
  });
});

import { faker } from '@faker-js/faker';
// Semilla fija: la MISMA secuencia en tu portátil, en el de tu compañera y en
// CI. Si un test falla, falla en todas partes, que es justo lo que quieres.
beforeEach(() => { faker.seed(20260315); contador = 0; });
// Los valores que deben ser ÚNICOS no se generan al azar: se cuentan. Faker
// puede repetir, y una violación de unicidad intermitente cuesta días.
let contador = 0;
export const emailUnico = () => `usuario-${++contador}@example.test`;
// Identificadores deterministas: un IdGenerator inyectable.
export abstract class IdGenerator { abstract next(): string; }
export class UuidGenerator extends IdGenerator { next() { return randomUUID(); } }
export class SequentialIdGenerator extends IdGenerator {
  private n = 0;
  next() { return `00000000-0000-4000-8000-${String(++this.n).padStart(12, '0')}`; }
}
// Con ids predecibles la aserción es completa y legible, sin expect.any(String):
it('crea la tarea con el id esperado', async () => {
  await expect(service.crear({ title: 'A' })).resolves.toEqual({
    id: '00000000-0000-4000-8000-000000000001',
    title: 'A', status: TaskStatus.Todo, createdAt: AHORA,
  });
});
// Y para la lógica que USA el azar, inyecta también la fuente aleatoria:
//   constructor(private readonly random: () => number = Math.random) {}
// En el test:  new Muestreador(() => 0.05)  → cae dentro del 10% muestreado.

export async function createTestApp(customize?: (b: TestingModuleBuilder) => void) {
  const builder = Test.createTestingModule({ imports: [AppModule] })
    // Lo único que se sustituye: efectos hacia el exterior.
    .overrideProvider(MailService).useValue({ send: jest.fn().mockResolvedValue(undefined) })
    .overrideProvider(PaymentsGateway).useValue({ charge: jest.fn().mockResolvedValue({ ok: true }) });
  customize?.(builder);
  const moduleRef = await builder.compile();
  const app = moduleRef.createNestApplication({ logger: false });   // sin ruido
  configureApp(app);       // ← LA MISMA función que usa main.ts
  await app.init();
  return { app, moduleRef, orm: app.get(MikroORM),
           http: () => request(app.getHttpServer()) };
}

describe('Flujo completo de un usuario (e2e)', () => {
  let app: INestApplication; let orm: MikroORM;
  let http: () => request.SuperTest<request.Test>;
  let token: string; let projectId: string; let taskId: string;
  beforeAll(async () => { ({ app, orm, http } = await createTestApp()); });
  afterAll(async () => { await orm.close(true); await app.close(); });
  beforeAll(async () => { await truncateAll(orm); });
  const auth = () => ({ Authorization: `Bearer ${token}` });
  // Este describe es un ESCENARIO: los pasos comparten estado a propósito
  // y van en orden. Los demás archivos deben ser independientes.
  it('1· registro: 201 y no devuelve el hash de la contraseña', async () => {
    const { body } = await http().post('/api/v1/auth/register')
      .send({ email: 'ana@example.com', password: 'S3gura!2026', name: 'Ana' })
      .expect(201);
    expect(body).toMatchObject({ email: 'ana@example.com' });
    expect(body).not.toHaveProperty('password');
    expect(body).not.toHaveProperty('passwordHash');   // fuga clásica
    // Efecto en la base de datos: la contraseña se guarda hasheada.
    const user = await orm.em.fork().findOneOrFail(User, { email: 'ana@example.com' });
    expect(user.passwordHash).not.toBe('S3gura!2026');
    expect(user.passwordHash).toMatch(/^\$2[aby]\$/);   // bcrypt
  });

  it('2· login: 200 con token, y 401 con contraseña incorrecta', async () => {
    await http().post('/api/v1/auth/login')
      .send({ email: 'ana@example.com', password: 'mal' }).expect(401);
    const { body } = await http().post('/api/v1/auth/login')
      .send({ email: 'ana@example.com', password: 'S3gura!2026' }).expect(200);
    token = body.accessToken;
    expect(token.split('.')).toHaveLength(3);
  });

  it('3· sin token: 401; con token: crea el proyecto y devuelve Location', async () => {
    await http().post('/api/v1/projects').send({ name: 'X' }).expect(401);
    const res = await http().post('/api/v1/projects').set(auth())
      .send({ name: 'Migración a Nest' }).expect(201);
    projectId = res.body.id;
    expect(res.headers.location).toBe(`/api/v1/projects/${projectId}`);
  });

  it('4· crea dos tareas dentro del proyecto', async () => {
    const crear = (title: string, tags: string[], dueDate: string) =>
      http().post(`/api/v1/projects/${projectId}/tasks`).set(auth())
        .send({ title, tags, dueDate }).expect(201);
    taskId = (await crear('Escribir tests', ['qa'], '2026-04-01')).body.id;
    await crear('Revisar PR', ['review'], '2026-04-05');
  });

  it('5· lista con filtro y paginación', async () => {
    const { body } = await http()
      .get(`/api/v1/projects/${projectId}/tasks?tag=qa&page=1&limit=10`)
      .set(auth()).expect(200);
    expect(body.total).toBe(1);
    expect(body.items[0]).toMatchObject({ id: taskId, title: 'Escribir tests' });
  });

  it('6· otro usuario no puede ver ni borrar la tarea (403, no 404 genérico)', async () => {
    const otro = await registrarYLogin(http, 'bob@example.com');
    await http().delete(`/api/v1/tasks/${taskId}`)
      .set({ Authorization: `Bearer ${otro}` }).expect(403);
  });

  it('7· borra la tarea: 204 sin cuerpo, y desaparece de la base de datos', async () => {
    const res = await http().delete(`/api/v1/tasks/${taskId}`).set(auth()).expect(204);
    expect(res.body).toEqual({});
    await expect(orm.em.fork().findOne(Task, { id: taskId })).resolves.toBeNull();
  });

  it('8· la tarea borrada da 404, y un id con formato inválido da 400', async () => {
    await http().get(`/api/v1/tasks/${taskId}`).set(auth()).expect(404);
    await http().get('/api/v1/tasks/no-es-un-uuid').set(auth()).expect(400);
  });
});

import { faker } from '@faker-js/faker';
// Los valores por defecto son VÁLIDOS pero irrelevantes: así el test solo
// escribe lo que importa, y ese delta es la documentación del caso.
export const taskFactory = (over: Partial<RequiredEntityData<Task>> = {})
  : RequiredEntityData<Task> => ({
  title: faker.lorem.sentence(3),
  description: null, status: TaskStatus.Todo, priority: Priority.Medium,
  tags: [], dueDate: null, createdAt: new Date('2026-01-01T00:00:00Z'),
  ...over,
});
// Un seeder de MikroORM para escenarios completos (demos, entorno local, e2e
// que necesitan volumen). En los tests unitarios, siempre factorías.
export class DemoSeeder extends Seeder {
  async run(em: EntityManager): Promise<void> {
    const owner = em.create(User, userFactory({ email: 'demo@example.com' }));
    const project = em.create(Project, projectFactory({ owner, name: 'Demo' }));
    for (let i = 0; i < 50; i++) em.create(Task, taskFactory({ project }));
    // Sin flush: lo hace el SeedManager al terminar.
  }
}

// 1· Generar el esquema sin arrancar un servidor HTTP: rápido y determinista.
export async function generarEsquema(): Promise<OpenAPIObject> {
  const app = await NestFactory.create(AppModule, { logger: false });
  configureApp(app);                       // el MISMO prefijo y versionado
  const doc = SwaggerModule.createDocument(app, new DocumentBuilder()
    .setTitle('TaskFlow API').setVersion(process.env.APP_VERSION ?? '1.0.0').build());
  await app.close();
  return doc;
}
// 2· Guardarlo en el repositorio y comprobarlo en cada ejecución. Si alguien
// cambia un DTO, este test falla y le OBLIGA a mirar el diff del esquema: el
// cambio deja de ser accidental y pasa a ser una decisión consciente.
it('el esquema público no ha cambiado sin querer', async () => {
  const actual = await generarEsquema();
  expect(actual).toMatchSnapshot();        // o comparar con openapi.json versionado
});
// 3· Y verificar que las RESPUESTAS reales se ajustan al esquema. Un contrato
// que nadie comprueba en ejecución es documentación, no contrato.
import jestOpenAPI from 'jest-openapi';
beforeAll(async () => jestOpenAPI(await generarEsquema()));
it('GET /tasks/:id satisface el esquema declarado', async () => {
  const res = await http().get(`/api/v1/tasks/${id}`).set(auth).expect(200);
  // Detecta lo que ningún toMatchObject detecta: campos declarados que no
  // llegan, tipos que no coinciden, formatos date-time rotos, nulos donde el
  // esquema dice que no puede haberlos.
  expect(res).toSatisfyApiSpec();
});

jobs:
  contrato:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: npm ci && npm run openapi:generate      # escribe openapi.json
      # oasdiff compara dos esquemas y clasifica los cambios. Solo los
      # BREAKING rompen el pipeline: añadir un campo opcional o un endpoint
      # nuevo es retrocompatible y no debe molestar a nadie.
      - name: Cambios incompatibles frente a main
        run: |
          git show origin/main:openapi.json > /tmp/base.json
          npx @tufin/oasdiff breaking /tmp/base.json openapi.json --fail-on ERR
      # El cliente del frontend se GENERA, no se escribe a mano: así el
      # compilador de TypeScript del consumidor detecta la ruptura en cuanto
      # se regenera, sin necesidad de ejecutar nada.
      - run: npx openapi-typescript openapi.json -o ../frontend/src/api/schema.d.ts
      - run: cd ../frontend && npx tsc --noEmit

import http from 'k6/http';
import { check, group, sleep } from 'k6';
import { Trend, Rate } from 'k6/metrics';
const latenciaListado = new Trend('latencia_listado_ms');
const erroresNegocio = new Rate('errores_negocio');
export const options = {
  scenarios: {
    // ramping-vus modela USUARIOS concurrentes: cada uno espera la respuesta
    // antes de seguir. Es el modelo realista para una API con clientes reales.
    carga: { executor: 'ramping-vus', startVUs: 0, stages: [
      { duration: '1m', target: 50 },     // rampa: nunca empieces en frío al máximo
      { duration: '5m', target: 50 },     // meseta: aquí se miden los percentiles
      { duration: '1m', target: 0 },      // bajada: comprueba que se recupera
    ] },
    // ramping-arrival-rate modela PETICIONES POR SEGUNDO con independencia de
    // lo que tarde el servidor. Es el modelo correcto para un pico: los
    // usuarios reales no dejan de pulsar porque tu servidor vaya lento.
    picos: { executor: 'ramping-arrival-rate', startTime: '8m',
      startRate: 20, timeUnit: '1s', preAllocatedVUs: 300,
      stages: [{ duration: '30s', target: 20 }, { duration: '15s', target: 400 },
               { duration: '1m', target: 400 }, { duration: '30s', target: 20 }] },
  },
  thresholds: {
    // El umbral ES el SLO escrito como código. Si no se cumple, k6 termina
    // con código 1 y el pipeline se pone en rojo, igual que un test unitario.
    'http_req_duration{escenario:listado}': ['p(95)<300', 'p(99)<800'],
    'http_req_failed': ['rate<0.01'],                    // menos del 1% de errores
    'errores_negocio': ['rate<0.001'],
    // abortOnFail corta la ejecución en cuanto se incumple: no tiene sentido
    // seguir castigando un sistema que ya sabemos que no cumple.
    'http_req_duration{escenario:escritura}': [{ threshold: 'p(95)<500', abortOnFail: true }],
  },
};
export function setup() {                 // se ejecuta UNA vez, antes de todo
  const r = http.post(`${__ENV.BASE_URL}/api/v1/auth/login`,
    JSON.stringify({ email: 'carga@example.test', password: __ENV.PASS }),
    { headers: { 'Content-Type': 'application/json' } });
  return { token: r.json('accessToken') };
}
export default function (data) {
  const auth = { headers: { Authorization: `Bearer ${data.token}` } };
  group('listado con filtro y paginación', () => {
    // La página 1 sale de la caché y no representa nada: hay que pedir páginas
    // dispersas y filtros variados, o estarás midiendo tu caché, no tu API.
    const page = Math.floor(Math.random() * 20) + 1;
    const res = http.get(`${__ENV.BASE_URL}/api/v1/tasks?page=${page}&limit=20&tag=qa`,
      Object.assign({ tags: { escenario: 'listado' } }, auth));
    latenciaListado.add(res.timings.duration);
    // Comprobar el CUERPO, no solo el estado: un servidor saturado puede
    // devolver 200 con una lista vacía y la prueba parecería perfecta.
    const ok = check(res, {
      'estado 200': (r) => r.status === 200,
      'devuelve elementos': (r) => r.json('items').length > 0,
    });
    erroresNegocio.add(!ok);
  });
  sleep(Math.random() * 2 + 1);   // tiempo de reflexión: un usuario no dispara
}                                  // peticiones sin parar, y sin sleep mides otra cosa

LoggerModule.forRoot({
  pinoHttp: {
    level: process.env.LOG_LEVEL ?? (isProd ? 'info' : 'debug'),
    // Un id por petición: si el cliente ya envía uno, se respeta, para poder
    // seguir la traza entre servicios; y se devuelve para que el usuario que
    // reporta un fallo pueda darte el identificador exacto.
    genReqId: (req, res) => {
      const id = (req.headers['x-request-id'] as string) ?? randomUUID();
      res.setHeader('x-request-id', id);
      return id;
    },
    // REDACCIÓN: obligatoria y por lista explícita de rutas conocidas.
    redact: {
      paths: ['req.headers.authorization', 'req.headers.cookie',
        'res.headers["set-cookie"]', 'req.body.password', 'req.body.newPassword',
        'req.body.token', 'req.body.card.number', 'req.body.card.cvv',
        '*.passwordHash', '*.refreshToken'],
      censor: '[REDACTADO]', remove: false,   // saber que el campo existía es útil
    },
    // Serializadores: volcar el req entero es una fuga de datos garantizada.
    serializers: { req: (r) => ({ id: r.id, method: r.method, url: r.url }),
                   res: (r) => ({ statusCode: r.statusCode }) },
    // Cada respuesta con su nivel: 5xx es error nuestro, 4xx es aviso.
    customLogLevel: (_req, res, err) =>
      err || res.statusCode >= 500 ? 'error' : res.statusCode >= 400 ? 'warn' : 'info',
    // MUESTREO: /health y /metrics generan miles de líneas sin información.
    autoLogging: { ignore: (req) => ['/health', '/metrics'].includes(req.url!) },
    // En desarrollo, salida legible; en producción, JSON puro a stdout, que
    // recoge el orquestador. Nunca escribas archivos de log desde la aplicación.
    transport: isProd ? undefined
      : { target: 'pino-pretty', options: { singleLine: true, translateTime: 'HH:MM:ss.l' } },
    base: { service: 'tasks-api', version: process.env.APP_VERSION,
            instance: process.env.HOSTNAME },   // filtrar por versión e instancia
  },
});
// main.ts: sustituye el logger de Nest por Pino, para que también los mensajes
// internos del framework salgan en JSON.
const app = await NestFactory.create(AppModule, { bufferLogs: true });
app.useLogger(app.get(Logger));

type Ctx = { requestId: string; userId?: string; traceId?: string };
const als = new AsyncLocalStorage<Ctx>();
export const RequestContext = {
  run: (ctx: Ctx, fn: () => unknown) => als.run(ctx, fn),
  get: () => als.getStore(),
  set: (patch: Partial<Ctx>) => Object.assign(als.getStore() ?? {}, patch),
};
@Injectable()
export class RequestContextMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const requestId = (req.headers['x-request-id'] as string) ?? randomUUID();
    res.setHeader('x-request-id', requestId);
    RequestContext.run({ requestId, traceId: trace.getActiveSpan()?.spanContext().traceId },
                       () => next());
  }
}
// Propagación: el mismo identificador debe viajar a TODAS las fronteras.
// 1) Llamadas HTTP salientes: cabecera x-request-id en el interceptor de Axios.
// 2) Colas: como metadato del job, y restaurado con RequestContext.run() en el worker.
// 3) Base de datos: como comentario SQL, para cruzar el log lento con la petición.
// Si se pierde en una frontera, la traza se corta justo donde más la necesitas.

@Module({
  imports: [PrometheusModule.register({ path: '/metrics',
    defaultMetrics: { enabled: true } })],   // CPU, memoria, lag del event loop, GC
  providers: [
    // R y E de RED: contador con etiquetas de BAJA cardinalidad.
    makeCounterProvider({ name: 'http_requests_total', help: 'Peticiones atendidas',
      labelNames: ['method', 'route', 'status'] }),
    // D de RED: histograma en SEGUNDOS, con buckets ajustados al SLO.
    makeHistogramProvider({ name: 'http_request_duration_seconds', help: 'Duración',
      labelNames: ['method', 'route', 'status'],
      buckets: [0.01, 0.05, 0.1, 0.3, 0.5, 1, 2.5, 5, 10] }),
    // Saturación: el pool de la base de datos es el límite más habitual.
    makeGaugeProvider({ name: 'db_pool_connections', help: 'Conexiones',
      labelNames: ['state'] }),
  ],
})
export class MetricsModule {}
@Injectable()
export class MetricsInterceptor implements NestInterceptor {
  constructor(
    @InjectMetric('http_requests_total') private readonly total: Counter,
    @InjectMetric('http_request_duration_seconds') private readonly dur: Histogram,
  ) {}
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const req = ctx.switchToHttp().getRequest();
    // CLAVE: la RUTA con parámetros (/tasks/:id), nunca la url concreta. Con
    // /tasks/018f-… tendrías una serie temporal por id: explosión de
    // cardinalidad que tumba al servidor de métricas.
    const route = req.route?.path ?? 'unknown';
    const fin = this.dur.startTimer({ method: req.method, route });
    return next.handle().pipe(finalize(() => {
      const status = String(ctx.switchToHttp().getResponse().statusCode);
      fin({ status });
      this.total.inc({ method: req.method, route, status });
    }));
  }
}

// El SDK parchea los módulos al cargarlos: si se inicializa después de
// importar Express o pg, la instrumentación automática no se aplica.
const sdk = new NodeSDK({
  resource: new Resource({ [ATTR_SERVICE_NAME]: 'tasks-api',
    [ATTR_SERVICE_VERSION]: process.env.APP_VERSION ?? 'dev' }),
  traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_ENDPOINT }),
  // Automática: HTTP entrante y saliente, Express/Fastify, pg, redis, nest-core.
  instrumentations: [getNodeAutoInstrumentations({
    '@opentelemetry/instrumentation-fs': { enabled: false },   // demasiado ruido
    '@opentelemetry/instrumentation-pg': { enhancedDatabaseReporting: true },
  })],
  // Muestreo: el 100% en un servicio con tráfico es carísimo. Este muestreador
  // hereda la decisión del padre y, si no hay padre, toma el 10%.
  sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.1) }),
});
sdk.start();
// Instrumentación MANUAL: solo para lo que el SDK no puede saber, es decir,
// tus operaciones de negocio.
async close(projectId: string, userId: string) {
  return tracer.startActiveSpan('project.close', async (span) => {
    span.setAttributes({ 'project.id': projectId, 'user.id': userId });
    try {
      const p = await this.doClose(projectId, userId);
      span.setAttribute('project.tasks_count', p.tasks.count());
      return p;
    } catch (e) {
      span.recordException(e as Error);                      // el error, en la traza
      span.setStatus({ code: SpanStatusCode.ERROR, message: (e as Error).message });
      throw e;
    } finally { span.end(); }   // SIEMPRE: un span sin end() es una fuga de memoria
  });
}

import { trace, context } from '@opentelemetry/api';
LoggerModule.forRoot({
  pinoHttp: {
    // mixin() se ejecuta en CADA línea y añade campos calculados. Lee el span
    // activo del contexto de OpenTelemetry, que AsyncLocalStorage mantiene vivo
    // a través de todos los await de la misma cadena asíncrona.
    mixin() {
      const span = trace.getSpan(context.active());
      if (!span) return {};                       // cron, arranque, consumidor
      const { traceId, spanId } = span.spanContext();
      // Nombres normalizados por OpenTelemetry: los backends de logs los
      // reconocen y ofrecen el enlace directo a la traza. Inventarse el nombre
      // (reqTraceId, tid...) rompe esa integración automática.
      return { trace_id: traceId, span_id: spanId,
               service: 'tasks-api', env: process.env.NODE_ENV };
    },
  },
});
// Y devolver el identificador al cliente: cuando alguien abra una incidencia,
// llegará con el dato exacto en lugar de "esta mañana no me funcionaba".
@Injectable()
export class TraceHeaderInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler) {
    const traceId = trace.getSpan(context.active())?.spanContext().traceId;
    if (traceId) ctx.switchToHttp().getResponse().setHeader('x-trace-id', traceId);
    return next.handle();
  }
}

// Métricas de NEGOCIO: contadores de eventos con significado para el producto.
makeCounterProvider({ name: 'taskflow_tasks_created_total', help: 'Tareas creadas',
  labelNames: ['plan'] });                    // baja cardinalidad: free|pro|team
makeCounterProvider({ name: 'taskflow_projects_closed_total', help: 'Proyectos cerrados' });
makeCounterProvider({ name: 'taskflow_signups_total', help: 'Altas', labelNames: ['origen'] });
makeHistogramProvider({ name: 'taskflow_report_generation_seconds',
  help: 'Duración de la generación de informes', buckets: [1, 5, 15, 30, 60, 120] });
// Se incrementan en el punto donde el hecho de negocio OCURRE de verdad, es
// decir, después de confirmar la transacción y no antes de intentarla.
async close(projectId: string, userId: string): Promise<Project> {
  const project = await this.em.transactional(/* ... */);
  this.proyectosCerrados.inc();
  return project;
}
// La alerta que ninguna métrica técnica puede dar:
//   - alert: SinAltasEnUnaHora
//     expr: sum(increase(taskflow_signups_total[1h])) == 0
//           and hour() > 7 and hour() < 23      # de madrugada el cero es normal
//     for: 15m
//   Detecta el formulario roto, el correo de verificación que no sale y el
//   despliegue que rompió el registro sin devolver un solo error 5xx.

@Controller('health')
export class HealthController {
  constructor(private health: HealthCheckService, private db: MikroOrmHealthIndicator,
              private disk: DiskHealthIndicator, private mem: MemoryHealthIndicator) {}
  // LIVENESS: sin dependencias externas. Si comprobaras la base de datos aquí,
  // una caída de la base de datos provocaría el reinicio en bucle de TODAS las
  // instancias sanas: un fallo parcial convertido en caída total.
  @Get('live') @HealthCheck()
  live() { return this.health.check([]); }
  // READINESS: sí comprueba dependencias, con timeout corto y cacheado para no
  // convertir el propio check en carga (lo llaman cada pocos segundos).
  @Get('ready') @HealthCheck()
  ready() {
    return this.health.check([
      () => this.db.pingCheck('database', { timeout: 1500 }),
      () => this.mem.checkHeap('memory_heap', 512 * 1024 * 1024),
      () => this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
    ]);
  }
}

# 1· Aplicación con inspector y recarga (el starter de Nest ya lo trae).
nest start --debug --watch          # abre 127.0.0.1:9229
# 2· Depurar TESTS. Sin --runInBand los breakpoints caen en otro proceso.
node --inspect-brk node_modules/.bin/jest --runInBand --testPathPattern=projects
# 3· En Docker: hay que escuchar en 0.0.0.0, no en localhost, y publicar 9229.
#    --inspect-brk PARA el proceso hasta que te conectas: así depuras el arranque.
node --inspect-brk=0.0.0.0:9229 dist/main.js     # + ports: ["9229:9229"]
# 4· Perfilado de CPU: 30 s de muestreo en producción, coste ~5%.
kill -USR2 <pid>   # o node --cpu-prof --cpu-prof-dir=/tmp dist/main.js
#    El .cpuprofile se abre en la pestaña Performance de Chrome DevTools.
# 5· FUGAS DE MEMORIA: tres heap snapshots (arranque, 1 h, 2 h) y comparar
#    la vista "Objects allocated between snapshots". Lo que crece y no baja
#    tras el GC es tu fuga: casi siempre un Map/array global que solo se
#    llena, un listener que se añade por petición, o un span sin end().
node --heapsnapshot-signal=SIGUSR2 --max-old-space-size=512 dist/main.js

@Controller('admin/diagnostics')
@UseGuards(JwtAuthGuard, RolesGuard) @Roles(Role.Admin)   // NUNCA sin proteger
export class DiagnosticsController {
  constructor(@InjectPinoLogger() private readonly logger: PinoLogger) {}
  /**
   * Sube el nivel de log sin redesplegar y lo devuelve solo con un temporizador.
   * Lo segundo es lo importante: el 'debug' que alguien activó durante una
   * incidencia y olvidó apagar multiplica por cincuenta la factura de logs y
   * entierra las líneas útiles. La caducidad convierte el olvido en imposible.
   */
  @Post('log-level')
  cambiarNivel(@Body() dto: { level: Level; durationSec?: number }) {
    const anterior = this.logger.logger.level;
    this.logger.logger.level = dto.level;
    const ms = Math.min(dto.durationSec ?? 300, 1800) * 1000;   // 30 min como techo
    setTimeout(() => { this.logger.logger.level = anterior; }, ms).unref();
    return { level: dto.level, revierteA: anterior, enSegundos: ms / 1000 };
  }
  /** Perfilado de CPU bajo demanda: N segundos de muestreo y a descargar. */
  @Post('cpu-profile')
  async perfilar(@Body() dto: { seconds?: number }) {
    const session = new inspector.Session();
    session.connect();
    // El muestreador toma pilas cada microsegundo; NO instrumenta el código,
    // por eso el coste es bajo y se puede usar con tráfico real.
    await post(session, 'Profiler.enable');
    await post(session, 'Profiler.start');
    await new Promise((r) => setTimeout(r, Math.min(dto.seconds ?? 20, 60) * 1000));
    const { profile } = await post(session, 'Profiler.stop');
    session.disconnect();
    const ruta = `/tmp/cpu-${Date.now()}.cpuprofile`;   // se abre en Chrome DevTools
    await writeFile(ruta, JSON.stringify(profile));
    return { ruta };
  }
  /** Instantánea del montículo: útil y CARA. Ver el aviso siguiente. */
  @Post('heap-snapshot')
  heapSnapshot() { return { ruta: v8.writeHeapSnapshot(`/tmp/heap-${Date.now()}.heapsnapshot`) }; }
}

import { monitorEventLoopDelay } from 'node:perf_hooks';
// Node es monohilo: si una función síncrona tarda 300 ms, TODAS las peticiones
// en vuelo esperan 300 ms, aunque la CPU esté al 20% y la base de datos ociosa.
// Ese retraso no aparece en ninguna métrica de latencia por endpoint: aparece
// repartido y homogéneo en todos, que es justo lo que despista.
const histograma = monitorEventLoopDelay({ resolution: 20 });
histograma.enable();
setInterval(() => {
  lagP99.set(histograma.percentile(99) / 1e6);   // nanosegundos → milisegundos
  lagMedia.set(histograma.mean / 1e6);
  histograma.reset();
}, 10_000).unref();
// Interpretación:  < 10 ms sano · 10–50 ms carga alta · > 100 ms hay trabajo
// síncrono bloqueando: JSON.parse de cargas enormes, bcrypt con coste alto en
// el hilo principal, expresiones regulares con retroceso catastrófico, bucles
// sobre colecciones grandes, o serialización de respuestas de megabytes.
// La solución no es "optimizar un poco": es sacar ese trabajo del hilo
// principal (worker_threads, cola, streaming) o trocearlo.

name: CI
on: { pull_request: {}, push: { branches: [main] } }
concurrency:                       # cancela ejecuciones obsoletas del mismo PR
  group: ci-${{ github.ref }}
  cancel-in-progress: true
jobs:
  estatico:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }   # caché de ~/.npm por package-lock
      - run: npm ci
      - run: npx tsc --noEmit                    # los tipos, aparte de SWC
      - run: npx eslint . --max-warnings=0
      - run: npx mikro-orm migration:check       # ¿modelo y migraciones cuadran?
  tests:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: { shard: [1, 2, 3, 4] }   # 4 procesos: la suite tarda 1/4
    services:
      postgres:
        image: postgres:16-alpine
        env: { POSTGRES_PASSWORD: test, POSTGRES_DB: test }
        ports: ['5432:5432']
        # SIN health-cmd, los tests arrancan antes que la base de datos:
        # fallo intermitente clásico en CI y muy difícil de reproducir.
        options: >-
          --health-cmd "pg_isready -U postgres" --health-interval 5s
          --health-timeout 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:test@localhost:5432/test
      TZ: UTC          # zona horaria fija: evita fallos que solo ocurren en CI
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - run: npx jest --shard=${{ matrix.shard }}/4 --coverage --maxWorkers=2
      - uses: actions/upload-artifact@v4
        if: always()          # los informes del intento FALLIDO son los útiles
        with: { name: coverage-${{ matrix.shard }}, path: coverage/ }
  # Job requerido en la protección de rama: "no se mergea en rojo". La regla es
  # social antes que técnica; la protección de rama solo la hace cumplir.
  todo-verde:
    needs: [estatico, tests]
    runs-on: ubuntu-latest
    steps: [{ run: echo "Listo para mergear" }]