1. ¿Qué es y para qué sirve?

ts-mockito es una potente librería para crear mocks, stubs y spies en TypeScript. Está inspirada en la popular librería Java Mockito y ofrece una API familiar para desarrolladores que vienen de Java o Python. El objetivo principal de ts-mockito es simplificar la escritura de unit tests, aislando el código bajo prueba de dependencias externas como bases de datos, clientes HTTP, sistemas de archivos y otros servicios.

¿Por qué es necesario? En las aplicaciones modernas de TypeScript, las clases y funciones suelen depender de otros componentes. Sin mocks, probar estas relaciones se convierte en una prueba de integración que requiere configurar todo el entorno. ts-mockito te permite crear objetos "falsos" con un comportamiento predefinido y verificar qué métodos se llamaron y con qué argumentos. Esto hace que las pruebas sean rápidas, deterministas y fáciles de mantener.

La librería soporta todas las funcionalidades principales de Mockito: creación de mocks con mock(), configuración de comportamiento con when() y thenReturn(), verificación de llamadas con verify(), y trabajo con spies mediante spy(). ts-mockito está completamente tipada y se integra perfectamente con frameworks de testing populares como Jest, Mocha y Jasmine.

2. Instalación

La instalación de ts-mockito se realiza a través de npm (Node Package Manager). Ejecuta el siguiente comando en la raíz de tu proyecto:

npm install ts-mockito --save-dev

Si usas yarn:

yarn add ts-mockito --dev

La librería no tiene dependencias obligatorias, excepto el propio TypeScript (versión 4.0+). Después de la instalación, puedes importar las funciones necesarias en tus archivos de prueba:

import { mock, when, verify, instance, anything, anyOfClass, deepEqual, spy } from 'ts-mockito';

Ten en cuenta: ts-mockito utiliza objetos proxy para interceptar las llamadas. Esto significa que siempre trabajas con objetos "envueltos", no con instancias reales de las clases.

3. Inicio rápido — ejemplo mínimo funcional

Veamos un ejemplo sencillo: tenemos una clase UserService que depende de UserRepository. Queremos probar el método getUser sin acceder a la base de datos real.

// user-repository.ts
export class UserRepository {
    async findById(id: number): Promise<{ id: number; name: string } | null> {
        // Consulta real a la BD
        return null;
    }
}

// user-service.ts
export class UserService {
    constructor(private repository: UserRepository) {}

    async getUser(id: number): Promise<string> {
        const user = await this.repository.findById(id);
        if (!user) {
            throw new Error('User not found');
        }
        return `User: ${user.name}`;
    }
}

// user-service.spec.ts
import { mock, when, instance, verify, anything } from 'ts-mockito';
import { UserService } from './user-service';
import { UserRepository } from './user-repository';

describe('UserService', () => {
    it('should return user name when user exists', async () => {
        // 1. Creamos un mock del repositorio
        const mockRepository: UserRepository = mock(UserRepository);
        
        // 2. Configuramos el comportamiento: al llamar findById(1) devolvemos un objeto
        when(mockRepository.findById(1)).thenResolve({ id: 1, name: 'Alice' });
        
        // 3. Obtenemos la instancia real del mock
        const repositoryInstance = i