api.md

Examples and explanation about how to use micmac

mockExecution(fn)

mockExecution mock global features (such as setTimeout) and then calls fn. This way when fn gets called, global features are mocked. After fn gets called features are restored to their original value.

import { mockExecution } from "micmac"

const globalSetTimeout = setTimeout
mockExecution(() => {
  setTimeout === globalSetTimeout // false
})
setTimeout === globalSetTimeout // true

Please note that if fn throws, mockExecution restore features because it wraps fn into try/finally.

mockExecution controller

mockExecution callback is called with a controller exposing many methods to control execution of your code.

tick(millisecond = 0, nanosecond = 0)

Optionnaly elapse given millisecond & nanosecond and executes all pending macrotask and microtask.

import { mockExecution } from "micmac"

mockExecution(({ tick })) => {
  const calls = []
  // nextTick registers microtask
  process.nextTick(() => {
    calls.push('nextTick')
  })

  // setImmediate registers macrotask
  setImmediate(() => {
    calls.push('setImmediate')
  })

  // setTimeout registers macrotask with a dependency to ellapsed time
  setTimeout(() => {
    calls.push('setTimeout')
  }, 5)

  tick(5)

  calls.join() === 'setImmediate,setTimeout,nextTick'
})

mockExecution examples

This section will show many example of how mockExecution is meant to be used. For the brievty of the examples some toBeTested function are declared inline. In your application you would import it from an external module that you want to test. The examples not declaring toBeTested function are here to show side effects on time related features.

Promise

import { mockExecution } from "micmac"

const toBeTested = () => Promise.resolve()

mockExecution(({ tick }) => {
  let called = false
  toBeTested().then(() => {
    called = true
  })
  called // false
  tick()
  called // true
})

time

import { mockExecution } from "micmac"

const toBeTested = (fn) => setTimeout(fn, 10)

mockExecution(({ tick }) => {
  let called = false
  toBeTested(() => {
    called = true
  })
  called // false
  tick(10)
  called // true
})

setInterval/clearInterval, setImmediate/clearImmediate, requestAnimationFrame/cancelAnimationFrame and process.nextTick work almost the same. You can reuse above example with them.

Date.now()

import { mockExecution } from "micmac"

mockExecution(({ tick }) => {
  tick(10)
  Date.now() // 10
})

new Date()

import { mockExecution } from "micmac"

mockExecution(({ tick }) => {
  tick(10)
  new Date().getTime() // 10
})

process.uptime()

import { mockExecution } from "micmac"

mockExecution(({ tick }) => {
  tick(1000)
  process.uptime() // 1
})

process.hrtime()

import { mockExecution } from "micmac"

mockExecution(({ tick }) => {
  tick(1000, 100)
  process.hrtime() // [1, 100]
})