Fix Cannot Find Module Supertest Error

Encountering the error Cannot find module 'supertest' is a common issue for Node.js developers, especially when setting up API testing. This error stops your test suite from running and can be frustrating. This guide breaks down the causes and provides clear, step-by-step solutions to fix it quickly. We'll cover installation, version mismatches, and project structure issues.

What Causes This Error?

The error "Cannot find module 'supertest'" occurs when Node.js cannot locate the supertest package in your project's node_modules directory. This usually happens because the package is missing, improperly installed, or placed in the wrong location. Other causes include using a global install instead of a local one, or running tests from the wrong directory.

Before diving into fixes, ensure you have Node.js and npm installed. Run node -v and npm -v in your terminal to check. If they are missing, install them first.

Solution 1: Install Supertest Locally

The most common fix is to install supertest as a development dependency in your project. Open your terminal in the project root and run:

npm install --save-dev supertest

This command installs the package locally and adds it to your package.json under devDependencies. After installation, check if the error persists. If it does, move to the next solution.

If you are using yarn, run:

yarn add --dev supertest

Solution 2: Verify Package.json and node_modules

Sometimes, the installation might fail silently. Verify that supertest appears in your package.json file. Look for this entry:

"devDependencies": {
  "supertest": "^6.3.3"
}

Also, check if the node_modules folder contains the supertest directory. Navigate to node_modules/supertest and see if it exists. If not, delete the node_modules folder and package-lock.json (or yarn.lock), then reinstall all dependencies:

rm -rf node_modules package-lock.json
npm install

This clean reinstall often resolves missing module issues.

Solution 3: Check Your Test File Import

Ensure you are importing supertest correctly in your test file. Use the require function properly. Here's an example of a correct import:

// Correct import
const request = require('supertest');
const app = require('./app'); // Your Express app

describe('GET /', () => {
  it('responds with Hello World', async () => {
    const response = await request(app)
      .get('/')
      .expect(200);
    console.log(response.text); // Output: Hello World
  });
});

If you are using ES modules (import syntax), ensure your package.json has "type": "module" or use the .mjs extension. For CommonJS, stick with require.

Solution 4: Check Node.js and NPM Versions

Outdated Node.js or npm versions can cause module resolution issues. supertest requires Node.js version 10 or higher. Update to the latest LTS version:

npm install -g n
n lts

After updating, reinstall the package:

npm install --save-dev supertest

Solution 5: Use npx for Global Commands

Avoid installing supertest globally. If you need to run tests from anywhere, use npx to execute the local version. For example, if you are using Mocha:

npx mocha test/api.test.js

This command uses the local mocha and supertest from your project, preventing global conflicts.

Solution 6: Verify Project Structure

Make sure you run your test command from the project root directory. If you have a monorepo or nested project, navigate to the correct folder. For example:

cd /path/to/your/project
npm test

If your test file is in a subfolder, adjust the path in the import. For instance, if app.js is in the parent directory:

const request = require('supertest');
const app = require('../app'); // Adjust path

Solution 7: Rebuild Node Modules

Sometimes, corrupted node modules cause errors. Use npm rebuild to recompile native modules:

npm rebuild

Then test again. This is less common but can help if the error persists.

Example: Complete Test Setup

Here is a full example to test an Express API with supertest. First, create a simple Express app:

// app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World');
});

module.exports = app;

Then, create a test file:

// test/api.test.js
const request = require('supertest');
const app = require('../app');

describe('API Tests', () => {
  it('returns Hello World', async () => {
    const res = await request(app)
      .get('/')
      .expect(200);
    console.log('Status:', res.status); // Output: Status: 200
    console.log('Body:', res.text); // Output: Body: Hello World
  });
});

Run the test with Mocha:

npx mocha test/api.test.js

Expected output:

  API Tests
    ✓ returns Hello World

  1 passing (10ms)

If you encounter the error again, double-check your import and installation.

Troubleshooting Tips

If none of the above solutions work, try these additional steps:

• Clear npm cache: npm cache clean --force
• Check for typos in your import statement.
• Ensure you are not using an incompatible version of supertest with your Node.js version.
• Look at your package.json for conflicting dependencies.

For more general module issues, read our guide on Fix Node.js Error: Cannot find module for broader solutions.

Conclusion

The "Cannot find module 'supertest'" error is manageable with the right approach. Start by installing the package locally, verify your package.json, and check your import syntax. Use a clean reinstall if needed, and always run tests from the project root. With these steps, you'll have your API tests running smoothly. Remember, careful dependency management prevents many Node.js errors.