index.d.ts 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406
  1. /**
  2. * Copyright (c) Meta Platforms, Inc. and affiliates.
  3. *
  4. * This source code is licensed under the MIT license found in the
  5. * LICENSE file in the root directory of this source tree.
  6. */
  7. export declare type ClassLike = {
  8. new (...args: any): any;
  9. };
  10. export declare type ConstructorLikeKeys<T> = keyof {
  11. [K in keyof T as Required<T>[K] extends ClassLike ? K : never]: T[K];
  12. };
  13. export declare const fn: <T extends FunctionLike = UnknownFunction>(
  14. implementation?: T | undefined,
  15. ) => Mock<T>;
  16. export declare type FunctionLike = (...args: any) => any;
  17. export declare type MethodLikeKeys<T> = keyof {
  18. [K in keyof T as Required<T>[K] extends FunctionLike ? K : never]: T[K];
  19. };
  20. /**
  21. * All what the internal typings need is to be sure that we have any-function.
  22. * `FunctionLike` type ensures that and helps to constrain the type as well.
  23. * The default of `UnknownFunction` makes sure that `any`s do not leak to the
  24. * user side. For instance, calling `fn()` without implementation will return
  25. * a mock of `(...args: Array<unknown>) => unknown` type. If implementation
  26. * is provided, its typings are inferred correctly.
  27. */
  28. export declare interface Mock<T extends FunctionLike = UnknownFunction>
  29. extends Function,
  30. MockInstance<T> {
  31. new (...args: Parameters<T>): ReturnType<T>;
  32. (...args: Parameters<T>): ReturnType<T>;
  33. }
  34. export declare type Mocked<T> = T extends ClassLike
  35. ? MockedClass<T>
  36. : T extends FunctionLike
  37. ? MockedFunction<T>
  38. : T extends object
  39. ? MockedObject<T>
  40. : T;
  41. export declare const mocked: {
  42. <T extends object>(
  43. source: T,
  44. options?: {
  45. shallow: false;
  46. },
  47. ): Mocked<T>;
  48. <T_1 extends object>(
  49. source: T_1,
  50. options: {
  51. shallow: true;
  52. },
  53. ): MockedShallow<T_1>;
  54. };
  55. export declare type MockedClass<T extends ClassLike> = MockInstance<
  56. (...args: ConstructorParameters<T>) => Mocked<InstanceType<T>>
  57. > &
  58. MockedObject<T>;
  59. export declare type MockedFunction<T extends FunctionLike> = MockInstance<T> &
  60. MockedObject<T>;
  61. declare type MockedFunctionShallow<T extends FunctionLike> = MockInstance<T> &
  62. T;
  63. export declare type MockedObject<T extends object> = {
  64. [K in keyof T]: T[K] extends ClassLike
  65. ? MockedClass<T[K]>
  66. : T[K] extends FunctionLike
  67. ? MockedFunction<T[K]>
  68. : T[K] extends object
  69. ? MockedObject<T[K]>
  70. : T[K];
  71. } & T;
  72. declare type MockedObjectShallow<T extends object> = {
  73. [K in keyof T]: T[K] extends ClassLike
  74. ? MockedClass<T[K]>
  75. : T[K] extends FunctionLike
  76. ? MockedFunctionShallow<T[K]>
  77. : T[K];
  78. } & T;
  79. export declare type MockedShallow<T> = T extends ClassLike
  80. ? MockedClass<T>
  81. : T extends FunctionLike
  82. ? MockedFunctionShallow<T>
  83. : T extends object
  84. ? MockedObjectShallow<T>
  85. : T;
  86. export declare type MockFunctionMetadata<
  87. T = unknown,
  88. MetadataType = MockMetadataType,
  89. > = MockMetadata<T, MetadataType>;
  90. export declare type MockFunctionMetadataType = MockMetadataType;
  91. declare type MockFunctionResult<T extends FunctionLike = UnknownFunction> =
  92. | MockFunctionResultIncomplete
  93. | MockFunctionResultReturn<T>
  94. | MockFunctionResultThrow;
  95. declare type MockFunctionResultIncomplete = {
  96. type: 'incomplete';
  97. /**
  98. * Result of a single call to a mock function that has not yet completed.
  99. * This occurs if you test the result from within the mock function itself,
  100. * or from within a function that was called by the mock.
  101. */
  102. value: undefined;
  103. };
  104. declare type MockFunctionResultReturn<
  105. T extends FunctionLike = UnknownFunction,
  106. > = {
  107. type: 'return';
  108. /**
  109. * Result of a single call to a mock function that returned.
  110. */
  111. value: ReturnType<T>;
  112. };
  113. declare type MockFunctionResultThrow = {
  114. type: 'throw';
  115. /**
  116. * Result of a single call to a mock function that threw.
  117. */
  118. value: unknown;
  119. };
  120. declare type MockFunctionState<T extends FunctionLike = UnknownFunction> = {
  121. /**
  122. * List of the call arguments of all calls that have been made to the mock.
  123. */
  124. calls: Array<Parameters<T>>;
  125. /**
  126. * List of all the object instances that have been instantiated from the mock.
  127. */
  128. instances: Array<ReturnType<T>>;
  129. /**
  130. * List of all the function contexts that have been applied to calls to the mock.
  131. */
  132. contexts: Array<ThisParameterType<T>>;
  133. /**
  134. * List of the call order indexes of the mock. Jest is indexing the order of
  135. * invocations of all mocks in a test file. The index is starting with `1`.
  136. */
  137. invocationCallOrder: Array<number>;
  138. /**
  139. * List of the call arguments of the last call that was made to the mock.
  140. * If the function was not called, it will return `undefined`.
  141. */
  142. lastCall?: Parameters<T>;
  143. /**
  144. * List of the results of all calls that have been made to the mock.
  145. */
  146. results: Array<MockFunctionResult<T>>;
  147. };
  148. export declare interface MockInstance<
  149. T extends FunctionLike = UnknownFunction,
  150. > {
  151. _isMockFunction: true;
  152. _protoImpl: Function;
  153. getMockImplementation(): T | undefined;
  154. getMockName(): string;
  155. mock: MockFunctionState<T>;
  156. mockClear(): this;
  157. mockReset(): this;
  158. mockRestore(): void;
  159. mockImplementation(fn: T): this;
  160. mockImplementationOnce(fn: T): this;
  161. withImplementation(fn: T, callback: () => Promise<unknown>): Promise<void>;
  162. withImplementation(fn: T, callback: () => void): void;
  163. mockName(name: string): this;
  164. mockReturnThis(): this;
  165. mockReturnValue(value: ReturnType<T>): this;
  166. mockReturnValueOnce(value: ReturnType<T>): this;
  167. mockResolvedValue(value: ResolveType<T>): this;
  168. mockResolvedValueOnce(value: ResolveType<T>): this;
  169. mockRejectedValue(value: RejectType<T>): this;
  170. mockRejectedValueOnce(value: RejectType<T>): this;
  171. }
  172. export declare type MockMetadata<T, MetadataType = MockMetadataType> = {
  173. ref?: number;
  174. members?: Record<string, MockMetadata<T>>;
  175. mockImpl?: T;
  176. name?: string;
  177. refID?: number;
  178. type?: MetadataType;
  179. value?: T;
  180. length?: number;
  181. };
  182. export declare type MockMetadataType =
  183. | 'object'
  184. | 'array'
  185. | 'regexp'
  186. | 'function'
  187. | 'constant'
  188. | 'collection'
  189. | 'null'
  190. | 'undefined';
  191. export declare class ModuleMocker {
  192. private readonly _environmentGlobal;
  193. private _mockState;
  194. private _mockConfigRegistry;
  195. private _spyState;
  196. private _invocationCallCounter;
  197. /**
  198. * @see README.md
  199. * @param global Global object of the test environment, used to create
  200. * mocks
  201. */
  202. constructor(global: typeof globalThis);
  203. private _getSlots;
  204. private _ensureMockConfig;
  205. private _ensureMockState;
  206. private _defaultMockConfig;
  207. private _defaultMockState;
  208. private _makeComponent;
  209. private _createMockFunction;
  210. private _generateMock;
  211. /**
  212. * Check whether the given property of an object has been already replaced.
  213. */
  214. private _findReplacedProperty;
  215. /**
  216. * @see README.md
  217. * @param metadata Metadata for the mock in the schema returned by the
  218. * getMetadata method of this module.
  219. */
  220. generateFromMetadata<T>(metadata: MockMetadata<T>): Mocked<T>;
  221. /**
  222. * @see README.md
  223. * @param component The component for which to retrieve metadata.
  224. */
  225. getMetadata<T = unknown>(
  226. component: T,
  227. _refs?: Map<T, number>,
  228. ): MockMetadata<T> | null;
  229. isMockFunction<T extends FunctionLike = UnknownFunction>(
  230. fn: MockInstance<T>,
  231. ): fn is MockInstance<T>;
  232. isMockFunction<P extends Array<unknown>, R>(
  233. fn: (...args: P) => R,
  234. ): fn is Mock<(...args: P) => R>;
  235. isMockFunction(fn: unknown): fn is Mock<UnknownFunction>;
  236. fn<T extends FunctionLike = UnknownFunction>(implementation?: T): Mock<T>;
  237. spyOn<
  238. T extends object,
  239. K extends PropertyLikeKeys<T>,
  240. V extends Required<T>[K],
  241. A extends 'get' | 'set',
  242. >(
  243. object: T,
  244. methodKey: K,
  245. accessType: A,
  246. ): A extends 'get'
  247. ? SpiedGetter<V>
  248. : A extends 'set'
  249. ? SpiedSetter<V>
  250. : never;
  251. spyOn<
  252. T extends object,
  253. K extends ConstructorLikeKeys<T> | MethodLikeKeys<T>,
  254. V extends Required<T>[K],
  255. >(
  256. object: T,
  257. methodKey: K,
  258. ): V extends ClassLike | FunctionLike ? Spied<V> : never;
  259. private _spyOnProperty;
  260. replaceProperty<T extends object, K extends keyof T>(
  261. object: T,
  262. propertyKey: K,
  263. value: T[K],
  264. ): Replaced<T[K]>;
  265. clearAllMocks(): void;
  266. resetAllMocks(): void;
  267. restoreAllMocks(): void;
  268. private _typeOf;
  269. mocked<T extends object>(
  270. source: T,
  271. options?: {
  272. shallow: false;
  273. },
  274. ): Mocked<T>;
  275. mocked<T extends object>(
  276. source: T,
  277. options: {
  278. shallow: true;
  279. },
  280. ): MockedShallow<T>;
  281. }
  282. export declare type PropertyLikeKeys<T> = Exclude<
  283. keyof T,
  284. ConstructorLikeKeys<T> | MethodLikeKeys<T>
  285. >;
  286. declare type RejectType<T extends FunctionLike> =
  287. ReturnType<T> extends PromiseLike<any> ? unknown : never;
  288. export declare interface Replaced<T = unknown> {
  289. /**
  290. * Restore property to its original value known at the time of mocking.
  291. */
  292. restore(): void;
  293. /**
  294. * Change the value of the property.
  295. */
  296. replaceValue(value: T): this;
  297. }
  298. export declare const replaceProperty: <T extends object, K extends keyof T>(
  299. object: T,
  300. propertyKey: K,
  301. value: T[K],
  302. ) => Replaced<T[K]>;
  303. declare type ResolveType<T extends FunctionLike> =
  304. ReturnType<T> extends PromiseLike<infer U> ? U : never;
  305. export declare type Spied<T extends ClassLike | FunctionLike> =
  306. T extends ClassLike
  307. ? SpiedClass<T>
  308. : T extends FunctionLike
  309. ? SpiedFunction<T>
  310. : never;
  311. export declare type SpiedClass<T extends ClassLike = UnknownClass> =
  312. MockInstance<(...args: ConstructorParameters<T>) => InstanceType<T>>;
  313. export declare type SpiedFunction<T extends FunctionLike = UnknownFunction> =
  314. MockInstance<(...args: Parameters<T>) => ReturnType<T>>;
  315. export declare type SpiedGetter<T> = MockInstance<() => T>;
  316. export declare type SpiedSetter<T> = MockInstance<(arg: T) => void>;
  317. export declare interface SpyInstance<T extends FunctionLike = UnknownFunction>
  318. extends MockInstance<T> {}
  319. export declare const spyOn: {
  320. <
  321. T extends object,
  322. K_2 extends Exclude<
  323. keyof T,
  324. | keyof {
  325. [K in keyof T as Required<T>[K] extends ClassLike ? K : never]: T[K];
  326. }
  327. | keyof {
  328. [K_1 in keyof T as Required<T>[K_1] extends FunctionLike
  329. ? K_1
  330. : never]: T[K_1];
  331. }
  332. >,
  333. V extends Required<T>[K_2],
  334. A extends 'set' | 'get',
  335. >(
  336. object: T,
  337. methodKey: K_2,
  338. accessType: A,
  339. ): A extends 'get'
  340. ? SpiedGetter<V>
  341. : A extends 'set'
  342. ? SpiedSetter<V>
  343. : never;
  344. <
  345. T_1 extends object,
  346. K_5 extends
  347. | keyof {
  348. [K_3 in keyof T_1 as Required<T_1>[K_3] extends ClassLike
  349. ? K_3
  350. : never]: T_1[K_3];
  351. }
  352. | keyof {
  353. [K_4 in keyof T_1 as Required<T_1>[K_4] extends FunctionLike
  354. ? K_4
  355. : never]: T_1[K_4];
  356. },
  357. V_1 extends Required<T_1>[K_5],
  358. >(
  359. object: T_1,
  360. methodKey: K_5,
  361. ): V_1 extends ClassLike | FunctionLike ? Spied<V_1> : never;
  362. };
  363. export declare type UnknownClass = {
  364. new (...args: Array<unknown>): unknown;
  365. };
  366. export declare type UnknownFunction = (...args: Array<unknown>) => unknown;
  367. export {};