xhr-mock
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, jQuery, Superagent
and probably every other library built on XMLHttpRequest
. Standard compliant (http://xhr.spec.whatwg.org/).
Documentation
Using a bundler
If you are using a bundler like Webpack or Browserify then install xhr-mock
using yarn
or npm
:
yarn add --dev xhr-mock
Now import xhr-mock
and start using it in your scripts:
import mock from 'xhr-mock';
Without a bundler
If you aren't using a bundler like Webpack or Browserify then add this script to your HTML:
<script src="https://unpkg.com/xhr-mock/dist/xhr-mock.js"></script>
Now you can start using the global, XHRMock
, in your scripts.
First off lets write some code that uses XMLHttpRequest
...
./createUser.js
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
import mock from 'xhr-mock';
import createUser from './createUser';
describe('createUser()', () => {
beforeEach(() => mock.setup());
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.');
}
});
});
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.
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.
Set a request header.
Get a request header.
Get the request headers.
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.
Set a response header.
Get a response header.
Get the response headers.
Set the response headers.
.body() : string
Get the response body.
.body(body : string)
Set the response body.
Simulate progress
Upload progress
Set the Content-Length
header and send a body. xhr-mock
will emit ProgressEvent
s.
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.
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.
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.
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.
import mock, {proxy} from 'xhr-mock';
mock.setup();
mock.post('/', {status: 204});
mock.use(proxy);
const xhr1 = new XMLHttpRequest();
xhr1.open('POST', '/');
xhr1.send();
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.
import mock, {delay} from 'xhr-mock';
mock.setup();
mock.post('/', delay({status: 201}, 3000));
Once off requests
Requests can be made on one off occasions using our handy once
utility.
import mock, {once} from 'xhr-mock';
mock.setup();
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.
import mock, {sequence} from 'xhr-mock';
mock.setup();
mock.post('/', sequence([
{status: 200},
{status: 500}
]
));
License
MIT Licensed. Copyright (c) James Newell 2014.