Typescript Mock Imports

Common errors

• TypeError: Cannot set property TestClass of #<Object> which has only a getter

  cause Attempting to mock a class from a module that defines its exports with getters, preventing modification. This is common with certain TypeScript compilation targets or bundler configurations (e.g., Babel 7+, Webpack).
  fix Replace `ImportMock.mockClass` with `new InPlaceMockManager(module, 'ClassName');` to use an alternative mocking strategy that bypasses the getter restriction.

• ReferenceError: [ClassName] is not defined

  cause The module path provided to `ImportMock.mockClass` in your test file does not precisely match the path used by the module under test that imports `ClassName`.
  fix Verify that `import * as myModule from './path/to/module';` in your test file uses the exact same relative or aliased path as the file that imports `ClassName` in your application code.

• Cannot find module 'sinon' or Cannot find module 'typescript'

  cause The peer dependencies `sinon` and/or `typescript` are not installed in the project.
  fix Install the required peer dependencies: `npm install sinon typescript --save-dev`.

• TypeError: module.exports is not a function or module.exports.default is not a constructor

  cause `ts-mock-imports` is designed for mocking ES6 `import`s of classes. This error can occur if you're trying to mock a CommonJS `require`'d module, or if the export structure doesn't match an ES6 class export.
  fix Ensure the module you are trying to mock is indeed exporting a class via ES6 `export class MyClass { ... }` or `export default class MyClass { ... }` and is being consumed via `import` statements. The library is not compatible with `requirejs`.

Warnings

• gotcha When mocking a module, both the source file and the test file must use the *exact same path* to import the target module. Inconsistent import paths (e.g., `'./src/foo'` in production vs. `'src/index'` in tests for the same module) will prevent the mock from being applied correctly.
  Fix: Standardize module import paths across your project, often by using `tsconfig.json` `paths` aliases, or ensure relative paths are identical between consumer and test files.
• breaking TypeScript versions 3.9 and later introduced changes that can cause a `TypeError: Cannot set property TestClass of #<Object> which has only a getter` when attempting to mock certain modules. This occurs because module exports are no longer enumerable, preventing `ts-mock-imports` from replacing the exported class.
  Fix: For modules exhibiting this error, use `InPlaceMockManager` instead of `ImportMock.mockClass`. This manager is designed to work around the getter issue. Example: `const mockManager = new InPlaceMockManager(fooModule, 'Foo');`
• gotcha It is critical to call `ImportMock.restore()` after each test or test suite where mocks were applied. Failure to restore mocks can lead to global state pollution, causing tests to interfere with each other and produce flaky or incorrect results.
  Fix: Always include `ImportMock.restore()` in an `afterEach` or `afterAll` hook in your test setup to reset the module state.
• gotcha While `ts-mock-imports` allows mocking ES6 `import`s, it relies on runtime manipulation of module exports. This mechanism is fundamentally a 'monkey patch' over Node's module system and may be less robust or compatible with native ESM environments where imports are often immutable.
  Fix: Be aware that complex module bundlers (e.g., Webpack, Rollup) or newer Node.js ESM loading behaviors might introduce challenges. Consider alternative dependency injection patterns if encountering consistent issues, or ensure your testing environment aligns with the library's assumptions about module loading.
• gotcha `ts-mock-imports` depends on `sinon` and `typescript` as peer dependencies. These must be installed manually in your project (typically as `devDependencies`) for the library to function correctly.
  Fix: Ensure `npm install sinon typescript --save-dev` has been run in your project.

Install

• npm install ts-mock-imports npm
• yarn add ts-mock-imports yarn
• pnpm add ts-mock-imports pnpm

Imports

• ImportMock
  wrong:

  const { ImportMock } = require('ts-mock-imports');

  correct:

  import { ImportMock } from 'ts-mock-imports';

  ImportMock is the main entry point for creating mocks and should be imported as a named export. While the library itself might be callable via CommonJS in some build environments, the core mocking mechanism primarily operates on ES6 `import`s.
• MockManager
  wrong:

  import { MockManager } from 'ts-mock-imports';

  correct:

  import type { MockManager } from 'ts-mock-imports';

  MockManager is a type interface for the object returned by `ImportMock.mockClass`. It should be imported as a type, not a value, to avoid potential runtime issues or unnecessary bundle size.
• InPlaceMockManager
  wrong:

  const { InPlaceMockManager } = require('ts-mock-imports');

  correct:

  import { InPlaceMockManager } from 'ts-mock-imports';

  InPlaceMockManager is an alternative manager for specific scenarios, particularly when encountering 'Cannot set property' errors due to module getters. It's used for mocking imports where standard `ImportMock.mockClass` fails.

Quickstart

Demonstrates mocking a TypeScript class imported via ES6 syntax, replacing its constructor and methods with stubs to prevent execution of original logic and control return values.

import { ImportMock } from 'ts-mock-imports';
import { Bar } from '../src/bar';
import * as fooModule from '../src/foo';

// Imagine 'Foo' class in '../src/foo.ts' has a constructor that throws an error
// and 'Bar' in '../src/bar.ts' instantiates 'Foo'.

describe('Bar', () => {
  let mockFooManager: ImportMock.MockManager<any>;

  beforeEach(() => {
    // Mock the 'Foo' class from 'fooModule'
    // This intercepts any 'new Foo()' call within modules that imported fooModule
    mockFooManager = ImportMock.mockClass(fooModule, 'Foo');
  });

  afterEach(() => {
    // Restore all mocks to their original implementations to ensure test isolation
    ImportMock.restore();
  });

  it('should create an instance of Bar without error when Foo is mocked', () => {
    // Now, new Bar() will use the mocked Foo, preventing the error
    const bar = new Bar();
    expect(bar).toBeInstanceOf(Bar);
  });

  it('should allow stubbing methods of the mocked Foo class', () => {
    // Configure a mock response for the 'getCount' method of Foo
    mockFooManager.mock('getCount', () => 42);

    // If Bar were to call getCount internally, it would now return 42
    // For demonstration, let's assume Bar had a method that called Foo.getCount()
    // (This example focuses on the core mocking setup)
    // const bar = new Bar();
    // const result = bar.getFooCount(); // Assuming such a method exists
    // expect(result).toBe(42);
    
    const mockFooInstance = mockFooManager.get;// For a real test, you'd test Bar's interaction with Foo
  });
});