🃏 MockChain Class

🃏 MockChain API Reference

MockChain is a mockable subclass of Promise designed for testing asynchronous operations. It preserves the full promise interface while providing methods to manually control resolution, rejection, and chaining.

Constructor

new MockChain(executor?: (resolve: Function, reject: Function) => void, autoStart?: boolean, parent?: MockChain | null)
  • executor – Optional executor function, like in native Promise.
  • autoStart – If false, execution is deferred until .mock() or .fail() is manually called.
  • parent – Internal link to the previous node in the chain.

Creates a new MockChain instance. Use this when you need deterministic control over asynchronous behavior.

Properties

.root

  • Type: MockChain
  • Description: The first (root) node of the chain. Useful for triggering resolution or rejection at the beginning of a chain.

.parent

  • Type: MockChain | undefined | null
  • Description: Reference to the previous node in the chain.

.autoStart

  • Type: boolean
  • Description: Indicates whether this chain node executes automatically upon creation.

External Control Methods

.mock(value: any): void

Resolve the chain at this node with a value.

.fail(error: any): void

Reject the chain at this node with an error.

.mockAfter(ms: number, value: any): void

Resolve the node after a delay in milliseconds.

.failAfter(ms: number, error: any): void

Reject the node after a delay in milliseconds.

Note: .mock() and .fail() can be called on any node, not just .root.

Promise Overrides

MockChain overrides standard Promise methods to preserve chain mockability.

.then(onFulfilled?, onRejected?)

Returns a new MockChain node.

.catch(onRejected?)

Returns a new MockChain node.

.finally(onFinally?)

Returns a new MockChain node.

All chain nodes maintain .parent links and can be mocked individually.

Static Methods

MockChain.resolve(value)

Returns a MockChain resolved with value.

MockChain.reject(reason)

Returns a MockChain rejected with reason.

MockChain.from(promise | value, autoStart?: boolean, parent?: MockChain | null)

Wraps any promise or value in a MockChain. Supports deferred execution via the autoStart flag.

MockChain.fromResponse(url: string | undefined, opts?: RequestInit, autoStart?: boolean)

Creates a MockChain from a fetch request. If url is undefined, returns a placeholder chain. Execution can be deferred.

MockChain.fromMessage(ws: WebSocket | undefined, isMessage?: Function, attach?: boolean, autoStart?: boolean)

Creates a MockChain from WebSocket messages, with an optional message filter predicate. If ws is undefined, returns a non-auto-start placeholder chain.

MockChain.fromEvent(emitter: EventTarget | EventEmitter | undefined, eventName: string, isEvent?: Function, attach?: boolean, autoStart?: boolean)

Wraps a Node.js or browser event in a mockable chain, allowing for custom filtering via isEvent. If emitter is undefined, returns a non-auto-start placeholder chain.

All static constructors now support an autoStart flag for consistent asynchronous control.

Example Usage

import { MockChain } from '@fizzwiz/mockchain';

// Wrap a fetch request in a mockable chain
const chain = MockChain.from(fetch('https://api/data'))
  .then(res => res.json())
  .then(console.log);

// Mock the response at the root of the chain
chain.root.mock(
  new Response(JSON.stringify({ ok: true }))
);

// -> { ok: true }


Comments

Post a Comment

Popular posts from this blog

🏁 The autostart Flag

🏁 The   autostart   Flag — Designing Testable Async Methods Async functions are convenient, but they hide execution inside native Promises — which can’t be intercepted or mocked. To preserve control, every asynchronous method in a distributed system should expose a   autostart   flag . This simple addition enables you to decide   when   asynchronous execution actually happens, giving your tests full deterministic control while keeping production behavior untouched. 🎯 The Idea Instead of rewriting async logic for testing, let each function decide whether to execute its asynchronous flow immediately or defer it. A   mockable method : Runs normally in production ( autostart = true ). Defers execution in tests ( autostart = false ), allowing   MockChain   to intercept and control outcomes. ⚙️ Implementation Pattern import { MockChain } from '@fizzwiz/mockchain' ; /** * Fetch data from a URL. * @param { string } url * @param { boolean ...
Read more

🔑 Why MockChain Is a Chain

🔑 Why   MockChain   Is a Chain When testing asynchronous methods, you often want to   control behavior without rewriting the method logic .   MockChain   allows you to inject and observe behavior at   any point in a promise chain , not just at the start. 🧩 Two Ends of the Chain Consider a typical async method: function fetchData ( url, opts, autoStart = true ) { return MockChain . fromResponse (url, opts, autoStart) . then ( res => res. json ()) . then ( obj => obj. ok ); } There are   three promises   involved: Root node ( root )   — the initial wrapped promise (e.g.,   fetch() ) resolving to a Response object. Mid node   — the in-between promise resolving to the JSON object. Leaf node ( end )   — the last node resolving to a Boolean flag. In tests, you usually mock the   root   to trigger the   end   manually: const chain = fetchData ( undefined , undefined , false ); // don’t awai...
Read more

⚠️ Async Functions Are Not Mockable

  ⚠️ Async Functions Are Not Mockable Async functions are convenient in JavaScript, but they are   incompatible with mockable Promises   like   MockChain . This post explains   why   async functions break mockability and how to preserve control over promise chains. ❌ Why Async Functions Break Mockability An   async   function always returns a   native Promise , even if you return another Promise (as a   MockChain ) inside it. async function example ( ) { const chain = MockChain . resolve ( 42 ); return chain; // You think you're returning a MockChain... } const result = example (); console . log (result instanceof MockChain ); // ❌ false Why this happens:   ECMAScript’s   Promise assimilation   wraps any thenable in a new native Promise, so the original instance is lost. Consequences: Custom subclass methods ( .mock() ,   .fail() ,   .root ,   .parent ) disappear. Any attached metadata ( promise...
Read more