Registry / testing / axios-test-instance

axios-test-instance

JSON →
library8.0.0jsnpmunverified

Axios Test Instance is a Node.js library designed to simplify the testing of backend applications by enabling in-memory HTTP requests using the familiar Axios API. It allows developers to test Express, Koa, Fastify, or raw Node.js HTTP handlers without initiating actual network calls, significantly accelerating integration test suites. The current stable version is 8.0.0, and the package maintains a release cadence tied to major updates of its core dependency, Axios, and Node.js LTS release cycles. Its primary strength lies in providing a convenient abstraction over backend server testing, offering methods like `setTestApp` for Jest/Mocha-style global setup, `createInstance` for fine-grained control over test instances, and `patchInstance` to redirect requests from existing Axios configurations. This approach ensures robust testing while maintaining development velocity and adhering to modern JavaScript module standards.

npm install axios-test-instance
INSTALL
IMPORT
SIG · AXIOS-TEST-INSTANC
A
axios-test-instance
testingjavascriptv8.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

request
import { request } from 'axios-test-instance';
const { request } = require('axios-test-instance');
The `request` object is a pre-configured Axios instance accessible after calling `setTestApp`. CommonJS `require` is not supported since v7.0.0 due to `exports` field.
setTestApp
import { setTestApp } from 'axios-test-instance';
const { setTestApp } = require('axios-test-instance');
`setTestApp` is commonly used with Jest or Mocha's `beforeAll`/`beforeEach` to globally configure the test instance. CommonJS `require` is not supported since v7.0.0.
createInstance
import { createInstance } from 'axios-test-instance';
const { createInstance } = require('axios-test-instance');
`createInstance` allows for explicit management of an Axios test instance, useful for non-Jest environments or granular control. CommonJS `require` is not supported since v7.0.0.
AxiosTestInstance
import type { AxiosTestInstance } from 'axios-test-instance';
Type import for the instance returned by `createInstance` or `patchInstance`. The underlying `AxiosInstance` type comes from the `axios` package, but this library provides its own wrapper type for convenience.

This quickstart demonstrates how to set up an Express application, create an `axios-test-instance`, and use it to make in-memory HTTP requests within a test suite (e.g., Jest).

import { createInstance, AxiosTestInstance } from 'axios-test-instance'; import express from 'express'; // 1. Set up a simple Express application for testing const app = express(); app.use(express.json()); // Middleware to parse JSON bodies app.get('/', (req, res) => { res.status(200).send('Hello from test app!'); }); app.post('/submit', (req, res) => { if (req.body && req.body.message) { return res.status(200).json({ received: req.body.message }); } res.status(400).send('Bad Request'); }); // 2. Declare a variable to hold the test instance let instance: AxiosTestInstance; describe('Axios Test Instance Integration', () => { // 3. Create the test instance before all tests beforeAll(async () => { instance = await createInstance(app); }); // 4. Close the test instance after all tests afterAll(async () => { await instance.close(); }); // 5. Write tests using the instance like a regular Axios client test('should handle GET requests correctly', async () => { const response = await instance.get('/'); expect(response.status).toBe(200); expect(response.data).toBe('Hello from test app!'); }); test('should handle POST requests with JSON body', async () => { const testPayload = { message: 'Greetings!' }; const response = await instance.post('/submit', testPayload); expect(response.status).toBe(200); expect(response.data).toEqual({ received: 'Greetings!' }); }); test('should return 400 for invalid POST payload', async () => { const response = await instance.post('/submit', {}); expect(response.status).toBe(400); expect(response.data).toBe('Bad Request'); }); });
Debug
Known issues
breakingNode.js 14 is no longer supported. Applications must run on Node.js 16 or newer.
fix
Upgrade your Node.js runtime to version 16 or later.
affects: >=8.0.0
breakingExplicit support for the `form-data` package was removed. Axios's built-in `FormData` handling is now used by default. This might break tests that relied on explicit `form-data` usage patterns for multipart requests.
fix
Remove manual `form-data` construction if it was used explicitly with `axios-test-instance`. Rely on standard Axios `FormData` behavior or pass plain objects for `application/x-www-form-urlencoded`.
affects: >=8.0.0
breakingThe library was updated to Axios 1.x. If your project uses an older version of Axios, this might introduce compatibility issues.
fix
Ensure your project's Axios dependency is compatible with Axios 1.x, or upgrade Axios in your project.
affects: >=7.0.0
breakingCommonJS `require()` is no longer officially supported, as the package now uses the `exports` field in `package.json`, making it an ESM-first module.
fix
Migrate your test files to use ES Module `import` syntax. If your project is CommonJS, consider transpiling or using dynamic `import()`.
affects: >=7.0.0
breakingTest instances created with `createInstance` or `setTestApp` will no longer follow HTTP redirects by default.
fix
If your tests depend on redirects, explicitly configure Axios to follow them, e.g., by passing `maxRedirects: 5` in your Axios config object for requests.
affects: >=4.0.0
breakingSupport for Node.js 12 was dropped.
fix
Upgrade your Node.js runtime to version 14 or later for `v6.x` and `v7.x`, or Node.js 16+ for `v8.x`.
affects: >=6.0.0 <8.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported.
Attempting to use `require()` to import `axios-test-instance` in a CommonJS environment, which is an ES Module since v7.0.0.
fix
Convert your test files to ES Modules using `import` statements, or ensure your `package.json` has `"type": "module"` if using `.js` files with ESM in a hybrid project.
TypeError: Cannot read properties of undefined (reading 'get') (or similar for other Axios methods)
The Axios instance (`request` or one created by `createInstance`/`patchInstance`) is being used before it has been properly initialized or awaited.
fix
Ensure `setTestApp` or `createInstance` is properly `await`ed in an asynchronous setup hook (like `beforeAll` or `beforeEach`) before any tests attempt to use the Axios instance.
AxiosError: Request failed with status code 302
An HTTP request resulted in a redirect, but the `axios-test-instance` is configured to not follow redirects by default since v4.0.0.
fix
If you expect redirects, configure the Axios instance to follow them by setting `maxRedirects` in the request config, e.g., `await instance.get('/old-path', { maxRedirects: 5 });`.
Upgrade
Version history
8.0.0latest on npm
Audit
Dependencies
axiosrequiredThis library internally uses and returns instances of Axios. It's a fundamental runtime dependency, even if not explicitly listed as a peer dependency.
Agent activity
17 hits · last 30 days
node
16
OpenAI (training)
1
Resources