🏁 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} [mockable=false] - Whether to defer execution for testing.
 * @returns {MockChain<Response, Object>}
 */
function doFetch(url, opts, autostart = true) {
  const chain = MockChain.fromResponse(url, opts, autostart)
    .then(res => res.json());
  return chain;
}

The autostart flag directly maps to the MockChain constructor’s autostart parameter. When autostart = true, the internal executor does not run automatically — you take control via .mock() or .fail().

🧪 In Tests

const chain = doFetch(undefined, undefined, true); // mockable mode
chain.root.mock(new Response(JSON.stringify({ ok: true })));

const result = await chain;
console.assert(result.ok === true);

Because execution is deferred, no real network request occurs. You manually trigger the async flow when ready, simulating network latency, failures, or data transformations.

🚀 In Production

await doFetch('https://api/data', opts); // default (autostart = true)

In production, the function runs as a standard asynchronous operation. The deferred logic is bypassed, and the fetch request executes normally.

🧩 Why This Matters

By introducing an autostart flag:

  • Your async functions stay predictable and ergonomic.
  • Tests gain deterministic control over every async path.
  • You avoid separate testing APIs or code branches.
  • It integrates seamlessly with the MockChain(autostart) design.

Rule: Always give your async methods an autostart flag. It’s a simple design choice that yields total control, clarity, and confidence in your asynchronous logic.


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

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