# expressmocks

> A small tool to support unit testing of express request handlers

Latest version **2.1.0** (published 2025-07-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install expressmocks
pnpm add expressmocks
yarn add expressmocks
bun add expressmocks
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2025-07-22 |
| First published | 2018-08-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 36.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Carsten Rohrbach |
| Maintainers | robaca |
| Keywords | nodejs, express, sinon, mock, mocha |

## Links

- npm: https://www.npmjs.com/package/expressmocks
- Repository: https://github.com/metro-nom/node-expressmocks
- Homepage: https://github.com/metro-nom/node-expressmocks#readme
- Issues: https://github.com/metro-nom/node-expressmocks/issues
- npm.io page: https://npm.io/package/expressmocks

## Alternatives

- [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads
- [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads
- [@anil-labs/factory](https://npm.io/package/@anil-labs/factory.md) — 0 weekly downloads
- [@massiv-oss/grpc-fake-server](https://npm.io/package/@massiv-oss/grpc-fake-server.md) — 0 weekly downloads
- [@buoy-gg/location](https://npm.io/package/@buoy-gg/location.md) — 0 weekly downloads

## Recent versions

- 2.1.0 (latest) — 2025-07-22
- 2.0.0 — 2022-12-07
- 1.0.0 — 2021-12-20
- 0.3.1 — 2020-07-27
- 0.3.0 — 2020-07-27
- 0.2.3 — 2020-07-21
- 0.2.2 — 2020-06-15
- 0.2.1 — 2020-06-09
- 0.2.0 — 2020-06-09
- 0.1.3 — 2018-12-12
- 0.1.2 — 2018-12-12
- 0.1.1 — 2018-12-12
- 0.1.0 — 2018-11-20
- 0.0.2 — 2018-08-11
- 0.0.1 — 2018-08-10

## README

# expressmocks

A small utility to write unit tests for [Express](https://expressjs.com) request handlers in a more readable and shorter fashion, based on [Sinon.JS](https://sinonjs.org/) and promises.

While this libary is written with Mocha, Sinon and Chai in mind, it should also work with other testing frameworks.

It's written in TypeScript and provides declaration files, but should also work with Babel or plain ES6+.

## Installation

Prerequisites:
```
npm install -D sinon
```

To install:
```
npm install -D expressmocks
```

## Usage examples

Let's say you have the following `SampleEndpoints` implementation:
```typescript
import { RequestHandler } from 'express'

const helloWorld: RequestHandler = (req, res, next) => {
    const { name } = req.params

    if (name === 'Carsten') {
        res.status(200).send(`Hello ${name}`)
    } else if (name) {
        res.status(404).send()
    } else {
        next(new Error('validation failed'))
    }
}
```

Some simple tests look like this:
```typescript
import { ExpressMocks } from 'expressmocks'
import { helloWorld } from './SampleEndpoints'

describe('helloWorld', () => {
    it('should say hello to Carsten', () => {
        return ExpressMocks.create({ params: { name: 'Carsten' } }).test(helloWorld)
            .expectStatus(200)
            .expectSend('Hello Carsten')
    })

    it('should return with 404 for others', () => {
        return ExpressMocks.create({ params: { name: 'Simon' } }).test(helloWorld)
            .expectStatus(404)
            .expectSend()
    })

    it('should fail via next() on validation error', () => {
        return ExpressMocks.create().test(helloWorld)
            .expectNext(Error, 'validation failed')
    })
})
```

`ExpressMocks` creates stubs for the `request`, `response` and `next` parameters and provides a simple API to test against the most often used method calls.

The functions of the request and response objects are [SinonJS stubs](https://sinonjs.org/releases/latest/stubs/), which can be checked via regular Sinon API. 
You may also add your own custom stubs if you are using some more esoteric functionality:

```typescript
    it('should allow testing on missing `cork()` method', () => {
        return ExpressMocks.create({}, { cork: sinon.stub() })
            .test((req, res, next) => {
                res.cork()
                // ...
            })
            .expectEnd()
            .then(({ res }) => {
                // using chai & sinon-chai
                expect(res.writeHead).to.have.been.called
                expect(res.cork).to.have.been.called
            })
    })
```

For more examples, please see the [sample project](./test/cjs-sample) and the [ExpressMocksSpec](./src/ExpressMocksSpec.ts)

## Build yourself

Checkout the project and run...
 
```bash
npm install
npm run build
```

---
_Source: https://npm.io/package/expressmocks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._