🏠 Intro

🏠 Introduction to @fizzwiz/mockchain

@fizzwiz/mockchain helps you test asynchronous operations in distributed systems, one node, one method, and one promise at a time.

One node at a time → One method at a time → One promise at a time

Testing a distributed system doesn’t require simulating the whole network. Each node can be tested in isolation — by testing its methods individually. Each asynchronous method can be tested by controlling one promise: the one that starts the chain.

MockChain makes this possible — by letting you inject, replace, or mock the initial promise of any async workflow.

🧠 The Core Idea

In a distributed computation, every node performs asynchronous operations — sending messages, waiting for responses, processing data. Testing nodes in isolation can be difficult when they depend on unpredictable async events.

MockChain addresses this by replacing the raw Promise in each async method with a mockable chain. Each node of the chain exposes parent and root links referencing the immediate previous and the top-level node of the chain. This allows you to manually control when (and with what) the operation resolves or rejects — while preserving the full Promise interface for chaining.

By injecting a mock value into the root node (root), you can test all downstream logic deterministically. Every node in the chain can be inspected or mocked individually.

⚙️ How It Works

Use MockChain instead of a raw Promise in your method implementation. In production, it behaves like a normal promise. In tests, you can mock any node in the chain and observe the downstream result:

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

// In code — use MockChain instead of a raw Promise
function fetchData(url, opts, autoStart = true) {
  const chain = MockChain.fromResponse(url, opts, autoStart);   // wrap fetch in a mockable chain
  return chain
    .then(res => res.json())                   // process the response
}

// In test — control the async flow manually
const chain = fetchData(undefined, undefined, false);           // get the mockable chain
chain.root.mock(new Response(JSON.stringify({ ok: true }))); // mock root node
const data = await chain;                          // await the leaf node resolution
console.log(data.ok);                             // verify result

Here, MockChain acts as the controllable bridge between the async source (network or event) and your application logic. You can also traverse or mock intermediate nodes using parent links if needed.

🧙‍♂️ Why It Matters

By structuring your system around MockChains:

  • You can test distributed nodes in isolation, without simulating the whole network.
  • You can control asynchronous flows deterministically in CI or development.
  • You can inject or override async responses at any node in the chain, observing downstream behavior in real-time.

This makes your async code predictable and fully testable, while preserving the same API as native promises.

“One node at a time → One method at a time → One promise at a time.” — @fizzwiz ✨


Comments

Post a Comment

Popular posts from this blog

🔑 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

🏁 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

⚠️ 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