rewiremock/lib/index.js.flow

Advanced dependency mocking device.

// @flow

declare type Plugin = any;
declare type Plugins = {
  childOnly: Plugin,
  nodejs: Plugin,
  protectNodeModles: Plugin,
  relative: Plugin,
  webpackAlias: Plugin,
  toBeUsed: Plugin,
  disabledByDefault: Plugin,
  mockThroughByDefault: Plugin,
  usedByDefault: Plugin,
  alwaysMatchOrigin: Plugin,
  directChild: Plugin,
};

declare interface OverloadedModule {
  name: string,
  fileName: string,
  parent: Object,
  original: Object,
  requireActual: () => any
}

declare type IStubFactory = (name: string, value: any) => any;

declare interface BaseMock {
  /**
   * Enabled call thought original module
   */
  callThrough(): *,

  /**
   * Mimic the original file, replacing all the original methods by mocks.
   * @param {IStubFactory} [stubFactory] - stub factory function
   * @example
   * mock.mockThrough();
   * mock.mockThrough( () => sinon.stub() );
   * mock.mockThrough( (name, value) => typeof value === 'function' ? sinon.stub() : value );
   */
  mockThrough(stubFactory?: IStubFactory): *,

  /**
   * enables hot mock updates
   * @return {this}
   */
  dynamic(): *,

  /**
   * Setting es6 bahavior for a module
   */
  es6(): *,

  /**
   * Overriding export of one module by another
   */
  by(module: string): BaseMock,

  /**
   * Overriding export of one module by something generated by a function
   */
  by(module: (module: OverloadedModule) => Object): BaseMock,

  enable(): *,

  disable(): *,

  /**
   * mocks only first direct children.
   */
  directChildOnly(): *;

  atAnyPlace(): *;

  /**
   * mocks only if parent were mocked
   */
  calledFromMock(): *;

  calledFromAnywhere(): *;

  /**
   * Force mock to be used, or throw an error otherwise
   */
  toBeUsed(): *,

  notToBeUsed(): *,

  /**
   * checks mocks against implementation
   * @return {this}
   */
  toMatchOrigin(): *,

  /**
   * Bypass shouldMock and always mock
   */
  always(): *,
}

declare interface MagicObjectWithRandomMethod {
  __magic__rewiremock_flow: any;
}

declare interface TypedModuleMock<T> extends BaseMock {
  /**
   * Overriding export of a module
   */
  with(key: $Shape<$Diff<T, MagicObjectWithRandomMethod>>): TypedModuleMock<T>;

  /**
   * Append overrides
   */
  append(key: $Shape<$Diff<T, MagicObjectWithRandomMethod>>): TypedModuleMock<T>;

  /**
   * Washes away the types
   */
  nonStrict(): AnyModuleMock;

  /**
   * Setting es6 behavior for a current module and overriding default export
   */
  withDefault(fn: $PropertyType<$Exact<T>, 'default'>): TypedModuleMock<T>;
}

declare interface AnyModuleMock extends BaseMock {
  /**
   * Setting es6 behavior for a current module and overriding default export
   */
  withDefault(stubs: any): AnyModuleMock;

  /**
   * Overriding export of a module
   */
  with(stubs: any): AnyModuleMock;

  /**
   * Append overrides
   */
  append(stubs: any): AnyModuleMock;
}

declare type Function = () => any;
declare type ModuleMock = AnyModuleMock;
declare type ProxyFunction = (r: ModuleMock) => Object;
declare type RequireFunction<T> = () => T;
declare type ImportFunction<T> = () => Promise<T>;
declare type AnyImportFunction<T> = RequireFunction<T> | ImportFunction<T>;

/**
 * @name rewiremock
 * @class
 * Proxies imports/require in order to allow overriding dependencies during testing.
 */
declare interface rewiremock {
  (module: string): ModuleMock;

  <T>(module: ImportFunction<T>): TypedModuleMock<T>;

  /**
   * returns existing mock
   */
  getMock(module: string): ModuleMock;
  getMock<T>(module: ImportFunction<T>): TypedModuleMock<T>;

  enable(): rewiremock;

  disable(): rewiremock;

  /**
   * executes module in a sanbox
   * @param {Function} loader - loader of target module. You can use import or require. May return a Promise
   * @param {Function} [creator] - mock creator. You may add any mocks inside.
   */
  around<T>(loader: AnyImportFunction<T>, creator: (mock: rewiremock) => any): Promise<T>;

  inScope(callback: Function): rewiremock;

  /**
   * Loads a file and hooks deps in a `proxyquire` way
   * @param {String|Function} fileName
   * @param {Object|Function} overrides, with key==filename, and value==data
   */
  proxy<T>(fileName: String | RequireFunction<T>, overrides: Object | ProxyFunction): T;

  /**
   * Loads a file and hooks deps in a `proxyquire` way
   * @param {Function} fileLoader. Require or Import desired module
   * @param {Object} overrides, with key==filename, and value==data
   */
  module<T>(fileLoader: ImportFunction<T>, overrides: Object | ProxyFunction): Promise<T>;

  flush(): void;

  clear(): void;

  /**
   * Define stub factory for mockThrought command
   * @param {IStubFactory} stubFactory
   */
  stubFactory(stubFactory: IStubFactory): void;

  /**
   * converts module name
   * @param module
   */
  resolve(module: string): string,

  /**
   * Activates module isolation
   * @param {Boolean} [options.noAutoPassBy] excludes mocked modules to a isolation scope. Use it with mock.callThrough.
   * @param {Boolean} [options.noParentPassBy] disable allowing any module, with allowed parent
   */
  isolation(options?: { noAutoPassBy?: boolean, noParentPassBy?: boolean}): rewiremock;

  /**
   * Deactivates isolation
   */
  withoutIsolation(): rewiremock;

  /**
   * set aggressive politics to cache operation, restoring to the the previous values on end.
   */
  forceCacheClear(): rewiremock;

  /**
   * Adding new isolationpassby record
   */
  passBy(pattern: string | RegExp): rewiremock;

  /**
   * Adds a plugin
   */
  addPlugin(plugin: any): rewiremock;

  /**
   * low-level require
   */
  requireActual(fileName: string): any;
  /**
   * low-level import
   */
  importActual(fileName: string): any;

  /**
   * low-level API override
   */
  overrideEntryPoint(module:any): void;
}


declare export function addPlugin(plugin: Plugin): void;
declare export function removePlugins(plugin: Plugin): void;
declare export function overrideEntryPoint(module:any):void;
declare export var plugins: Plugins;
declare export default rewiremock;