Repository navigation
Conversation
- run the spec/**/*.test.ts regression files again (lost in #280) - drop inline 'type' import modifiers so the typings parse on TypeScript < 4.5 - import 'util' instead of 'node:util' (Node < 14.18 compatibility) - use registered symbols (Symbol.for) so duplicate package copies interoperate - add a 'configure' context symbol (runtime support follows) - remove the unused src/api/Constants.ts Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Replace the node/recorder model with an explicit SubstituteState per substitute (root or cached auto-substitute): append-only received-call records indexed by member, configured substitutions kept apart from them, an optional mimicked instance, and a cache of auto-substitutes keyed by (kind, member, arguments). Thin proxies translate operations onto it: real use, setup chains, assertion chains and a configure view. Existing specs updated where a fix-spec decision changes behaviour: - RecordedArguments.spec: argument matching is one-directional (D3) - received.spec (#18): a bare add(Arg.all()) is a setup, not a call (D3) - issues/178: received(3).subSection fails both ways, so it throws synchronously; an ambiguous case keeps the deferred report (D9) - clearReceivedCalls.spec: asserts behaviour instead of the removed recorder internals Recorder.spec and RecordsSet.spec are removed with the classes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Add one regression test per audit finding (named with its id) under spec/regression/fixes/, plus tests for the decisions that add or change behaviour (D2 auto-substitute caching, D5 configure, D9 deferral, D11 string assertion forms, D12 mimick, D13, D14, D16-D19) and for two copies of the package interoperating (G:RG-8). Engine changes found while testing: - every proxy target carries the printer, because util.inspect inspects the target of a proxy instead of calling its traps - only the call-site frame is captured per call, which halves the cost of a call (D19) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
After sub[mimick](instance), reading a member that the instance does not have now returns undefined, as on the instance itself. The substitute keeps an auto-substitute only where it needs one: the string received/didNotReceive forms, members with configured calls, and members configured through nested setups. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… spec output - Add an "exports" map with a generated native ES module entry (dist/index.mjs + dist/index.d.mts, written by packaging/build-esm.js), so `import Substitute from '@fluffy-spoon/substitute'` is the Substitute class under native ESM and TypeScript node16/nodenext/bundler. CommonJS, "main"/"types", package.json and deep imports of dist/ files keep working. - Build before packing (prepack), so npm pack / npm publish always ship a fresh dist/ (G:PK-3). - Compile the specs into dist-spec/ (npm run build:spec), so npm test never leaves dist/ in an unpublishable state (G:PK-3). - Sync package-lock.json to 2.0.1 (G:PK-4). - engines.node stays >=10: the packed build was smoke-tested on Node 10.0.0 to 26 (CommonJS) and 12.17.0+ (ESM); Node 8 lacks util.isDeepStrictEqual (G:PK-2). - publishConfig pins the npm registry; packaging/dist-tag.js computes the npm dist-tag for a release; better keywords; volta pin moves to Node 24. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…:test check - The pretest script (npm run install:local) packs the repository root like npm publish does and installs the tarball with --no-save; the runners import '@fluffy-spoon/substitute' instead of ../../../src (G:CI-2). - Strip NODE_TEST_* from the environment of the nested runners. A nested `node --test` inherited NODE_TEST_CONTEXT and exited 0 although its test failed, so the node:test check failed on Node 20.11+ (G:CI-2). - Accept the runners' reports for a synchronous failure as well as for an assertion thrown on process.nextTick, and match the exception name and message separately (ava and node:test print them apart). - Update the runners (ava 6.4, jest 30, mocha 12, vitest 5, tsx, ts-jest, TypeScript 5.9) so the checks run on Node 22, 24 and 26; mocha 10 failed to start on Node 26. This also removes the critical/high audit findings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…rs; fix publishing - Node CI: run on push and pull_request (and as a reusable workflow) on Node 22, 24 and 26 instead of 18/20/21, and run `npm run test:types --if-present`. - New compatibility job: the compatibility checks against the packed package (G:CI-2). - New minimum-node job: packs the package and smoke-tests it on MINIMUM_NODE_VERSION (10.0.0, = engines.node) and on 12.17.0 for the ES module entry (G:PK-2). - Publish: trigger on `published` releases, run the full CI workflow first, check that the release tag matches package.json, publish stable versions as `latest` and prereleases as `beta`, with provenance. - Remove the GitHub Packages job. GitHub Packages only accepts packages whose scope is the repository owner (@ffMathy), so it could never host @fluffy-spoon/substitute and failed every release (G:CI-1). - CodeQL: action v4, drop the obsolete HEAD^2 checkout, explicit permissions. Dependabot also watches compatibility-checks/. The bug report template asks for the module system and the test runner. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
packaging/package.test.js runs with `npm test`. It packs the repository like npm publish does (starting from a stale dist/), installs the tarball into a fresh consumer project and checks: - G:PK-3: the tarball has the entry points and no spec/stale output; the spec build goes to dist-spec/. - DOCS:ESM: the default import works under native ESM and in TypeScript (node10, node16, nodenext, bundler); require, deep imports and package.json still work. - G:PK-4: package-lock.json version = package.json version. - G:PK-2: engines.node = the version the minimum-node CI job tests. - G:CI-1 / CI:dist-tag: publishing only targets npm, tag logic. - G:CI-2: nested node --test runs report failures; CI runs the compatibility checks against the packed build. - CI:matrix: supported LTS lines and the type tests. CONTRIBUTING.md (linked from the README, previously a 404) documents install, build, test, test:types, the compatibility checks, CI and the release process. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
- One rule for the setup methods (T:TY-2, G:RG-4): `.returns` / `.throws` / `.mimicks` / `.resolves` / `.rejects` are offered unless the value they are accessed on (property type or return type) has a member with that name; the symbol forms are always offered. Checks are non-distributive for the method types, so union return types keep a single `mimicks` (T:TY-1). - D11: `sub.received` / `sub.didNotReceive` are only offered when T has no public or private member named received, didNotReceive, returns, throws, resolves, rejects or mimicks; the symbol forms are always available, including on SubstituteOf<T> for a generic T (T:TY-3, G:RG-3, T:TY-14). - D12: `mimick` is symbol-only (`sub[mimick](instance)`) (T:TY-5). - D5: `sub[configure]()` returns a view whose members only expose the setup API. - Overloads: up to 8 overloads in one bivariant inference step (T:TY-11), zero-parameter overloads anywhere (T:TY-10), `(...args: unknown[])` (T:TY-13), positional signatures before the Arg.all() ones. - Optional members (T:TY-7), index signatures next to named members (T:TY-8), members returning `never` (T:TY-12), `then` typed `never` and `toJSON` without setup API (T:TY-16, D20). - Export SubstituteException from the index through a public interface, so the typings do not reach the internals or @types/node (G:RG-9). - overlap.spec.ts: use the string received/didNotReceive forms through `any`, since D11 no longer offers them in the typings for these types. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
- spec-types/: fixtures type-checked by `npm run test:types` (strict, and spec-types/loose without strict), one file per finding; must-fail lines use `@ts-expect-error`. `npm test` runs them first. - spec-types/min-ts: `npm run test:types:min-ts` builds dist/ and type-checks a consumer of the built typings (resolved through package.json, without @types/node) with an old TypeScript installed by npx (default 3.6, the measured minimum; other versions as arguments). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
With the D9 engine change, the old scenario fails synchronously. Three calls followed by a property-style received(2) can only be reported on process.nextTick, so the runners are still checked for that path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Editors then show the documentation of received, didNotReceive, configure, mimick and the setup methods on hover. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
sub[returns](1) (and [throws], [resolves], [rejects], [mimicks]) on a root substitute, or on its configure() view, used to read a member keyed by the symbol and return an auto-substitute, so nothing was configured. It now throws a SubstituteException usage error that points to member/call setups and to sub[configure]() for a substitute returned by a configured call. The string names stay ordinary members (D11). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
A failing assertion on a member with hundreds of received calls produced a message with one or two lines per call. The listing now stops after 50 entries with "› … and N more", using the listing's own marker. The counts in the expectation line still cover every call. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The colour decision now follows Node's own policy more closely:
FORCE_COLOR still wins ('0'/'false' off, anything else on); otherwise a
non-empty NO_COLOR or NODE_DISABLE_COLORS, or TERM=dumb, turn colours off;
otherwise stdout must be a TTY. The decision is a pure function,
shouldUseColors(env, stdoutIsTTY), so it is tested without a real TTY.
The existing A:RT-14 test now also clears NODE_DISABLE_COLORS and TERM, so
its TTY case does not depend on the environment the tests run in.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Two hints, after the listing of received calls: - When a method assertion finds too few calls and the member was also read without being invoked: "@Substitute.m was read N time(s) without being called; reading a method does not count as calling it." The same hint is given when a member that was read and invoked fails a property-style check with a count above its calls. - When didNotReceive().m(...) fails on a member that was only read, for example passed as a callback (the A:RT-3 residual forced by D9): the hint explains that the assertion is decided when the member is read and that sub[clearReceivedCalls]() after the arrange step resets the reads. SubstituteException's mismatch description gains optional `explanation` (continues the expectation line) and `hints` (lines after the listing). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… method Amended D9: a property-style assertion such as `sub.received(2).m` on a member that has only ever been invoked is reported on process.nextTick when it is not invoked. Its message said "Expected to receive 2 property reads matching m, but received none." and nothing else. It now continues with "m was never read as a property; it was called 1 time as a method. To assert calls, invoke it: sub.received(2).m(...)", with the path of nested substitutes (sub.logger.received(2).info(...)). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…utated arguments
Resolving a call compared it against every literal substitution of the
member, and configuring one compared it against all earlier ones, so 8000
literal setups plus 8000 calls took about 4.6 s. All-literal substitutions
are now indexed per member by a stable fingerprint of their arguments:
primitives by value, functions, substitutes and symbols by identity, and an
object only as "an object", so the key never goes stale when an argument
object is mutated after the setup (literal arguments are compared as they
are when the call is made, D15). The deep-equal confirmation and the D4
precedence (most specific class, then most recent) are unchanged. The same
workload now takes about 0.17 s. Literal setups with object arguments still
compare against the setups with the same primitives in the same places.
The auto-substitute cache looked entries up by a structural fingerprint
only, which goes stale when an argument object is mutated: after
api.get(request).body.returns('ok') and request.headers = {...},
api.get(request).body was a new auto-substitute (D2). Entries are now also
found by the identity of the argument objects.
The ratio test 'the cost of a call does not grow' now takes the best of
three runs and compares 2000 with 32000 calls against a bound of 48x
(linear is about 16x, quadratic about 256x), so CPU load does not fail it.
New: 8000 literal setups plus 8000 matching calls in under 1 s (best of
three, directly and through configure()) and a growth check for them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Every example now compiles under strict TypeScript and does what the text says (the old snippets mostly failed to compile or crashed at runtime). - Fix the malformed badge HTML and the requirements: Node.js 10 for CommonJS, 12.17 for the ES module entry point, TypeScript 3.6. - Document importing (CommonJS, ES module default and named imports), sequences that repeat their last value, promises on properties, mimicks, the Arg.any type strings, Arg.all() for the rest of the arguments, the .not matchers, match order and precedence, configure(), partial mocks with [mimick](), auto-substitutes and nested members, received(count) validation, property checks, what counts as a call, clearReceivedCalls, SubstituteException, the assertions reported on process.nextTick, the name-conflict rules for TypeScript and JavaScript, the symbol API, special members, typing limitations and test runners. - Replace the Substitute.disableFor section, which described an API that no longer exists. - Link the migration guide, the changelog and CONTRIBUTING.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Covers npm latest moving from 1.208.0 to 2.x, the Node.js and TypeScript minimums, the removed APIs (Substitute.disableFor, clearSubstitute and ClearType, the string mimick(instance)) with their replacements, the symbol API and the name-conflict rules, and the behaviour changes: sequences repeating their last value, cached auto-substitutes and nested checks that really check, matcher calls being setups, match order, configure(), what counts as a call, checks never running setups, received(count) validation, matchers and messages. Also the ES module default import, the exports map and the moved deep import paths. Each section says which old versions it applies to; the "after" examples are checked like the README's. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Keep a Changelog format. The 2.0.1 entry summarises the fixes, changes, additions and removals since 2.0.0-beta.4 in user terms; the beta entries are reconstructed from the git history. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
`npm run test:docs` builds the package, then spec-docs/check.js extracts every typescript and js code block from README.md, MIGRATION.md and CHANGELOG.md, type-checks the TypeScript ones under strict against the built package (resolved through package.json and its exports map, like an installed copy) and runs each block in its own Node.js process. Examples state what they do in comments that the check enforces: `// prints <output>` must print exactly that, and `// throws <Name>` must throw. Any other output, exception, uncaught exception or unhandled rejection fails the check. HTML comment directives share setup code between blocks (name=/uses=), mark ES modules, compile-only and skipped blocks, an expected uncaught exception, and an error message text that must match. Relative links and #anchors are checked too. spec-docs/self-test.js runs the check on fixtures/broken.md, whose blocks and links are broken on purpose, and fails unless each problem is reported. The whole run takes about 10 seconds. CI runs it in the test job. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tion (D10, D11) A call of the string `received` / `didNotReceive` with an Arg matcher among its arguments was always taken as a setup (D3) of a member with that name, so `sub.received(Arg.any()).add(1)` silently configured something and the "assertion" passed, and `sub.didNotReceive(Arg.any()).value = 1` threw "Property assignments cannot be configured". By D11 such a call followed by a member access or an assignment is the assertion API: received() now reports the invalid count (D10) and didNotReceive() asserts, ignoring its arguments as it does without matchers. Followed by a substitution method, and inside a configure() view, it is still a setup of the user's member. Found by porting engine A's D11 test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…tion A failed `sub.received(1).isEnabled = false` listed the assignments under "All property or method calls to @Substitute.isEnabled received so far:". The listing of an assignment assertion only contains assignments, so it is now headed "All property assignments to ... received so far:". The other headings are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… setups Code under test that reads a member called returns (or throws, resolves, rejects, mimicks) on an unconfigured call result gets the setup method, so calling it reconfigures the substitute. Configuring the value first avoids that. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…e (R3-ADV-5, E6) The jest check accepted "type: 'CallCountMismatch'", which is part of Node.js's fatal-exception dump, so it passed when jest crashed. The jest fixture now has a passing test before and after the failing one, and the check requires jest's report: the failure of that test with "Tests: 1 failed, 2 passed, 3 total". jest 30 on Node.js 22 cannot attribute an exception thrown from a microtask to the running test (Node.js 22 loses the AsyncLocalStorage store there), so on Node.js 22 the check also accepts jest's "Test suite failed to run" for the file, with "Tests: 3 passed, 3 total". Every runner's output must be free of a Node.js crash, and jest's and vitest's "called at" lines must name the TypeScript source lines (E4). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
The feature check for AggregateError read globalThis, which Node.js 10 does not have, so requiring the package threw a ReferenceError there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ith keyof T `T[P & keyof T]` intersects each key with the whole key union of `T`, which distributes over hundreds of keys for lib.dom types every time a member type is computed (TypeScript computes every member of a substitute on the first member access). `T[Extract<P, keyof T>]` is a single lookup, and in generic code it still resolves to the constraint's member type on assignment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Hashing a string longer than 4096 characters computed every sampled position through sampledPosition, which made 10k calls with 5000-character strings slower than hashing them in full before. The prefix, the strided samples and the suffix now have loops of their own (the same positions). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…T33/T34 Both are pre-existing (they fail the same way at 6cb1c22) and are recorded with the way around them, which is checked on TypeScript 3.9 to 5.9: - assigning a plain function to a callable member in the assertion view (`button.received().onClick = handler`): the member's type there also has the `Arg.all()` call signatures. Use `(button.received() as Button).onClick = handler`. - in generic code, checking a set of a property typed as the type parameter itself (`current: T`): use `(holder.received() as Holder<T>).current = value`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…of reading members from T Members<T> now picks `T` itself in generic code: it is an indexed access whose key is `any` for the plain object type (`Pick<T, keyof T>`, reached through a string index signature), and TypeScript leaves out an `any` branch when it cannot decide `MembersKind<T>` for a type parameter. Indexing the mapped object type gives `T['total']` there, which accepts the constraint's member type, so the per-member `T[Extract<P, keyof T>]` lookup is no longer needed. Concrete types are mapped as before (a type with a string index signature directly, anything else through `Pick<T, keyof T>`, a union as one object). Instantiations for `Substitute.for<Document>()` plus 5 setups/checks: 115,056 -> 112,006 (6cb1c22: 107,819). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…equire() (P2)
CommonJS code that require()s the package, bundled with @rollup/plugin-commonjs on
default options while the package stays external (also Vite 7 and older SSR builds),
gets the Substitute class instead of the exports object: the plugin turns require()
into a default import, which Node.js resolves to the ES module entry.
P29 keeps that behaviour and documents it with its workarounds. test/bundlers.ts now
bundles bundlers/require-entry.mjs, which imports CommonJS code that require()s the
package, and checks that each documented setting gives the exports object:
commonjs({ esmExternals: true }), commonjs({ esmExternals: [the package] }), bundling
the package with Rollup, Vite's ssr.noExternal, and Vite 8's default externals. It also
checks that each bundle really keeps the package external or really bundles it, and
that the caveat itself still holds, so the docs are revisited when the tools change.
A packaging test (P2) makes sure the compatibility checks keep covering each setting,
and CONTRIBUTING describes the new check.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ery smoke-tested Node.js (R3TD-5) CONTRIBUTING and the header of packaging/smoke/deep-imports.js said that deep imports fail on 12.17 to 12.22, all of 13.x, 14.0 to 14.18 and 16.0 to 16.8. Measured with the packed package, they fail only on 12.17 to 12.19, 13.x and 14.0 to 14.12; on 12.20 to 12.22, 14.13 to 14.18 and 16.0 to 16.8 the form without .js works, as MIGRATION says. packaging/smoke/deep-import-support.js now holds that table (15.x, which nobody checked, is left out), and deep-imports.js checks it on the Node.js version it runs on: the forms that should work must work, the others must fail with Node.js's error. The minimum-node CI job runs it on all four old versions it installs, not only on 10.0.0. It passes on all 26 versions from 10.0.0 to 26.13.1. deep-imports.mjs says that its forms with an extension need 14.19+ or 16.9+. The R3TD-5 packaging test pins the table to the measured results and checks that CONTRIBUTING, MIGRATION and both smoke files state the same ranges. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
A method reference invoked later is a call made where it is invoked (E1), the adjacency fallback applies only when neither operation has a frame, and promise-job async frames are ignored (E2), a structural argument hash with bounded cost per argument, also for cycles, native errors, long strings and wide values (E3), "called at" text formatted by V8/Node.js with source maps, structured frames read from a separate capture (E4), Error.prepareStackTrace never changed for the process (E5), deferred reports thrown from the queueMicrotask captured at load (E6), and the runtime's own util.promisify.custom and util.inspect.custom (E7). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Setups and checks through a type parameter's constraint (T33), the
optional-callback limitation of the assertion view pinned with its
workarounds (T34), inverse documentation at Arg.is.not / Arg.any.not
call sites (T35), unions whose variants declare null-only members no
longer reduce to never (T36), substitutes of function types and
callable interfaces configured and checked through their calls (T37),
and Arg.any('undefined') only fits parameters that accept undefined
(T38).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Compatibility checks that bundle CommonJS code which require()s the package with each documented setting, and pin the default @rollup/plugin-commonjs caveat (P29), and a version-aware deep-import smoke test whose table CONTRIBUTING, MIGRATION and the smoke files must agree with, run on every Node.js version the minimum-node job installs (P30). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…fixes
- Which calls lead to a setup or a check: calls through a method reference
handed to the code under test, and calls from promise jobs, are kept (E1, E2);
position alone decides only when neither side has a stack frame; the library
restores Error.prepareStackTrace exactly (E5). Checked examples for both.
- "called at" lines keep source maps and custom formatters (E4).
- Assertions that fail later: reported from a microtask; how jest 29/30, vitest,
ava, mocha, node:test and plain Node.js report it; fake timers (E6, R3-ADV-5).
- Performance: the bounded argument hash, its limits, and the shapes that can
still share a hash (E3); the bounded nested-matcher search (D27 limits).
- Special members: the runtime's own util.promisify.custom (E7).
- Importing / Imports and packaging: the Rollup commonjs external require()
caveat and its workarounds (P2).
- TypeScript: function-type substitutes (T37), constrained generics (T33),
unions with null-only members (T36), Arg.any('undefined') (T38), and the
remaining limitations with checked workarounds (optional callbacks in checks,
callable members in checks, Arg.any.not(type), T | undefined substitutes,
TS 3.6-3.8 nullable members in generic code). Removes the stale
@ts-expect-error that made test:docs fail.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…er operation (E8, E11) R4-ADV-1 (E8): a read that is invoked later always takes the call site of the invocation, so the frame of the call it becomes is where it was invoked, also when the code under test invokes a method reference on the substitute again (Reflect.apply(fetch, api, [id]), an uncurried Function.prototype.call, a wrapper). The `this === proxy` shortcut is gone; a setup of the value the code under test got back no longer erases its call. E11: the structured first frame is read from the record's own capture with a prepareStackTrace that throws, which V8 does not cache, so the capture still formats its text normally later. There is no second capture per operation, and the traps capture the call site themselves, only for operations that are recorded (each frame between the capture and the trap costs). Operations that record nothing read a throwaway capture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
R4-ADV-4: Node.js compares an object as an error (name, message, cause, errors) when isNativeError(value) || value instanceof Error, unless its toString tag is [object Object]. The hash now uses the same predicate (whether error-like objects count is found out once at load), so an Error.prototype object with the tag 'Error' hashes like the native error it is deep strictly equal to, and objects tagged [object Object] hash by their keys, which also covers Node.js 24's asymmetric comparison of such native errors. The E3 property test generates error-like objects and native errors tagged [object Object] as well, and prints the values when a pair disagrees. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…ups again (T39, R4TD-1) A member whose type is a union of function types with different return types (`Cat | Dog` methods, `this`-returning methods in unions, union-typed callbacks) is expanded per variant since round 4, so a call returned a union of setup APIs and `.returns()` / `.resolves()` / `.mimicks()` / the configure view took `never`. Each variant keeps its own signatures, but when the variants' overloads at the same position return different types, every variant's call result is now computed from the union of those return types. The choice is made lazily inside the call's return type, so type-checking cost is unchanged (DOM probes and the union of all lib.dom elements check as fast as at ec64181), and in generic code it falls back to the constraint's own overload (T33 unchanged). Generic code whose constraint is such a union is pinned in limitations.ts with its workaround (cast to SubstituteOf<Constraint>). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… (E9) R4-ADV-2: - the search for nested matchers visits each container once per argument (a visited set next to the budget), looks at 4,096 items and keys per argument at most, and remembers (weakly) the objects it found too wide to search, so a lookup table passed again and again is listed once; - within one hash, the shallow part of a wide object, Map or Set is computed once however many values refer to it, and objects with more than 4,096 keys (Maps and Sets with more entries) are hashed by their size only; - a call computes the structural hash only when a literal substitution could match it: the same objects as a literal substitution answer by identity when no literal substitution is more recent, and a call whose primitive arguments are those of no literal substitution skips the index. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
R4-ADV-3: the mocha, ava, vitest and node:test fixtures get passing tests
before and after the failing one (mocha and ava a second file as well), and
the checks assert what really happens:
- mocha reports the test as passed, then as failed ("Uncaught"), and aborts
the run: later tests, in the file and in later files, do not run;
- ava reports the test as passed, "Uncaught exception in <file>" and "<file>
exited with a non-zero exit code"; the unfinished tests of that file are not
reported; other files are;
- vitest and node:test run and report every test, and fail the run with the
error (vitest names the last test that ran).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…objects is searched" (E9) An argument looks at 32,768 items and keys in all at most (not 4,096), so that an array of 1,000 objects with a few keys each is still searched completely, as the README says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…peScript version (T40, R4TD-2, R4V-1) The direct setups compile with TypeScript 4.8 and newer. With older versions the typings cannot avoid two limitations, now pinned and documented in the fixture header from cross-version harness runs (3.6 to 5.9 and 7.0): - 3.6 to 4.7: calls of optional methods and of `fn | undefined` members are not callable with a constrained type parameter (`sub.reset().returns()`); - 3.6 to 3.8: properties whose type includes null/undefined have no setup API, with a constrained type parameter and in an interface instantiated with any type parameter (`maybe?: T`, `orNull: T | null`). The configure view and the checks work on every version; the min-ts consumer now checks those workarounds with TypeScript 3.6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…neric code (T41, R4TD-3)
With `T extends { [key: string]: number; port: number }`, `sub.timeout.returns(5)`
and `sub[configure]().timeout.returns(5)` took no value: the setup API was computed
from `T[string]`, and TypeScript never lets a value be written to `T[string]` of a
type parameter. For keys that exist only through a string index signature, the
member is now computed by a conditional type over the members type, which
TypeScript resolves with the constraint when the member is used, so the setups
take the index signature's type (also for union-typed index signatures). Concrete
types are unchanged.
Checking a set of such a key (`sub.received().timeout = 5`) still does not compile
on any TypeScript version (TS2339: a write through an index signature of a generic
type); the fixture pins it with the workaround `(sub.received() as Settings).timeout = 5`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
… exports (PK4-2) With vitest's server.deps.inline and deps.interopDefault: false, the default import of dist/index.js is an object with only some of the exports, and the namespace holds every named export plus that object as its default. The wrapper required default === Substitute and threw "could not read the exports" although the namespace was complete. The generated dist/index.mjs now accepts a view when every named export has the type it has at build time, ignoring the view's default, and exports the named export Substitute (the default export found at build time) as its default. The packaging test simulates the new shape and a namespace with undefined values; the compatibility checks run the inlined vitest exports test with deps.interopDefault: false too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…agerly (GenericKind comment) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…/ (PK4-4) packaging/package.test.js deleted dist/, wrote a stale dist/spec/Stale.spec.js and packed the working tree, so an interrupted npm test left no dist/ at all, although CONTRIBUTING says npm test never writes into dist/. The checks now copy the working tree (uncommitted changes included; without dist/, dist-spec/, .git, other dot-directories and node_modules/, which is linked instead) to a temporary directory, put the stale dist/ there and pack that copy. A new test compares a snapshot of the working tree's dist/ before and after packing. CONTRIBUTING describes the temporary copy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…d import (PK4-1) ES module code bundled into CommonJS output while the package stays external (Rollup format 'cjs', esbuild format 'cjs' with packages external, webpack with a commonjs external, a Vite SSR build with CommonJS output) require()s the package at run time, and its default import is module.exports, the exports object, not the Substitute class. compatibility-checks/test/bundlers.ts now bundles bundlers/named-entry.mjs (named import only) with each of them and checks that it works, checks Rollup's output.interop: 'auto' workaround for the default import, and checks that the caveat itself still holds, so the README and MIGRATION wording is updated when the tools change. A packaging test makes sure these checks stay in place. CONTRIBUTING describes them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…on return types (T39) The T39 call results took the position of the overload in the 8-slot expansion as a type argument. Identical overloads in several positions then gave distinct signature types, so their intersection no longer collapsed. For a rest parameter typed as a union of tuples (`log(...args: [string] | [string, number])`) every position is a union, and the combinations multiplied: type-checking such a substitute took minutes, and TypeScript 5.4 ran out of memory. The union of the variants' return types is now keyed by the overload's parameter list (as TypeScript matches signatures of a union of function types), so identical positions give identical types again. The T39 fixture now includes such a member, so a regression makes `npm run test:types` hang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
E8 (R4-ADV-1): a method reference invoked by the code under test is a call made where it is invoked, decided by frames, not by this === proxy. E9 (R4-ADV-2): bounded cost per call for wide and shared arguments. E10 (R4-ADV-4): error-like objects hash as Node.js compares them. E11: one call-site capture per recorded operation; hot path back to round-3 speed. E12 (R4-ADV-3): compatibility checks pin each runner's behaviour around a deferred report. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
T39 (R4TD-1): members typed as a union of function types get the setup API again, with the union of the variants' return types. T40 (R4TD-2, R4V-1): optional and nullable members in generic code are pinned per TypeScript version, with the configure-view workaround. T41 (R4TD-3): keys that exist only through a constraint's string index signature can be configured in generic code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
P31 (PK4-2): the ES module entry decides completeness by the named exports, so vitest with deps.interopDefault: false works. P32 (PK4-4): the packaging checks pack a temporary copy of the repository and never write into the working tree's dist/. P33 (PK4-1): a compatibility case for CommonJS output with the package external and the named import. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
…fixes - Importing (PK4-1, PK4-3, PK4-2, P33): prefer the named import; document CommonJS output with the package external (Rollup/Vite 5-7 cjs for any source; esbuild, webpack, Rolldown, Vite 8 for .mjs/type:module sources; Rollup output.interop: 'auto') and ts-node's ESM loader; qualify "Bundlers give the same exports"; vitest deps.interopDefault: false is checked. - Which calls lead to a setup (E8): method references invoked with the substitute as `this` (Reflect.apply, fn.call, wrappers) are kept; builtins (Reflect.apply/call/apply/bind have no frame, Array.map does). Checked example. Stack-chain rule without the wrong version (R4TD-4). - How arguments are compared (E10): error-like objects with the Error tag, [object Object]-tagged errors, Node 24+ order dependence. Checked example. - Matchers inside objects (E9): shared containers searched once, 32,768 items and keys per argument, objects once wider than 1,024 keys remembered. - Assertions that fail later / Test runners (R4-ADV-3, E12): exact mocha (stops the run) and ava (ends the file's worker) behaviour, plus jest, vitest and node:test; drop "without crashing". - Typing limitations, "In TypeScript" and MIGRATION "TypeScript" (R4V-1, R4TD-2, R4TD-3, T39-T41): TS < 4.8 optional/nullable members in generic code, union constraints, index-signature set checks, rest parameters typed as tuple unions; T41 index-signature setups; T39 union return types. Checked examples. - Performance (E9, E11): re-measured on Node 22 against the build; 4,096 cap, identity-first lookup, remaining slow shapes (unreadable arguments, matcher setups inside objects about 9 s, which 6cb1c22 and ec64181 share). - CHANGELOG: T39 fix relative to 2.0.0-beta.4, T41, E8, E9, E12, PK4-2, CommonJS-output and ts-node note. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Work in progress. This PR fixes the problems found in an audit of the unreleased 2.0.1 on
master, before it is published. It covers the runtime engine, the typings, packaging/CI and the docs.Merged so far
spec/**/*.test.tsregression files run again.typeimport modifier, so the typings parse on TypeScript < 4.5.utilinstead ofnode:util.Symbol.for(...).src/internals/rewritten around per-substitute state):received(n)counts throwreturns/throws/… are assertions.call/.apply/.bindworksub[configure]()view to re-configure overlapping setupssub[mimick](instance)implementedArg.all()after leading arguments matches the restArg.any('object')excludesnull;Arg.isvalidates its predicate, and a throwing predicate counts as a non-matchFORCE_COLORError.stackTraceLimit = 0.mimicks()on methods returning unions or booleansSubstituteOf<T>[configure]()typedSubstituteExceptionexportednpm run test:types) and a TypeScript 3.6 minimum checkexportsmap and ESM entry, so the default import works under native ESMprepackbuild; specs compile todist-spec/enginesverified on Node 10latest/betadist-tags, provenance, no broken GitHub Packages jobCONTRIBUTING.mdStill in progress
[returns], capped call listings, extra hints in messages,NODE_DISABLE_COLORS/TERM=dumb, a literal-setup index.npm run test:docs),MIGRATION.md(1.x → 2.x, beta → 2.0.1) andCHANGELOG.md(closes Update documentation #234).🤖 Generated with Claude Code
https://claude.ai/code/session_01KD7sVgSiP9KbiEpaM8wCyt