feat(mock): add useFakeTimers method

bin/test.ts

@@ -11,6 +11,7 @@ import { Runner } from '#src'
 
 await Runner.setTsEnv()
   .addAssertPlugin()
+  .addExpectTypeOfPlugin()
   .addPath('tests/unit/**/*Test.ts')
   .setCliArgs(process.argv.slice(2))
   .setGlobalTimeout(10000)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@athenna/test",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "The Athenna test runner. Built on top of Japa.",
   "license": "MIT",
   "author": "João Lenon <lenon@athenna.io>",

src/mocks/Mock.ts

@@ -17,6 +17,7 @@ import type {
 } from '#src'
 import { createSandbox } from 'sinon'
 import { MockBuilder } from '#src/mocks/MockBuilder'
+import type { FakeTimerInstallOpts } from '#src/types/FakeTimerInstallOpts'
 
 export class Mock {
   /**
@@ -32,6 +33,13 @@ export class Mock {
     return new MockBuilder(Mock.sandbox, object, method)
   }
 
+  /**
+   * Create a fake timer to mock dates in your application.
+   */
+  public static useFakeTimers(config?: number | Date | FakeTimerInstallOpts) {
+    return Mock.sandbox.useFakeTimers(config)
+  }
+
   /**
    * Create a spy function for a given object.
    */

src/types/FakeMethod.ts

@@ -0,0 +1,28 @@
+/**
+ * @athenna/test
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * Names of clock methods that may be faked by install.
+ */
+export type FakeMethod =
+  | 'setTimeout'
+  | 'clearTimeout'
+  | 'setImmediate'
+  | 'clearImmediate'
+  | 'setInterval'
+  | 'clearInterval'
+  | 'Date'
+  | 'nextTick'
+  | 'hrtime'
+  | 'requestAnimationFrame'
+  | 'cancelAnimationFrame'
+  | 'requestIdleCallback'
+  | 'cancelIdleCallback'
+  | 'performance'
+  | 'queueMicrotask'

src/types/FakeTimerInstallOpts.ts

@@ -0,0 +1,46 @@
+/**
+ * @athenna/test
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import type { FakeMethod } from '#src/types'
+
+export interface FakeTimerInstallOpts {
+  /**
+   * Installs fake timers with the specified unix epoch (default: 0)
+   */
+  now?: number | Date | undefined
+
+  /**
+   * An array with names of global methods and APIs to fake. By default, `@sinonjs/fake-timers` does not replace `nextTick()` and `queueMicrotask()`.
+   * For instance, `FakeTimers.install({ toFake: ['setTimeout', 'nextTick'] })` will fake only `setTimeout()` and `nextTick()`
+   */
+  toFake?: FakeMethod[] | undefined
+
+  /**
+   * The maximum number of timers that will be run when calling runAll() (default: 1000)
+   */
+  loopLimit?: number | undefined
+
+  /**
+   * Tells @sinonjs/fake-timers to increment mocked time automatically based on the real system time shift (e.g. the mocked time will be incremented by
+   * 20ms for every 20ms change in the real system time) (default: false)
+   */
+  shouldAdvanceTime?: boolean | undefined
+
+  /**
+   * Relevant only when using with shouldAdvanceTime: true. increment mocked time by advanceTimeDelta ms every advanceTimeDelta ms change
+   * in the real system time (default: 20)
+   */
+  advanceTimeDelta?: number | undefined
+
+  /**
+   * Tells FakeTimers to clear 'native' (i.e. not fake) timers by delegating to their respective handlers. These are not cleared by
+   * default, leading to potentially unexpected behavior if timers existed prior to installing FakeTimers. (default: false)
+   */
+  shouldClearNativeTimers?: boolean | undefined
+}

src/types/index.ts

@@ -1,3 +1,3 @@
 /**
  * @athenna/test
  *
@@ -12,6 +12,7 @@
 export * from '#src/types/Spy'
 export * from '#src/types/Match'
 export * from '#src/types/SpyMethod'
+export * from '#src/types/FakeMethod'
 export * from '#src/types/SpyInstance'
 export * from '#src/types/Stub'
 export * from '#src/types/StubMethod'