📚 TOC

📚 Table of Contents

Welcome to your comprehensive guide for the @fizzwiz/mockchain library! Whether you're just starting out or exploring advanced abstractions, this guide will help you navigate the documentation and resources with ease.

🚀 Getting Started

  • Welcome Overview, audience, and organizational principles behind the library.

  • Quick Start How to install and write your first meaningful code with @fizzwiz/mockchain.

  • Introduction The motivation, philosophy, and design goals shaping the library’s architecture.

  • Contribute & Feedback Ways to report issues, suggest improvements, or contribute to the project.

📄 API Overview

🧬 Core Package:

  • 🃏 MockChain class A mockable Promise subclass designed for deterministic async testing.

🧠 Concepts & Patterns

🎯 Practical Examples

Coming soon — real-world usage to help you master the library.

📌 This page will be updated regularly — bookmark it to stay current with project developments.


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