tinyspy 3.0.2: spy

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify tinyspy.spy in pkg:npm/tinyspy@3.0.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinyspy@3.0.2
Demonstrate these symbols/APIs:
  - tinyspy.spy

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:88df6b81229665dcccf4bcd29554f899c480e60a09da27b3b4fc993b58e2f14d","constraints":{"executionContext":"node"},"contract":["spy creates a standalone spy function tracking calls, arguments, and return values","spy wraps an implementation function preserving arity and name","spy records errors thrown during execution and propagates them to the caller","spy nextResult and nextError queue one-time return values and thrown errors","spy intercepts constructor calls invoked with the new keyword","spy tracks asynchronous function execution and resolves promise results","spy reset restores recorded calls, results, resolves, and queued overrides to initial state","spy throws an error when passed a non-function value"],"goal":"verify tinyspy.spy in pkg:npm/tinyspy@3.0.2","kind":"HOW","packages":["pkg:npm/tinyspy@3.0.2"],"schemaVersion":1,"symbols":["tinyspy.spy"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/tinyspy@3.0.2"],"schemaVersion":1,"subject":"pkg:npm/tinyspy@3.0.2","symbols":["tinyspy.spy"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyspy-spy",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyspy-spy",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tinyspy": "3.0.2"
      }
    },
    "node_modules/tinyspy": {
      "version": "3.0.2",
      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-3.0.2.tgz",
      "integrity": "sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-tinyspy-spy",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "Clean-room verification for tinyspy.spy in tinyspy@3.0.2",
  "main": "test/contract.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "tinyspy": "3.0.2"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify tinyspy.spy in pkg:npm/tinyspy@3.0.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyspy@3.0.2"
  ],
  "symbols": [
    "tinyspy.spy"
  ]
}

import assert from "node:assert";
import { spy } from "tinyspy";

async function runContract() {
  // 1. Standalone spy tracking calls, arguments, and returns
  const standaloneSpy = spy();
  assert.strictEqual(standaloneSpy.called, false, "spy.called should initially be false");
  assert.strictEqual(standaloneSpy.callCount, 0, "spy.callCount should initially be 0");
  assert.deepStrictEqual(standaloneSpy.calls, [], "spy.calls should initially be empty");
  assert.strictEqual(standaloneSpy._isMockFunction, true, "spy._isMockFunction should be true");
  assert.strictEqual(standaloneSpy.name, "spy", "standalone spy name should default to spy");
  assert.strictEqual(standaloneSpy.length, 0, "standalone spy length should be 0");

  const resStandalone = standaloneSpy("alpha", 42);
  assert.strictEqual(resStandalone, undefined, "standalone spy returns undefined by default");
  assert.strictEqual(standaloneSpy.called, true, "spy.called should be true after call");
  assert.strictEqual(standaloneSpy.callCount, 1, "spy.callCount should be 1 after one call");
  assert.deepStrictEqual(standaloneSpy.calls, [["alpha", 42]], "spy.calls should record arguments");
  assert.deepStrictEqual(standaloneSpy.returns, [undefined], "spy.returns should record undefined");
  assert.deepStrictEqual(standaloneSpy.results, [["ok", undefined]], "spy.results should record ok with undefined");

  // 2. Spy wrapping an implementation function preserving arity and name
  function calculateSum(a, b, c) {
    return a + b + c;
  }
  const sumSpy = spy(calculateSum);
  assert.strictEqual(sumSpy.name, "calculateSum", "spy should preserve function name");
  assert.strictEqual(sumSpy.length, 3, "spy should preserve function parameter length");
  assert.strictEqual(sumSpy(10, 20, 30), 60, "spy should invoke wrapped function and return result");
  assert.strictEqual(sumSpy.called, true, "spy.called should be true");
  assert.strictEqual(sumSpy.callCount, 1, "spy.callCount should be 1");
  assert.deepStrictEqual(sumSpy.calls, [[10, 20, 30]], "spy.calls should record arguments");
  assert.deepStrictEqual(sumSpy.returns, [60], "spy.returns should record returned sum");
  assert.deepStrictEqual(sumSpy.results, [["ok", 60]], "spy.results should record ok result");

  // 3. Spy records errors thrown during execution and propagates them
  const throwSpy = spy((msg) => {
    throw new Error(msg);
  });
  assert.throws(() => throwSpy("contract-error"), /contract-error/, "spy should rethrow error");
  assert.strictEqual(throwSpy.called, true, "spy.called should be true after thrown error");
  assert.strictEqual(throwSpy.callCount, 1, "spy.callCount should increment after thrown error");
  assert.strictEqual(throwSpy.results.length, 1, "results array should record the failure");
  assert.strictEqual(throwSpy.results[0][0], "error", "result status should be error");
  assert.strictEqual(throwSpy.results[0][1].message, "contract-error", "result value should be error object");

  // 4. nextResult and nextError queue one-time return values and errors
  const modifierSpy = spy((x) => x * 2);
  modifierSpy.nextResult(500);
  modifierSpy.nextError(new Error("queued-error"));

  assert.strictEqual(modifierSpy(5), 500, "nextResult should override return value once");
  assert.throws(() => modifierSpy(5), /queued-error/, "nextError should throw queued error once");
  assert.strictEqual(modifierSpy(5), 10, "subsequent call should resume standard implementation");
  assert.strictEqual(modifierSpy.callCount, 3, "callCount should reflect all invocations");

  // 5. Spy intercepts constructor calls invoked with new
  class TargetService {
    constructor(identifier) {
      this.identifier = identifier;
    }
  }
  const TargetSpy = spy(TargetService);
  const instance = new TargetSpy("service-01");
  assert.strictEqual(instance.identifier, "service-01", "constructor instance should initialize properties");
  assert.strictEqual(TargetSpy.called, true, "spy.called should be true after constructor invocation");
  assert.strictEqual(TargetSpy.callCount, 1, "spy.callCount should be 1 after constructor invocation");
  assert.deepStrictEqual(TargetSpy.calls, [["service-01"]], "spy.calls should record constructor arguments");

  // 6. Spy tracks asynchronous execution and resolves promise results
  const asyncOperation = spy(async (val) => {
    return `result-${val}`;
  });
  const pendingPromise = asyncOperation("ok");
  assert.deepStrictEqual(asyncOperation.resolves, [], "resolves should be empty before promise settles");
  const asyncResult = await pendingPromise;
  assert.strictEqual(asyncResult, "result-ok", "async function should resolve to expected string");
  assert.deepStrictEqual(asyncOperation.resolves, [["ok", "result-ok"]], "resolves should record ok with resolved value");

  // 7. Reset restores recorded state to initial state
  modifierSpy.nextResult(999);
  modifierSpy.reset();
  assert.strictEqual(modifierSpy.called, false, "called should be false after reset");
  assert.strictEqual(modifierSpy.callCount, 0, "callCount should be 0 after reset");
  assert.deepStrictEqual(modifierSpy.calls, [], "calls should be empty after reset");
  assert.deepStrictEqual(modifierSpy.returns, [], "returns should be empty after reset");
  assert.deepStrictEqual(modifierSpy.results, [], "results should be empty after reset");
  assert.deepStrictEqual(modifierSpy.resolves, [], "resolves should be empty after reset");
  assert.strictEqual(modifierSpy(3), 6, "implementation should work normally without queued overrides");

  // 8. Spy throws error when passed non-function value
  assert.throws(() => {
    spy(9999);
  }, /cannot spy on a non-function value/, "spy should reject non-function target");

  console.log("Contract verified successfully.");
}

runContract().catch((err) => {
  console.error("Contract failed:", err);
  process.exit(1);
});