{"id":12857,"library":"axios-test-instance","title":"Axios Test Instance","description":"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.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/remcohaszing/axios-test-instance","tags":["javascript","axios","express","fastify","http","jest","koa","test","testing","typescript"],"install":[{"cmd":"npm install axios-test-instance","lang":"bash","label":"npm"},{"cmd":"yarn add axios-test-instance","lang":"bash","label":"yarn"},{"cmd":"pnpm add axios-test-instance","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This library internally uses and returns instances of Axios. It's a fundamental runtime dependency, even if not explicitly listed as a peer dependency.","package":"axios","optional":false}],"imports":[{"note":"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.","wrong":"const { request } = require('axios-test-instance');","symbol":"request","correct":"import { request } from 'axios-test-instance';"},{"note":"`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.","wrong":"const { setTestApp } = require('axios-test-instance');","symbol":"setTestApp","correct":"import { setTestApp } from 'axios-test-instance';"},{"note":"`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.","wrong":"const { createInstance } = require('axios-test-instance');","symbol":"createInstance","correct":"import { createInstance } from 'axios-test-instance';"},{"note":"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.","symbol":"AxiosTestInstance","correct":"import type { AxiosTestInstance } from 'axios-test-instance';"}],"quickstart":{"code":"import { createInstance, AxiosTestInstance } from 'axios-test-instance';\nimport express from 'express';\n\n// 1. Set up a simple Express application for testing\nconst app = express();\napp.use(express.json()); // Middleware to parse JSON bodies\n\napp.get('/', (req, res) => {\n  res.status(200).send('Hello from test app!');\n});\n\napp.post('/submit', (req, res) => {\n  if (req.body && req.body.message) {\n    return res.status(200).json({ received: req.body.message });\n  }\n  res.status(400).send('Bad Request');\n});\n\n// 2. Declare a variable to hold the test instance\nlet instance: AxiosTestInstance;\n\ndescribe('Axios Test Instance Integration', () => {\n  // 3. Create the test instance before all tests\n  beforeAll(async () => {\n    instance = await createInstance(app);\n  });\n\n  // 4. Close the test instance after all tests\n  afterAll(async () => {\n    await instance.close();\n  });\n\n  // 5. Write tests using the instance like a regular Axios client\n  test('should handle GET requests correctly', async () => {\n    const response = await instance.get('/');\n    expect(response.status).toBe(200);\n    expect(response.data).toBe('Hello from test app!');\n  });\n\n  test('should handle POST requests with JSON body', async () => {\n    const testPayload = { message: 'Greetings!' };\n    const response = await instance.post('/submit', testPayload);\n    expect(response.status).toBe(200);\n    expect(response.data).toEqual({ received: 'Greetings!' });\n  });\n\n  test('should return 400 for invalid POST payload', async () => {\n    const response = await instance.post('/submit', {});\n    expect(response.status).toBe(400);\n    expect(response.data).toBe('Bad Request');\n  });\n});","lang":"typescript","description":"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)."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 16 or later.","message":"Node.js 14 is no longer supported. Applications must run on Node.js 16 or newer.","severity":"breaking","affected_versions":">=8.0.0"},{"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`.","message":"Explicit 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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Ensure your project's Axios dependency is compatible with Axios 1.x, or upgrade Axios in your project.","message":"The library was updated to Axios 1.x. If your project uses an older version of Axios, this might introduce compatibility issues.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Migrate your test files to use ES Module `import` syntax. If your project is CommonJS, consider transpiling or using dynamic `import()`.","message":"CommonJS `require()` is no longer officially supported, as the package now uses the `exports` field in `package.json`, making it an ESM-first module.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"Test instances created with `createInstance` or `setTestApp` will no longer follow HTTP redirects by default.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js runtime to version 14 or later for `v6.x` and `v7.x`, or Node.js 16+ for `v8.x`.","message":"Support for Node.js 12 was dropped.","severity":"breaking","affected_versions":">=6.0.0 <8.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` to import `axios-test-instance` in a CommonJS environment, which is an ES Module since v7.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported."},{"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.","cause":"The Axios instance (`request` or one created by `createInstance`/`patchInstance`) is being used before it has been properly initialized or awaited.","error":"TypeError: Cannot read properties of undefined (reading 'get') (or similar for other Axios methods)"},{"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 });`.","cause":"An HTTP request resulted in a redirect, but the `axios-test-instance` is configured to not follow redirects by default since v4.0.0.","error":"AxiosError: Request failed with status code 302"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}