@@ -45,19 +45,36 @@ class MockFunctionContext { |
45 | 45 | this.#times = times; |
46 | 46 | } |
47 | 47 |
|
| 48 | + /** |
| 49 | + * Gets an array of recorded calls made to the mock function. |
| 50 | + * @returns {Array} An array of recorded calls. |
| 51 | + */ |
48 | 52 | get calls() { |
49 | 53 | return ArrayPrototypeSlice(this.#calls, 0); |
50 | 54 | } |
51 | 55 |
|
| 56 | + /** |
| 57 | + * Retrieves the number of times the mock function has been called. |
| 58 | + * @returns {number} The call count. |
| 59 | + */ |
52 | 60 | callCount() { |
53 | 61 | return this.#calls.length; |
54 | 62 | } |
55 | 63 |
|
| 64 | + /** |
| 65 | + * Sets a new implementation for the mock function. |
| 66 | + * @param {Function} implementation - The new implementation for the mock function. |
| 67 | + */ |
56 | 68 | mockImplementation(implementation) { |
57 | 69 | validateFunction(implementation, 'implementation'); |
58 | 70 | this.#implementation = implementation; |
59 | 71 | } |
60 | 72 |
|
| 73 | + /** |
| 74 | + * Replaces the implementation of the function only once. |
| 75 | + * @param {Function} implementation - The substitute function. |
| 76 | + * @param {number} [onCall] - The call index to be replaced. |
| 77 | + */ |
61 | 78 | mockImplementationOnce(implementation, onCall) { |
62 | 79 | validateFunction(implementation, 'implementation'); |
63 | 80 | const nextCall = this.#calls.length; |
@@ -66,6 +83,9 @@ class MockFunctionContext { |
66 | 83 | this.#mocks.set(call, implementation); |
67 | 84 | } |
68 | 85 |
|
| 86 | + /** |
| 87 | + * Restores the original function that was mocked. |
| 88 | + */ |
69 | 89 | restore() { |
70 | 90 | const { descriptor, object, original, methodName } = this.#restore; |
71 | 91 |
|
@@ -79,14 +99,25 @@ class MockFunctionContext { |
79 | 99 | } |
80 | 100 | } |
81 | 101 |
|
| 102 | + /** |
| 103 | + * Resets the recorded calls to the mock function |
| 104 | + */ |
82 | 105 | resetCalls() { |
83 | 106 | this.#calls = []; |
84 | 107 | } |
85 | 108 |
|
| 109 | + /** |
| 110 | + * Tracks a call made to the mock function. |
| 111 | + * @param {object} call - The call details. |
| 112 | + */ |
86 | 113 | trackCall(call) { |
87 | 114 | ArrayPrototypePush(this.#calls, call); |
88 | 115 | } |
89 | 116 |
|
| 117 | + /** |
| 118 | + * Gets the next implementation to use for the mock function. |
| 119 | + * @returns {Function} The next implementation. |
| 120 | + */ |
90 | 121 | nextImpl() { |
91 | 122 | const nextCall = this.#calls.length; |
92 | 123 | const mock = this.#mocks.get(nextCall); |
@@ -109,11 +140,23 @@ class MockTracker { |
109 | 140 | #mocks = []; |
110 | 141 | #timers; |
111 | 142 |
|
| 143 | + /** |
| 144 | + * Returns the mock timers of this MockTracker instance. |
| 145 | + * @returns {MockTimers} The mock timers instance. |
| 146 | + */ |
112 | 147 | get timers() { |
113 | 148 | this.#timers ??= new MockTimers(); |
114 | 149 | return this.#timers; |
115 | 150 | } |
116 | 151 |
|
| 152 | + /** |
| 153 | + * Creates a mock function tracker. |
| 154 | + * @param {Function} [original] - The original function to be tracked. |
| 155 | + * @param {Function} [implementation] - An optional replacement function for the original one. |
| 156 | + * @param {object} [options] - Additional tracking options. |
| 157 | + * @param {number} [options.times=Infinity] - The maximum number of times the mock function can be called. |
| 158 | + * @returns {ProxyConstructor} The mock function tracker. |
| 159 | + */ |
117 | 160 | fn( |
118 | 161 | original = function() {}, |
119 | 162 | implementation = original, |
@@ -137,6 +180,17 @@ class MockTracker { |
137 | 180 | return this.#setupMock(ctx, original); |
138 | 181 | } |
139 | 182 |
|
| 183 | + /** |
| 184 | + * Creates a method tracker for a specified object or function. |
| 185 | + * @param {(object | Function)} objectOrFunction - The object or function containing the method to be tracked. |
| 186 | + * @param {string} methodName - The name of the method to be tracked. |
| 187 | + * @param {Function} [implementation] - An optional replacement function for the original method. |
| 188 | + * @param {object} [options] - Additional tracking options. |
| 189 | + * @param {boolean} [options.getter=false] - Indicates whether this is a getter method. |
| 190 | + * @param {boolean} [options.setter=false] - Indicates whether this is a setter method. |
| 191 | + * @param {number} [options.times=Infinity] - The maximum number of times the mock method can be called. |
| 192 | + * @returns {ProxyConstructor} The mock method tracker. |
| 193 | + */ |
140 | 194 | method( |
141 | 195 | objectOrFunction, |
142 | 196 | methodName, |
@@ -216,6 +270,18 @@ class MockTracker { |
216 | 270 | return mock; |
217 | 271 | } |
218 | 272 |
|
| 273 | + /** |
| 274 | + * Mocks a getter method of an object. |
| 275 | + * This is a syntax sugar for the MockTracker.method with options.getter set to true |
| 276 | + * @param {object} object - The target object. |
| 277 | + * @param {string} methodName - The name of the getter method to be mocked. |
| 278 | + * @param {Function} [implementation] - An optional replacement function for the targeted method. |
| 279 | + * @param {object} [options] - Additional tracking options. |
| 280 | + * @param {boolean} [options.getter=true] - Indicates whether this is a getter method. |
| 281 | + * @param {boolean} [options.setter=false] - Indicates whether this is a setter method. |
| 282 | + * @param {number} [options.times=Infinity] - The maximum number of times the mock method can be called. |
| 283 | + * @returns {ProxyConstructor} The mock method tracker. |
| 284 | + */ |
219 | 285 | getter( |
220 | 286 | object, |
221 | 287 | methodName, |
@@ -244,6 +310,18 @@ class MockTracker { |
244 | 310 | }); |
245 | 311 | } |
246 | 312 |
|
| 313 | + /** |
| 314 | + * Mocks a setter method of an object. |
| 315 | + * This function is a syntax sugar for MockTracker.method with options.setter set to true. |
| 316 | + * @param {object} object - The target object. |
| 317 | + * @param {string} methodName - The setter method to be mocked. |
| 318 | + * @param {Function} [implementation] - An optional replacement function for the targeted method. |
| 319 | + * @param {object} [options] - Additional tracking options. |
| 320 | + * @param {boolean} [options.getter=false] - Indicates whether this is a getter method. |
| 321 | + * @param {boolean} [options.setter=true] - Indicates whether this is a setter method. |
| 322 | + * @param {number} [options.times=Infinity] - The maximum number of times the mock method can be called. |
| 323 | + * @returns {ProxyConstructor} The mock method tracker. |
| 324 | + */ |
247 | 325 | setter( |
248 | 326 | object, |
249 | 327 | methodName, |
@@ -272,12 +350,18 @@ class MockTracker { |
272 | 350 | }); |
273 | 351 | } |
274 | 352 |
|
| 353 | + /** |
| 354 | + * Resets the mock tracker, restoring all mocks and clearing timers. |
| 355 | + */ |
275 | 356 | reset() { |
276 | 357 | this.restoreAll(); |
277 | 358 | this.#timers?.reset(); |
278 | 359 | this.#mocks = []; |
279 | 360 | } |
280 | 361 |
|
| 362 | + /** |
| 363 | + * Restore all mocks created by this MockTracker instance. |
| 364 | + */ |
281 | 365 | restoreAll() { |
282 | 366 | for (let i = 0; i < this.#mocks.length; i++) { |
283 | 367 | FunctionPrototypeCall(restore, this.#mocks[i]); |
|