Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mock
✓ import mock from 'xhr-mock';
✗ import { mock } from 'xhr-mock';
This is the primary way to import the mocking utility in modern JavaScript environments using bundlers (ESM).
mock
✓ const mock = require('xhr-mock');
✗ const mock = require('xhr-mock').default;
Used for CommonJS environments, typically in Node.js or older browser tooling. `require('xhr-mock')` directly provides the default export.
XHRMock (global)
✓ const mock = XHRMock;
✗ import mock from 'xhr-mock';
When `xhr-mock` is loaded directly via a `<script>` tag in the browser (e.g., from a CDN), the utility is exposed globally as `XHRMock`. Importing via `import` or `require` will not work in this scenario.
This quickstart demonstrates how to set up `xhr-mock` to intercept and respond to XMLHttpRequest calls for both GET and POST requests. It includes `beforeEach` and `afterEach` hooks to ensure proper test isolation by setting up and tearing down the mock for each simulated test case.
import mock from 'xhr-mock';
// This function simulates application code that uses XMLHttpRequest.
// It will use the real XMLHttpRequest unless xhr-mock intercepts it.
async function fetchData(url: string, method: string = 'GET', body?: object): Promise<any> {
return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest();
xhr.onload = () => {
if (xhr.status >= 200 && xhr.status < 300) {
try {
resolve(JSON.parse(xhr.responseText));
} catch (e) {
resolve(xhr.responseText);
}
} else {
reject(new Error(`Request failed with status ${xhr.status}: ${xhr.statusText}`));
}
};
xhr.onerror = () => {
reject(new Error('Network error or request aborted.'));
};
xhr.open(method, url);
if (body) {
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.send(JSON.stringify(body));
} else {
xhr.send();
}
});
}
// Simulate a basic test runner environment for demonstration
const describe = (name: string, fn: () => void) => {
console.log(`\nDescribe: ${name}`);
fn();
};
const it = async (name: string, fn: () => Promise<void>) => {
console.log(` It: ${name}`);
try {
await fn();
console.log(` ✅ Passed: ${name}`);
} catch (e: any) {
console.error(` ❌ Failed: ${name} - ${e.message}`);
}
};
const beforeEach = (fn: () => void) => {
globalThis.beforeEachCallbacks.push(fn);
};
const afterEach = (fn: () => void) => {
globalThis.afterEachCallbacks.push(fn);
};
const expect = (value: any) => ({
toBe: (expected: any) => {
if (value !== expected) throw new Error(`Expected ${expected}, got ${value}`);
},
toEqual: (expected: any) => {
if (JSON.stringify(value) !== JSON.stringify(expected)) {
throw new Error(`Expected deep equality ${JSON.stringify(expected)}, got ${JSON.stringify(value)}`);
}
}
});
globalThis.beforeEachCallbacks = [];
globalThis.afterEachCallbacks = [];
async function runAllTests() {
for (const beforeEachCb of globalThis.beforeEachCallbacks) {
beforeEachCb();
}
// In a real test runner, 'it' blocks would be collected and run here
}
describe('xhr-mock usage', () => {
beforeEach(() => mock.setup());
afterEach(() => mock.teardown());
it('should mock a GET request successfully', async () => {
mock.get('/api/data', (req, res) => {
return res.status(200).body(JSON.stringify({ message: 'Mocked GET data' }));
});
const result = await fetchData('/api/data');
expect(result).toEqual({ message: 'Mocked GET data' });
});
it('should mock a POST request with specific body', async () => {
let receivedBody: object | undefined;
mock.post('/api/users', (req, res) => {
receivedBody = JSON.parse(req.body() || '{}');
return res.status(201).body(JSON.stringify({ id: 'user-123', ...receivedBody }));
});
const userData = { name: 'Alice' };
const result = await fetchData('/api/users', 'POST', userData);
expect(receivedBody).toEqual(userData);
expect(result).toEqual({ id: 'user-123', name: 'Alice' });
});
it('should handle network error (mocked)', async () => {
mock.get('/api/error', (req, res) => {
return res.status(500).body('Internal Server Error');
});
try {
await fetchData('/api/error');
throw new Error('Expected request to fail, but it succeeded.');
} catch (e: any) {
expect(e.message).toBe('Request failed with status 500: Internal Server Error');
}
});
});
runAllTests();
Errors
Common errors & fixes
ReferenceError: XMLHttpRequest is not defined
This error typically occurs when running XMLHttpRequest-dependent code in a Node.js environment that lacks a global `XMLHttpRequest` object, and `xhr-mock.setup()` has not been called or is unable to correctly initialize its mock.
fixEnsure your test environment (e.g., Jest) uses a browser-like environment like `jsdom` (`testEnvironment: 'jsdom'`). Also, verify that `mock.setup()` is called before any code that interacts with `XMLHttpRequest`.
Error: Mocks not cleared between tests.
This is a descriptive error or observed behavior indicating that a mock set up in one test is affecting subsequent tests, leading to inconsistent results.
fixImplement `afterEach(() => mock.teardown());` in your test suite to ensure that all mock configurations are reset to their original state after each test runs, preventing leakage.
TypeError: Cannot read properties of undefined (reading 'body')
This usually happens when attempting to access methods like `req.body()` or `res.body()` on a request or response object that is `undefined` or has an unexpected structure within your mock handler, or when the HTTP method doesn't typically carry a body (e.g., GET requests).
fixCarefully inspect your mock handler function (`(req, res) => { ... }`) to ensure `req` and `res` objects are properly handled and their methods are called correctly. Verify the request being mocked matches the expected method and body type. Ensure your mock response object has the correct properties. Audit
Dependencies
No dependency data recorded yet.