This jest extension module provides an ad-hoc SMTP server, as well as custom jest matchers, in order to test email sendings. This is meant to use in end-to-end webserver tests.

It leverages Nodemailer's smtp-server and mailparser modules.

npm i -D jest-smtp

In the jest section of your package.json file:

"jest": {
    ...,
    "setupFilesAfterEnv": [
      "jest-smtp",
      "<rootDir>/tests/jest-setup.ts"
      ...
    ],
}

You can add jest-smtp globally to your jest-setup file.

import { createJestSMTPServer } from 'jest-smtp';


beforeAll(() => {
    global.smtpServer = createJestSMTPServer();
});

afterAll(() => {
    global.smtpServer.close();
});

beforeEach(() => {
    global.smtpServer.resetMails();
});

If you use typescript you should add this declaration in your jest.d.ts file:

declare namespace NodeJS {
  export interface Global {
    smtpServer: import('jest-smtp').JestSMTPServer;
  }
}

import { createJestSMTPServer } from 'jest-smtp';

describe('test my server', () => {
    const smtpServer = createJestSMTPServer();

    afterAll(() => {
        smtpServer.close();
    });

    beforeEach(() => {
        smtpServer.resetMails();
    });
})

jest-smtp provides custom matchers

This tests the number of mails received by the server.

expect(smtpServer).toHaveReceivedEmails(1);

This tests if an email matching the provided fields was sent. This is useful so you don't have to provide an exact match but only test the relevant fields.

The fields are structured by mailparser, you can find the reference here: https://nodemailer.com/extras/mailparser/#mail-object

Be especially aware that the to, from, cc etc... fields are structured as objects, not strings.

expect(smtpServer).toHaveReceivedEmailMatching({
    subject: 'My e-mail subject',
    from: {
        name: 'Don\'t reply',
        address: '[email protected]'
    }
});

jest-smtp only exports one function :

const { emails, server, close, resetMails } = createJestSMTPServer({
    port: 465,
    host: undefined,
    options: ()
})

port: the port the server will be listening on. Default is 465.

host: the host the server will be listening on (pretty unuseful is you ask me)

options: these options will be passed to the smtp-server instance constructor. See here for reference: https://nodemailer.com/extras/smtp-server/#usage

The default options provided are :

{
  authMethods: ["PLAIN", "LOGIN"],
  authOptional: true,
  onData: ... // if you override this function it will break the main features of the plugin
};

• resetEmails

convenience method to reset the list of received emails between the tests.

• close

shortcut to server.close method. This must be called after all tests or jest will timeout.

• emails

The list of ParsedMail objects received. You can access it to do extra tests on the content of the emails.

• server

The smtp-server instance.