You can create an object with methods exposed as test doubles that are typed according to the passed interface. This comes very handy in unit testing. Without the typesafety we could be making our tests pass while implementing the functionality that does not apply to the contract.
Let's create a mocked object for a following interface:
interface IUserRepository {
findByName(name: string): string;
}
const mockedRepository = td.object<IUserRepository>();Now we can work with it as with any other testdouble object:
td.when(mockedRepository.findByName("Alice")).thenReturn("Alice Alicy");
const value = mockedRepository.findByName("Alice");
expect(value).toEqual("Alice Alicy");What's different is that we get the typesafety - meaning, typescript will alert us in following three situations:
td.when(mockedRepository.findByName(3)).thenReturn("Alice Alicy");with
TS2345: Argument of type '3' is not assignable to parameter of type 'string'.
And:
td.when(mockedRepository.findByNaame("Alice")).thenReturn("returnedString");with
TS2551: Property 'findByNaame' does not exist on type 'IUserRepository'. Did you mean 'findByName'?
And finally:
td.when(mockedRepository.findByName("Alice")).thenReturn({ lastName: "Alicy" });
const found = mockedRepository.findByName("Alice");
expect(found.lastName).toEqual("Alicy");gives us: TS2339: Property 'lastName' does not exist on type 'string'.
Similarly to working with interfaces you can define a function type, and create a test double based on it:
type pickFirstFrom = (strings: string[]) => string;
const mockedPickFirst = td.func<pickFirstFrom>();Again, typescript helps us mock properly:
mockedPickFirst("myString");TS2345: Argument of type '"myString"' is not assignable to parameter of type 'string[]'.
And also ensures that we don't wrongly use returned values:
td.when(mockedPickFirst(["", ""])).thenReturn({ abc: () => {} });
const result = mockedPickFirst(["", ""]);
result.abc();Gives us:
TS2339: Property 'abc' does not exist on type 'string'.
Abstract and concrete classes work similarly to the interfaces:
abstract class MyAbstractRepository {
findByName(name: string): string;
}
const mockedRepository = td.object<MyAbstractRepository>();
td.when(mockedRepository.findByName("Alice")).thenReturn("Alice Alicy");For classes:
class MyRepository implements IUserRepository {
findByName(name: string): string {
return "";
}
}
const mockedRepository = td.object<MyRepository>();
td.when(mockedRepository.findByName("Alice")).thenReturn("Alice Alicy");td.replace() and td.replaceEsm() work with TypeScript loaders like
tsx, @swc-node/register,
and ts-node.
On Node.js v20.6.0 or higher, testdouble.js registers its own loader automatically,
alongside whichever loader runs your TypeScript, so you don't need --loader=testdouble.
Which function you use depends on whether your TypeScript runs as ES modules or as
CommonJS, not on whether your source uses import syntax. Most TypeScript loaders
follow the same rules Node.js does:
.tsfiles run as ES modules only if the nearestpackage.jsonhas"type": "module". Otherwise, they're compiled to CommonJS, and theirimportstatements becomerequire()calls..mtsfiles always run as ES modules, and.ctsfiles always run as CommonJS.
If your code runs as ES modules, use await td.replaceEsm() and then await import()
your subject. If it runs as CommonJS, use td.replace() and then require() your
subject. Using td.replaceEsm() on code that's been compiled to CommonJS fails
silently: the subject still gets the real module.
When you call td.replaceEsm(), pass the path to the file that actually exists on
disk, including its .ts extension, even if your source imports it as ./other.js.
Using the .js path won't replace anything, and you won't get an error.
// src/main.ts
import { toBeMocked } from './other.js'
// test/main.test.ts
const toBeMocked = td.func<() => string>()
await td.replaceEsm('../src/other.ts', { toBeMocked })
const { main } = await import('../src/main.js')