tinyspy 3.0.2: 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 tinyspy.spyOn 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.spyOn

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:c5097a321f165e7013e103122a1b57bfb4c3ad41eb843dd4be4467a3583a2586","constraints":{"executionContext":"node"},"contract":["spyOn wraps an object method and records calls, arguments, and return values while delegating to original implementation","spyOn accepts a mock implementation to replace method behavior and tracks invocations","spyOn getOriginal provides access to the underlying unspied implementation","spyOn willCall dynamically replaces the method implementation on an existing spy","spyOn getter wraps property getter and tracks property accesses","spyOn setter wraps property setter and tracks assigned values","spyOn restore reverts the object property back to its original descriptor","restoreAll restores all active spies created across objects"],"goal":"verify tinyspy.spyOn in pkg:npm/tinyspy@3.0.2","kind":"HOW","packages":["pkg:npm/tinyspy@3.0.2"],"schemaVersion":1,"symbols":["tinyspy.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":["tinyspy.spyOn"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyspy-spyon",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyspy-spyon",
      "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-spyon",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "Clean-room verification for tinyspy.spyOn 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.spyOn in pkg:npm/tinyspy@3.0.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyspy@3.0.2"
  ],
  "symbols": [
    "tinyspy.spyOn"
  ]
}

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

async function runContract() {
  // 1. spyOn wraps an object method and records calls, arguments, and return values while delegating to original implementation
  const math = {
    add(a, b) {
      return a + b;
    },
  };
  const addSpy = spyOn(math, "add");

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

  const sum = math.add(10, 20);
  assert.strictEqual(sum, 30, "spied method should delegate to original implementation and return result");
  assert.strictEqual(addSpy.called, true, "spyOn.called should be true after call");
  assert.strictEqual(addSpy.callCount, 1, "spyOn.callCount should be 1 after one call");
  assert.deepStrictEqual(addSpy.calls, [[10, 20]], "spyOn.calls should record passed arguments");
  assert.deepStrictEqual(addSpy.returns, [30], "spyOn.returns should record return values");

  // 2. spyOn accepts a mock implementation to replace method behavior and tracks invocations
  const greeter = {
    greet(name) {
      return `Hello, ${name}!`;
    },
  };
  const greetSpy = spyOn(greeter, "greet", (name) => `Hi, ${name}!`);

  const greeting = greeter.greet("Alice");
  assert.strictEqual(greeting, "Hi, Alice!", "spyOn with custom mock should override method behavior");
  assert.strictEqual(greetSpy.called, true, "custom mock spy should be marked as called");
  assert.deepStrictEqual(greetSpy.calls, [["Alice"]], "custom mock spy should track arguments");

  // 3. spyOn getOriginal provides access to the underlying unspied implementation
  const originalGreet = greetSpy.getOriginal();
  assert.strictEqual(typeof originalGreet, "function", "getOriginal should return a function");
  assert.strictEqual(originalGreet("Bob"), "Hello, Bob!", "getOriginal should invoke original behavior");

  // 4. spyOn willCall dynamically replaces the method implementation on an existing spy
  greetSpy.willCall((name) => `Welcome, ${name}!`);
  assert.strictEqual(greeter.greet("Carol"), "Welcome, Carol!", "willCall should replace active mock implementation");
  assert.strictEqual(greetSpy.callCount, 2, "greetSpy should record second call");

  // 5. spyOn getter wraps property getter and tracks property accesses
  const config = {
    _mode: "development",
    get mode() {
      return this._mode;
    },
  };
  const getterSpy = spyOn(config, { getter: "mode" });

  assert.strictEqual(getterSpy.called, false, "getter spy should initially not be called");
  const modeVal = config.mode;
  assert.strictEqual(modeVal, "development", "getter access should return underlying value");
  assert.strictEqual(getterSpy.called, true, "getter spy should be called after property access");
  assert.strictEqual(getterSpy.callCount, 1, "getter spy callCount should be 1");

  getterSpy.willCall(() => "test");
  assert.strictEqual(config.mode, "test", "willCall on getter spy should return mock value");

  // 6. spyOn setter wraps property setter and tracks assigned values
  const store = {
    _item: "empty",
    get item() {
      return this._item;
    },
    set item(val) {
      this._item = val;
    },
  };
  const setterSpy = spyOn(store, { setter: "item" });

  assert.strictEqual(setterSpy.called, false, "setter spy should initially not be called");
  store.item = "first";
  assert.strictEqual(setterSpy.called, true, "setter spy should be marked as called after assignment");
  assert.deepStrictEqual(setterSpy.calls, [["first"]], "setter spy should record assigned values");
  assert.strictEqual(store.item, "first", "underlying setter should have set property");

  // 7. spyOn restore reverts the object property back to its original descriptor
  getterSpy.restore();
  assert.strictEqual(config.mode, "development", "restored getter should revert to original behavior");

  setterSpy.restore();
  store.item = "second";
  assert.strictEqual(store.item, "second", "restored setter should maintain standard behavior");
  assert.strictEqual(setterSpy.callCount, 1, "restored setter spy should not record subsequent changes");

  addSpy.restore();
  assert.strictEqual(math.add(1, 2), 3, "restored method should continue to work");
  assert.strictEqual(addSpy.callCount, 1, "restored method spy should not record subsequent calls");

  // 8. restoreAll restores all active spies created across objects
  const service = {
    step1() {
      return "one";
    },
    step2() {
      return "two";
    },
  };
  const s1 = spyOn(service, "step1", () => "mocked-one");
  const s2 = spyOn(service, "step2", () => "mocked-two");
  assert.strictEqual(service.step1(), "mocked-one");
  assert.strictEqual(service.step2(), "mocked-two");

  restoreAll();
  assert.strictEqual(service.step1(), "one", "service.step1 should revert to original after restoreAll");
  assert.strictEqual(service.step2(), "two", "service.step2 should revert to original after restoreAll");

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

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