Jest and Typescript: Mocking Overload Signatures

Eric Egli — Sun, 26 Dec 2021 16:09:12 +0000

Type-safe tests are a blessing but come with a price: Correctly mocking modules and functions can be cumbersome and becomes even more complicated when a function has multiple overload signatures.

A quick recap on overloads by the TypeScript Handbook:

Some JavaScript functions can be called in a variety of argument counts and types. For example, you might write a function to produce a Date that takes either a timestamp (one argument) or a month/day/year specification (three arguments).

When there are more than two "descriptions" of a function, they are called overload signatures.

function makeDate(timestamp: number): Date;
function makeDate(m: number, d: number, y: number): Date;

Sometimes when we mock functions, we need to force TypeScript to use the correct overload signature because the compiler does not know which signature we want to mock. In many cases I had experienced, it would simply try to enforce the first signature.

A Google Drive example

The following example is taken from a more extensive project and simplified. The link to the repo with more examples can be found at the end of the article.

Our example function below makes a request to the Google Drive API and return a list of folders for a given user.

First, there is some setup for the Google Drive client.

// src/services/google.ts
import { auth, drive } from '@googleapis/drive';
import config from '../config';

const oAuth2Client = new auth.OAuth2(
  config.GOOGLE.client_id,
  config.GOOGLE.client_secret
);

oAuth2Client.setCredentials({ refresh_token: config.GOOGLE.refresh_token });

export const googleDrive = drive({ version: 'v3', auth: oAuth2Client });

The client is used somewhere in our app to make a request. This is what we want to test.

// src/routes/getFolders
async function getFolders(){
  const folders = await googleDrive.files.list({
    pageSize: 10,
    fields: 'files(id, name)',
    q: "mimeType = 'application/vnd.google-apps.folder'",
  });
  return folders
}

For unit tests, we want to mock googleDrive.files.list and return a custom response in order not to hit the actual API.

Let's look at the type definition file for the googleDrive.files class:

class Resource$Drives {
  // ...
  list(
    params: Params$Resource$Files$List,
    options: StreamMethodOptions
  ): GaxiosPromise<Readable>;
  list(
    params?: Params$Resource$Files$List,
    options?: MethodOptions
  ): GaxiosPromise<Schema$FileList>;
  list(
    params: Params$Resource$Files$List,
    options: StreamMethodOptions | BodyResponseCallback<Readable>,
    callback: BodyResponseCallback<Readable>
  ): void;
  list(
    params: Params$Resource$Files$List,
    options: MethodOptions | BodyResponseCallback<Schema$FileList>,
    callback: BodyResponseCallback<Schema$FileList>
  ): void;
  list(
    params: Params$Resource$Files$List,
    callback: BodyResponseCallback<Schema$FileList>
  ): void;
  list(callback: BodyResponseCallback<Schema$FileList>): void;
  //...
}

Woah. Six overload signatures.

Some expect a callback and return nothing, some return a Promise, some return a Stream.

When we write the implementation, we can choose any signature to stick to and TypeScript will not complain. But for unit tests, we usually need to mock a very specific signature.

Enforcing type safety

We know that our implementation above in getFolders returns a Promise. To be precise, the second signature is the one we want:

  list(
    params?: Params$Resource$Files$List,
    options?: MethodOptions
  ): GaxiosPromise<Schema$FileList>;

A way to write a spy for the Google functionality would be the following:

import { drive_v3,
  GaxiosPromise,
  MethodOptions } from '@googleapis/drive';

// Mock the module that exports the googleDrive client:
jest.mock('../src/services/google');

// Typing our spy according to the signature that we use
type DriveListSpy = (
  params?: drive_v3.Params$Resource$Files$List,
  options?: MethodOptions
) => GaxiosPromise<drive_v3.Schema$FileList>;

// Setting the right method overloads manually
const driveListSpy = jest.spyOn(
  googleDrive.files,
  'list'
) as unknown as jest.MockedFunction<DriveListSpy>;

Note how the DriveListSpy type is more or less copy-paste from the type definition file provided by the library. It may take some time to figure out from where you can import the types. Here, the MethodOptions interface is a direct named export, the params and Promise result type are part of the drive_v3 export.

Now we have complete type safety!
Let's provide a custom response with:

driveListSpy.mockResolvedValue({
  config: {},
  data: { files: [{ name: 'folder', id: 'id' }] },
  status: 200,
  statusText: 'OK',
  headers: {},
  request: { responseURL: 'test' },
});

Example test case:

  it('lists folders', async () => {
    await getFolders();
    expect(driveListSpy).toHaveBeenCalledTimes(1);
    expect(driveListSpy.mock.calls[0][0]).toMatchSnapshot();
  });

If we forget or misspell a property, e.g. type "Name" instead of "name", TypeScript will complain:

Now we can provide any sort of mock implementation that adheres to our Promise-based signature, e.g. resolve different values for different tests (with mockResolvedValueOnce).

Final notes

Setting overload signatures manually is generally not nice because we are re-writing (or copy-pasting) implementation details of a third-party library. Upgrading the Google Drive dependency may result in different signatures.
Also, as unknown as <type> assertions are error-prone since we tell the compiler not to infer types and instead use our custom type.

Nevertheless, setting overload signatures manually is sometimes the only way out. Take your time to setup your spies and enjoy the benefit of rock-solid test.

Happy mocking!

Thanks for sticking through - here's a full example: https://github.com/eegli/spotify-history/blob/main/test/backup.test.ts

Quick Guide to Python Formatting in VS Code (2025)

Eric Egli — Thu, 22 Oct 2020 15:46:11 +0000

Edit: Things have changed, see the 2025 update at the bottom of this post.

You've followed Microsoft's tutorial on setting up Python in VS Code but formatting is just not working? It might be that other extensions are interfering with your Python formatter.

If you use VS Code mostly for web development, you most likely also use Prettier for formatting. I'm talking about Prettier as an extension, not as a package. Check if you have the following configuration in your settings:

(Open VS Code, hit Ctrl + Shift + P on Windows / Cmd + Shift + P on MacOS to open the Command Palette and search for "Settings", check both "Workspace" and "User" settings).

Prettier does not work with Python

"editor.defaultFormatter": "esbenp.prettier-vscode"

If you find this config in your settings, you've found the reason why autopep8, black or yapf are not working - The above configuration will choose Prettier to format Python, which is not supported. In your settings, make sure you override the default formatter for python like so:

  "[python]": {
    "editor.defaultFormatter": null
  }

And don't forget to install and select the actual formatter that you want (just like in the official docs).

  "python.formatting.provider": "black",
  "python.formatting.blackArgs": ["--line-length", "120"]

Override default formatter

You can either overwrite editor.defaultFormatter just for your workspace or globally for your user. Also, it doesn't matter whether you're using a global Python installation or a virtual environment.

I prefer applying this configuration to my user settings - this way, I can easily start a Python project and will get formatting out of the box based on my user settings. No need to create dedicated workspace settings for every single project and override the formatter over and over. Here's the relevant config from my settings:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[python]": {
    "editor.defaultFormatter": null
  },
  "python.formatting.blackArgs": ["--line-length", "120"],
  "python.formatting.provider": "black",
}

2025 Update

It's been 5 years since this was originally posted. Long story short: Use Astral's ruff - it's a billion times better and supports Jupyter notebooks out of the box. Just search for the extension in the VSCode Extension Marketplace and add/overwrite the following entry in your ´settings.json´:

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}

Preview picture by @fidpad on unsplash.

DEV Community: Eric Egli