Bristo

Create mock objects and assert precise order of interactions.

Installation

npm install bristo

Usage

Create a mock object and assert on function calls without adding any implementations:

import { Root, Mock, pick } from 'bristo'

type Mocked = {
  getUser(id: string): string
  saveUser(name: string): void
  isActive: boolean
}

const root = Root<Mocked>()
const mock = Mock(root)

mock.getUser('123')
mock.saveUser('Alice')
mock.isActive = true

const events = pick(root.getUser, root.saveUser, root.isActive).read()

expect(events).toEqual([
  { type: 'call', path: root.getUser, args: ['123'] },
  { type: 'call', path: root.saveUser, args: ['Alice'] },
  { type: 'set', path: root.isActive, value: true }
])

set and call are the only event types.

Adding Implementations

Use set() to add mock implementations. Use set() for both functions and values. Intermediate objects are created automatically. Does not trigger write events

import { Root, Mock, pick, set } from 'bristo'

type Mocked = {
  getUser(id: string): string
  config: { timeout: number }
}

const root = Root<Mocked>()

set(root.getUser, id => `user-${id}`)
set(root.config.timeout, 5000)

// Alternatively:

set(root, {
  getUser: id=> `user-${id}`,
  config: { timeout: 5000 }
})

const mock = Mock(root)

const user = mock.getUser('123')
console.log(user)  // -> "user-123"

console.log(root.config.timeout)  // -> 5000

const events = pick(root.getUser).read()
expect(events).toEqual([
  { type: 'call', path: root.getUser, args: ['123'] }
])

Filtering Events

Use pick() to select specific paths, omit() to exclude paths, and empty() to drop all past events and restart logging:

import { Root, Mock, pick, omit } from 'bristo'

type Mocked = {
  fs: {
    readFile(path: string): string
    writeFile(path: string): void
  }
  db: {
    query(sql: string): void
  }
}

const root = Root<Mocked>()
const mock = Mock(root)

pick selects only the specified paths

pick(root.fs.readFile).read()

will log only events from root.fs.readFile

omit selects everything EXCEPT the specified paths

omit(root.db).read()

will log readFile and writeFile events

pick(root.fs).omit(root.fs.writeFile).read()

will log only readFile events

empty() restarts logging from this point

mock.fs.readFile('b.txt')
const afterEmpty = pick(root.fs).empty()
mock.fs.readFile('c.txt')
const future = afterEmpty.read()
// Only 'c.txt' event

Mocking Multiple Objects

Pass multiple paths to pick() to combine events from different parts of your interface:

import { Root, Mock, pick } from 'bristo'

type Mock1 = {
  getUser(id: string): void
  updateUser(id: string, data: any): void
}
type Mock2 = {
  login(email: string): void
  logout(): void
}

const root = Root<{ mock1: Mock1, mock2: Mock2 }>()
const mock1 = Mock(root.mock1)
const mock2 = Mock(root.mock2)

mock1.getUser('123')
mock2.login('[email protected]')

const events = pick(root).read()
expect(events).toEqual([
  { type: 'call', path: root.mock1.getUser, args: ['123'] }
  { type: 'call', path: root.mock2.login, args: ['[email protected]'] }
])