# xhr-mock

> Utility for mocking XMLHttpRequest.

Latest version **2.5.1** (published 2019-11-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install xhr-mock
pnpm add xhr-mock
yarn add xhr-mock
bun add xhr-mock
```

## Health

**Score 25/100 (F)** — status: abandoned.

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

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.5.1 |
| Published | 2019-11-08 |
| First published | 2015-08-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 174.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 198 |
| Maintainers | jameslnewell |
| Keywords | mock, xhr, test, fake, request, ajax, browser, xmlhttprequest, jquery, superagent, axios |

## Links

- npm: https://www.npmjs.com/package/xhr-mock
- Repository: https://github.com/jameslnewell/xhr-mock
- npm.io page: https://npm.io/package/xhr-mock

## Dependencies (2)

- [url](https://npm.io/package/url.md) ^0.11.0
- [global](https://npm.io/package/global.md) ^4.3.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 2.5.1 (latest) — 2019-11-08
- 2.0.0-preview.15 (next) — 2018-01-10
- 2.5.0 — 2019-07-17
- 2.4.1 — 2018-07-11
- 2.4.1-preview.1 — 2018-06-14
- 2.4.0 — 2018-05-29
- 2.3.2 — 2018-05-01
- 2.3.1 — 2018-03-28
- 2.3.0 — 2018-03-19
- 2.2.0 — 2018-02-20
- 2.1.0 — 2018-02-14
- 2.0.3 — 2018-01-12
- 2.0.2 — 2018-01-10
- 2.0.1 — 2018-01-10
- 2.0.0 — 2018-01-10
- … 26 more at https://npm.io/package/xhr-mock/versions

## README

# xhr-mock

[![npm (tag)](https://img.shields.io/npm/v/xhr-mock.svg)]()
[![Build Status](https://travis-ci.org/jameslnewell/xhr-mock.svg?branch=master)](https://travis-ci.org/jameslnewell/xhr-mock)
[![npm](https://img.shields.io/npm/dm/localeval.svg)]()

Utility for mocking `XMLHttpRequest`.

Great for testing. Great for prototyping while your backend is still being built.

Works in NodeJS and in the browser. Is compatible with [Axios](https://www.npmjs.com/package/axios), [jQuery](https://www.npmjs.com/package/jquery), [Superagent](https://www.npmjs.com/package/superagent)
and probably every other library built on `XMLHttpRequest`. Standard compliant ([http://xhr.spec.whatwg.org/](http://xhr.spec.whatwg.org/)).

###### Documentation

* [Installation](#installation)
* [Usage](#usage)
* [API](#api)
* [How to?](#how-to)

## <a name="installation">Installation</a>

### Using a bundler

If you are using a bundler like [Webpack](https://www.npmjs.com/package/webpack) or [Browserify](https://www.npmjs.com/package/browserify) then install `xhr-mock` using `yarn` or `npm`:

```bash
yarn add --dev xhr-mock
```

Now import `xhr-mock` and start using it in your scripts:

```js
import mock from 'xhr-mock';
```

### Without a bundler

If you aren't using a bundler like [Webpack](https://www.npmjs.com/package/webpack) or [Browserify](https://www.npmjs.com/package/browserify) then add this script to your HTML:

```html
<script src="https://unpkg.com/xhr-mock/dist/xhr-mock.js"></script>
```

Now you can start using the global, `XHRMock`, in your scripts.

## <a name="usage">Usage</a>

First off lets write some code that uses `XMLHttpRequest`...

`./createUser.js`

```js
// we could have just as easily use Axios, jQuery, Superagent
// or another package here instead of using the native XMLHttpRequest object

export default function(data) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.onreadystatechange = () => {
      if (xhr.readyState == XMLHttpRequest.DONE) {
        if (xhr.status === 201) {
          try {
            resolve(JSON.parse(xhr.responseText).data);
          } catch (error) {
            reject(error);
          }
        } else if (xhr.status) {
          try {
            reject(JSON.parse(xhr.responseText).error);
          } catch (error) {
            reject(error);
          }
        } else {
          reject(new Error('An error ocurred whilst sending the request.'));
        }
      }
    };
    xhr.open('post', '/api/user');
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.send(JSON.stringify({data: data}));
  });
}
```

Now lets test the code we've written...

`./createUser.test.js`

```js
import mock from 'xhr-mock';
import createUser from './createUser';

describe('createUser()', () => {
  // replace the real XHR object with the mock XHR object before each test
  beforeEach(() => mock.setup());

  // put the real XHR object back and clear the mocks after each test
  afterEach(() => mock.teardown());

  it('should send the data as JSON', async () => {
    expect.assertions(2);

    mock.post('/api/user', (req, res) => {
      expect(req.header('Content-Type')).toEqual('application/json');
      expect(req.body()).toEqual('{"data":{"name":"John"}}');
      return res.status(201).body('{"data":{"id":"abc-123"}}');
    });

    await createUser({name: 'John'});
  });

  it('should resolve with some data when status=201', async () => {
    expect.assertions(1);

    mock.post('/api/user', {
      status: 201,
      reason: 'Created',
      body: '{"data":{"id":"abc-123"}}'
    });

    const user = await createUser({name: 'John'});

    expect(user).toEqual({id: 'abc-123'});
  });

  it('should reject with an error when status=400', async () => {
    expect.assertions(1);

    mock.post('/api/user', {
      status: 400,
      reason: 'Bad request',
      body: '{"error":"A user named \\"John\\" already exists."}'
    });

    try {
      const user = await createUser({name: 'John'});
    } catch (error) {
      expect(error).toMatch('A user named "John" already exists.');
    }
  });
});
```

## <a name="api">API</a>

### xhr-mock

#### .setup()

Replace the global `XMLHttpRequest` object with the `MockXMLHttpRequest`.

#### .teardown()

Restore the global `XMLHttpRequest` object to its original state.

#### .reset()

Forget all the request handlers.

#### .get(url | regex, mock)

Register a factory function to create mock responses for each GET request to a specific URL.

```js
mock.get(/\.*.json$/, {
  body: JSON.stringify({ data: { id: "abc" } })
});
```

#### .post(url | regex, mock)

Register a factory function to create mock responses for each POST request to a specific URL.

#### .put(url | regex, mock)

Register a factory function to create mock responses for each PUT request to a specific URL.

#### .patch(url | regex, mock)

Register a factory function to create mock responses for each PATCH request to a specific URL.

#### .delete(url | regex, mock)

Register a factory function to create mock responses for each DELETE request to a specific URL.

#### .use(method, url | regex, mock)

Register a factory function to create mock responses for each request to a specific URL.

#### .use(fn)

Register a factory function to create mock responses for every request.

#### .error(fn)

Log errors thrown by handlers.

### MockXMLHttpRequest

### MockRequest

#### .method() : string

Get the request method.

#### .url() : MockURL

Get the request URL.

#### .header(name : string, value: string)

Set a request header.

#### .header(name : string) : string | null

Get a request header.

#### .headers() : object

Get the request headers.

#### .headers(headers : object)

Set the request headers.

#### .body() : string

Get the request body.

#### .body(body : string)

Set the request body.

### MockResponse

#### .status() : number

Get the response status.

#### .status(code : number)

Set the response status.

#### .reason() : string

Get the response reason.

#### .reason(phrase : string)

Set the response reason.

#### .header(name : string, value: string)

Set a response header.

#### .header(name : string) : string | null

Get a response header.

#### .headers() : object

Get the response headers.

#### .headers(headers : object)

Set the response headers.

#### .body() : string

Get the response body.

#### .body(body : string)

Set the response body.

## <a name="how-to">How to?</a>

### Simulate progress

#### Upload progress

Set the `Content-Length` header and send a body. `xhr-mock` will emit `ProgressEvent`s.

```js
import mock from 'xhr-mock';

mock.setup();

mock.post('/', {});

const xhr = new XMLHttpRequest();
xhr.upload.onprogress = event => console.log(event.loaded, event.total);
xhr.open('POST', '/');
xhr.setRequestHeader('Content-Length', '12');
xhr.send('Hello World!');
```

#### Download progress

Set the `Content-Length` header and send a body. `xhr-mock` will emit `ProgressEvent`s.

```js
import mock from 'xhr-mock';

mock.setup();

mock.get('/', {
  headers: {'Content-Length': '12'},
  body: 'Hello World!'
});

const xhr = new XMLHttpRequest();
xhr.onprogress = event => console.log(event.loaded, event.total);
xhr.open('GET', '/');
xhr.send();
```

### Simulate a timeout

Return a `Promise` that never resolves or rejects.

```js
import mock from 'xhr-mock';

mock.setup();

mock.get('/', () => new Promise(() => {}));

const xhr = new XMLHttpRequest();
xhr.timeout = 100;
xhr.ontimeout = event => console.log('timeout');
xhr.open('GET', '/');
xhr.send();
```

> A number of major libraries don't use the `timeout` event and use `setTimeout()` instead. Therefore, in order to mock timeouts in major libraries, we have to wait for the specified amount of time anyway.

### Simulate an error

Return a `Promise` that rejects. If you want to test a particular error you an use one of the pre-defined error classes.

```js
import mock from 'xhr-mock';

mock.setup();

mock.get('/', () => Promise.reject(new Error()));

const xhr = new XMLHttpRequest();
xhr.onerror = event => console.log('error');
xhr.open('GET', '/');
xhr.send();
```

### Proxying requests

If you want to mock some requests, but not all of them, you can proxy unhandled requests to a real server.

```js
import mock, {proxy} from 'xhr-mock';

mock.setup();

// mock specific requests
mock.post('/', {status: 204});

// proxy unhandled requests to the real servers
mock.use(proxy);

// this request will receive a mocked response
const xhr1 = new XMLHttpRequest();
xhr1.open('POST', '/');
xhr1.send();

// this request will receieve the real response
const xhr2 = new XMLHttpRequest();
xhr2.open('GET', 'https://jsonplaceholder.typicode.com/users/1');
xhr2.send();
```

### Delaying requests

Requests can be delayed using our handy `delay` utility.

```js
import mock, {delay} from 'xhr-mock';

mock.setup();

// delay the request for three seconds
mock.post('/', delay({status: 201}, 3000));
```

### Once off requests

Requests can be made on one off occasions using our handy `once` utility.

```js
import mock, {once} from 'xhr-mock';

mock.setup();

// the response will only be returned the first time a request is made
mock.post('/', once({status: 201}));
```

### send a sequence of responses

In case you need to return a different response each time a request is made, you may use the `sequence` utility.

```js
import mock, {sequence} from 'xhr-mock';

mock.setup();

mock.post('/', sequence([
  {status: 200}, // the first request will receive a response with status 200
  {status: 500}  // the second request will receive a response with status 500
                 // if a third request is made, no response will be sent
  ]
));
```

## License

MIT Licensed. Copyright (c) James Newell 2014.

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