tinyspy 3.0.2: spy, spyOn

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 pkg:npm/tinyspy@3.0.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinyspy@3.0.2
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:95ae016fd3ee70c0de8d319be5c9bb29b84366b20b47c46e2f2da7e87b3f643a","constraints":{"executionContext":"node"},"contract":["spy wraps a function and records calls, arguments, and return values","spy tracks callCount and called state accurately across multiple invocations","spy captures thrown errors in results array when wrapped function fails","spy nextResult overrides return value for a single subsequent call","spy nextError causes a single subsequent call to throw specified error","spyOn wraps an object method and restore reverts back to original implementation","spy reset clears recorded calls, returns, results, and invocation count"],"goal":"verify pkg:npm/tinyspy@3.0.2","kind":"HOW","packages":["pkg:npm/tinyspy@3.0.2"],"schemaVersion":1,"symbols":["spy","spyOn"]},"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":["spy","spyOn"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyspy",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyspy",
      "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",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "Clean-room verification for 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 pkg:npm/tinyspy@3.0.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyspy@3.0.2"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import assert from "node:assert";
import { spy, spyOn, restoreAll } from "tinyspy";

async function runContract() {
  // 1. Basic spy wrapping, argument tracking, and return value recording
  const add = (a, b) => a + b;
  const fn = spy(add);

  assert.strictEqual(fn.called, false, "spy.called should initially be false");
  assert.strictEqual(fn.callCount, 0, "spy.callCount should initially be 0");
  assert.deepStrictEqual(fn.calls, [], "spy.calls should initially be empty");

  const res1 = fn(2, 3);
  assert.strictEqual(res1, 5, "spy should return result of wrapped function");
  assert.strictEqual(fn.called, true, "spy.called should be true after call");
  assert.strictEqual(fn.callCount, 1, "spy.callCount should be 1 after one call");
  assert.deepStrictEqual(fn.calls, [[2, 3]], "spy.calls should record argument list");
  assert.deepStrictEqual(fn.returns, [5], "spy.returns should record return values");
  assert.deepStrictEqual(fn.results, [["ok", 5]], "spy.results should record result tuple with status ok");

  // 2. Multiple invocations tracking
  const res2 = fn(10, 20);
  assert.strictEqual(res2, 30, "spy should return second invocation result");
  assert.strictEqual(fn.callCount, 2, "spy.callCount should be 2");
  assert.deepStrictEqual(fn.calls, [[2, 3], [10, 20]], "spy.calls should record all calls");
  assert.deepStrictEqual(fn.returns, [5, 30], "spy.returns should record all return values");

  // 3. Error capturing in results
  const failingFn = spy((msg) => {
    throw new Error(msg);
  });
  assert.throws(() => failingFn("fail"), /fail/, "spy should propagate thrown error");
  assert.strictEqual(failingFn.called, true, "failingFn.called should be true");
  assert.strictEqual(failingFn.callCount, 1, "failingFn.callCount should be 1");
  assert.strictEqual(failingFn.results.length, 1, "failingFn.results should contain one record");
  assert.strictEqual(failingFn.results[0][0], "error", "failingFn.results status should be error");
  assert.strictEqual(failingFn.results[0][1].message, "fail", "failingFn.results should contain the thrown error object");

  // 4. nextResult overrides return value for next single call
  const multiplier = spy((x) => x * 2);
  multiplier.nextResult(999);
  const val1 = multiplier(4);
  assert.strictEqual(val1, 999, "multiplier should return nextResult override value");
  const val2 = multiplier(4);
  assert.strictEqual(val2, 8, "multiplier should return standard implementation result on subsequent calls");

  // 5. nextError causes next single call to throw specified error
  const errSpy = spy((x) => x + 1);
  const customErr = new Error("injected error");
  errSpy.nextError(customErr);
  assert.throws(() => errSpy(1), /injected error/, "errSpy should throw injected error on next call");
  assert.strictEqual(errSpy(1), 2, "errSpy should resume standard implementation after nextError");

  // 6. spyOn wraps an object method and restores original implementation
  const calculator = {
    multiply(a, b) {
      return a * b;
    },
  };
  const spyCalc = spyOn(calculator, "multiply");
  assert.strictEqual(calculator.multiply(3, 4), 12, "spyOn should invoke wrapped method");
  assert.strictEqual(spyCalc.called, true, "spyCalc.called should be true");
  assert.deepStrictEqual(spyCalc.calls, [[3, 4]], "spyCalc.calls should record arguments");
  spyCalc.restore();
  assert.strictEqual(calculator.multiply(3, 4), 12, "original method should work after restore");

  // 7. Reset clears recorded state
  fn.reset();
  assert.strictEqual(fn.called, false, "spy.called should be false after reset");
  assert.strictEqual(fn.callCount, 0, "spy.callCount should be 0 after reset");
  assert.deepStrictEqual(fn.calls, [], "spy.calls should be empty after reset");
  assert.deepStrictEqual(fn.returns, [], "spy.returns should be empty after reset");
  assert.deepStrictEqual(fn.results, [], "spy.results should be empty after reset");

  console.log("All contract assertions passed successfully.");
}

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