frida-test 0.3.2 → 0.4.0

package/src/agent-runtime/expect.ts

@@ -0,0 +1,5 @@
+import { createExpectMatcher, type Matchers } from "./modifiers.js";
+
+export function expect<T>(actual: T): Matchers<T> {
+  return createExpectMatcher(actual);
+}

package/src/agent-runtime/fridaTest.ts

@@ -0,0 +1,9 @@
+import { fn, type AnyFn, type Mock } from "./mock.js";
+import { spyOn } from "./spy.js";
+
+export interface FridaTest {
+  fn(implementation?: AnyFn): Mock;
+  spyOn<T extends object, K extends keyof T>(target: T, key: K): Mock;
+}
+
+export const fridaTest: FridaTest = { fn, spyOn };

package/src/agent-runtime/globals.d.ts

@@ -1,5 +1,7 @@
-type Matcher<T> = import("./matchers.js").Matcher<T>;
-type Spy = import("./matchers.js").Spy;
+type Matchers<T> = import("./modifiers.js").Matchers<T>;
+type Mock = import("./mock.js").Mock;
+type AnyFn = import("./mock.js").AnyFn;
+type FridaTest = import("./fridaTest.js").FridaTest;
 type TestFn = import("./registry.js").TestFn;
 type HookFn = import("./registry.js").HookFn;
 
@@ -10,5 +12,7 @@ declare function beforeEach(fn: HookFn): void;
 declare function afterEach(fn: HookFn): void;
 declare function beforeAll(fn: HookFn): void;
 declare function afterAll(fn: HookFn): void;
-declare function expect<T>(actual: T): Matcher<T>;
-declare function spyOn<T extends object, K extends keyof T>(target: T, key: K): Spy;
+declare function expect<T>(actual: T): Matchers<T>;
+declare function spyOn<T extends object, K extends keyof T>(target: T, key: K): Mock;
+declare function fn(implementation?: AnyFn): Mock;
+declare var fridaTest: FridaTest;

package/src/agent-runtime/globals.ts

@@ -1,6 +1,10 @@
-import { expect, spyOn, type Matcher, type Spy } from "./matchers.js";
+import { expect } from "./expect.js";
+import { fridaTest, type FridaTest } from "./fridaTest.js";
+import { fn, type AnyFn, type Mock } from "./mock.js";
+import type { Matchers } from "./modifiers.js";
 import type { HookFn, TestFn } from "./registry.js";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, it, test } from "./registry.js";
+import { spyOn } from "./spy.js";
 
 declare global {
   function describe(name: string, fn: TestFn): void;
@@ -10,8 +14,10 @@ declare global {
   function afterEach(fn: HookFn): void;
   function beforeAll(fn: HookFn): void;
   function afterAll(fn: HookFn): void;
-  function expect<T>(actual: T): Matcher<T>;
-  function spyOn<T extends object, K extends keyof T>(target: T, key: K): Spy;
+  function expect<T>(actual: T): Matchers<T>;
+  function spyOn<T extends object, K extends keyof T>(target: T, key: K): Mock;
+  function fn(implementation?: AnyFn): Mock;
+  var fridaTest: FridaTest;
 }
 
-Object.assign(globalThis, { describe, it, test, beforeEach, afterEach, beforeAll, afterAll, expect, spyOn });
+Object.assign(globalThis, { describe, it, test, beforeEach, afterEach, beforeAll, afterAll, expect, spyOn, fn, fridaTest });

package/src/agent-runtime/matchers.ts

@@ -1,7 +1,12 @@
-export type Containable<T> = T extends readonly (infer U)[] ? U : T extends string ? string : never;
+import { isMock, type Mock } from "./mock.js";
+
+export type Containable<T> = T extends readonly (infer U)[] ? U : T extends ReadonlySet<infer U> ? U : T extends string ? string : never;
 export type Numeric<T> = T extends number ? number : never;
 
-export interface Matcher<T> {
+export type ErrorClass = new (...args: any[]) => Error;
+export type ErrorMatch = string | RegExp | Error | ErrorClass;
+
+export interface Assertions<T> {
   toBe(expected: T): void;
   toEqual(expected: T): void;
   toBeTruthy(): void;
@@ -12,19 +17,13 @@ export interface Matcher<T> {
   toBeGreaterThan(expected: Numeric<T>): void;
   toBeLessThan(expected: Numeric<T>): void;
   toContain(expected: Containable<T>): void;
-  toThrow(errorMatch?: string | Error): void;
-  toResolve(valueMatch?: unknown): Promise<void>;
-  toReject(errorMatch?: string | Error): Promise<void>;
+  toContainEqual(expected: Containable<T>): void;
+  toThrow(errorMatch?: ErrorMatch): void;
   toHaveBeenCalled(): void;
+  toHaveBeenCalledTimes(expected: number): void;
   toHaveBeenCalledWith(...expected: unknown[]): void;
-  readonly not: Matcher<T>;
-}
-
-export interface Spy {
-  readonly calls: readonly unknown[][];
-  restore(): void;
-  mockReturnValue(value: unknown): Spy;
-  mockImplementation(fn: (...args: unknown[]) => unknown): Spy;
+  toHaveBeenLastCalledWith(...expected: unknown[]): void;
+  toHaveBeenNthCalledWith(n: number, ...expected: unknown[]): void;
 }
 
 const assert = (condition: boolean, message: string): void => {
@@ -55,10 +54,15 @@ const deepEqual = (a: unknown, b: unknown, seen: Array<[unknown, unknown]> = [])
   }
 
   if (a instanceof Set) {
-    const bs = [...(b as Set<unknown>)];
-    if (a.size !== bs.length) return false;
+    // Match each element of `a` against a distinct, not-yet-consumed element of
+    // `b` (rather than `some`), so a value appearing twice in `a` can't both be
+    // satisfied by the same single matching element in `b`.
+    const remaining = [...(b as Set<unknown>)];
+    if (a.size !== remaining.length) return false;
     for (const val of a) {
-      if (!bs.some((other) => deepEqual(val, other, nextSeen))) return false;
+      const index = remaining.findIndex((other) => deepEqual(val, other, nextSeen));
+      if (index === -1) return false;
+      remaining.splice(index, 1);
     }
     return true;
   }
@@ -71,31 +75,40 @@ const deepEqual = (a: unknown, b: unknown, seen: Array<[unknown, unknown]> = [])
   return keysA.every((k) => deepEqual(ra[k], rb[k], nextSeen));
 };
 
-const isSpy = (value: unknown): value is Spy => typeof value === "object" && value !== null && Array.isArray((value as Spy).calls);
-
 function assertIsNumber(value: unknown, label: string): asserts value is number {
   assert(typeof value === "number", `Expected ${label} to be a number`);
 }
 
-function createMatcher<T>(actual: T, negated = false): Matcher<T> {
+export function matchesThrown(caught: unknown, errorMatch: ErrorMatch): boolean {
+  if (typeof errorMatch === "string") {
+    const message = caught instanceof Error ? caught.message : String(caught);
+    return message.includes(errorMatch);
+  }
+  if (errorMatch instanceof RegExp) {
+    const message = caught instanceof Error ? caught.message : String(caught);
+    return errorMatch.test(message);
+  }
+  if (errorMatch instanceof Error) {
+    return caught instanceof Error && caught.message === errorMatch.message;
+  }
+  return caught instanceof errorMatch;
+}
+
+export function describeCaught(caught: unknown): string {
+  return caught instanceof Error ? `${caught.constructor.name}: "${caught.message}"` : JSON.stringify(caught);
+}
+
+function describeErrorMatch(errorMatch: ErrorMatch): string {
+  if (typeof errorMatch === "string") return `a message including "${errorMatch}"`;
+  if (errorMatch instanceof RegExp) return `a message matching ${errorMatch}`;
+  if (errorMatch instanceof Error) return `${errorMatch.constructor.name}: "${errorMatch.message}"`;
+  return `an instance of ${errorMatch.name}`;
+}
+
+export function createMatcher<T>(actual: T, negated = false): Assertions<T> {
   const check = (condition: boolean, message: string): void => assert(negated ? !condition : condition, message);
   const phrase = negated ? "not to" : "to";
 
-  const describeCaught = (caught: unknown): string =>
-    caught instanceof Error ? `${caught.constructor.name}: "${caught.message}"` : JSON.stringify(caught);
-
-  const checkThrown = (caught: unknown, errorMatch: string | Error): void => {
-    if (typeof errorMatch === "string") {
-      const message = caught instanceof Error ? caught.message : String(caught);
-      assert(message.includes(errorMatch), `Expected message to include "${errorMatch}" but got "${message}"`);
-    } else {
-      assert(
-        caught instanceof Error && caught instanceof errorMatch.constructor && caught.message === errorMatch.message,
-        `Expected ${errorMatch.constructor.name}: "${errorMatch.message}" but got ${describeCaught(caught)}`,
-      );
-    }
-  };
-
   return {
     toBe: (expected) => check(Object.is(actual, expected), `Expected ${String(actual)} ${phrase} be ${String(expected)}`),
 
@@ -121,12 +134,23 @@ function createMatcher<T>(actual: T, negated = false): Matcher<T> {
     },
 
     toContain: (expected) => {
-      assert(typeof actual === "string" || Array.isArray(actual), "Expected an array or string");
+      assert(typeof actual === "string" || Array.isArray(actual) || actual instanceof Set, "Expected an array, Set, or string");
       const contains =
-        typeof actual === "string" ? actual.includes(expected as string) : (actual as readonly unknown[]).some((item) => deepEqual(item, expected));
+        typeof actual === "string"
+          ? actual.includes(expected as string)
+          : actual instanceof Set
+            ? actual.has(expected)
+            : (actual as readonly unknown[]).includes(expected);
       check(contains, `Expected ${JSON.stringify(actual)} ${phrase} contain ${JSON.stringify(expected)}`);
     },
 
+    toContainEqual: (expected) => {
+      assert(Array.isArray(actual) || actual instanceof Set, "Expected an array or Set");
+      const items = actual instanceof Set ? [...actual] : (actual as readonly unknown[]);
+      const contains = items.some((item) => deepEqual(item, expected));
+      check(contains, `Expected ${JSON.stringify(actual)} ${phrase} contain an item equal to ${JSON.stringify(expected)}`);
+    },
+
     toThrow: (errorMatch) => {
       assert(typeof actual === "function", "Expected a function");
       let caught: unknown;
@@ -140,104 +164,63 @@ function createMatcher<T>(actual: T, negated = false): Matcher<T> {
       }
 
       if (!threw && result != null && typeof (result as PromiseLike<unknown>).then === "function") {
-        throw new Error("toThrow() received a function returning a Promise; use await expect(fn).toReject(...) instead");
+        // Avoid leaving the caller's promise unhandled while we redirect them to .rejects.
+        void Promise.resolve(result as PromiseLike<unknown>).catch(() => {});
+        throw new Error("toThrow() received a function returning a Promise; use await expect(fn()).rejects.toThrow(...) instead");
       }
 
-      check(threw, `Expected function ${phrase} throw`);
-      if (negated || errorMatch === undefined) return;
-      checkThrown(caught, errorMatch);
-    },
-
-    toResolve: async (expected) => {
-      assert(typeof actual === "function", "Expected a function returning a promise");
-      let caught: unknown;
-      let resolved = false;
-      try {
-        caught = await (actual as () => Promise<unknown>)();
-        resolved = true;
-      } catch (e) {
-        // promise rejected
+      if (errorMatch === undefined) {
+        check(threw, `Expected function ${phrase} throw`);
+        return;
       }
-      check(resolved, `Expected promise ${phrase} resolve`);
-      if (negated || expected === undefined) return;
-      assert(deepEqual(caught, expected), `Expected ${JSON.stringify(caught)} to equal ${JSON.stringify(expected)}`);
+      const matches = threw && matchesThrown(caught, errorMatch);
+      check(
+        matches,
+        threw
+          ? `Expected function ${phrase} throw ${describeErrorMatch(errorMatch)} but got ${describeCaught(caught)}`
+          : `Expected function ${phrase} throw`,
+      );
     },
 
-    toReject: async (errorMatch) => {
-      assert(typeof actual === "function", "Expected a function returning a promise");
-      let caught: unknown;
-      let rejected = false;
-      try {
-        await (actual as () => Promise<unknown>)();
-      } catch (e) {
-        rejected = true;
-        caught = e;
-      }
-      check(rejected, `Expected promise ${phrase} reject`);
-      if (negated || errorMatch === undefined) return;
-      checkThrown(caught, errorMatch);
+    toHaveBeenCalled: () => {
+      assert(isMock(actual), "Expected a mock function created with fn() or spyOn()");
+      check((actual as Mock).mock.calls.length > 0, `Expected mock ${phrase} have been called`);
     },
 
-    toHaveBeenCalled: () => {
-      assert(isSpy(actual), "Expected a spy created with spyOn()");
-      check((actual as Spy).calls.length > 0, `Expected spy ${phrase} have been called`);
+    toHaveBeenCalledTimes: (expected: number) => {
+      assert(isMock(actual), "Expected a mock function created with fn() or spyOn()");
+      const count = (actual as Mock).mock.calls.length;
+      check(count === expected, `Expected mock ${phrase} have been called ${expected} time(s) but it was called ${count} time(s)`);
     },
 
     toHaveBeenCalledWith: (...expected: unknown[]) => {
-      assert(isSpy(actual), "Expected a spy created with spyOn()");
-      const calls = (actual as Spy).calls;
+      assert(isMock(actual), "Expected a mock function created with fn() or spyOn()");
+      const calls = (actual as Mock).mock.calls;
       const match = calls.some((args) => deepEqual(args, expected));
-      check(match, `Expected spy ${phrase} have been called with ${JSON.stringify(expected)} but got ${JSON.stringify(calls)}`);
+      check(match, `Expected mock ${phrase} have been called with ${JSON.stringify(expected)} but got ${JSON.stringify(calls)}`);
     },
 
-    get not(): Matcher<T> {
-      return createMatcher(actual, !negated);
+    toHaveBeenLastCalledWith: (...expected: unknown[]) => {
+      assert(isMock(actual), "Expected a mock function created with fn() or spyOn()");
+      const calls = (actual as Mock).mock.calls;
+      const last = calls[calls.length - 1];
+      const match = calls.length > 0 && deepEqual(last, expected);
+      check(
+        match,
+        `Expected mock ${phrase} have last been called with ${JSON.stringify(expected)} but got ${calls.length > 0 ? JSON.stringify(last) : "no calls"}`,
+      );
     },
-  };
-}
 
-export function expect<T>(actual: T): Matcher<T> {
-  return createMatcher(actual);
-}
-
-export function spyOn<T extends object, K extends keyof T>(target: T, key: K): Spy {
-  const original = target[key];
-  assert(typeof original === "function", `${String(key)} is not a function`);
-
-  const descriptor = Object.getOwnPropertyDescriptor(target, key); // fix: capture descriptor for faithful restore
-  const calls: unknown[][] = [];
-  let impl: (...args: unknown[]) => unknown = (original as (...a: unknown[]) => unknown).bind(target);
-  let returnValue: unknown;
-  let hasReturnValue = false;
-  let restored = false;
-
-  const spy: Spy = {
-    calls,
-    restore: () => {
-      if (restored) return;
-      restored = true;
-      if (descriptor) {
-        Object.defineProperty(target, key, descriptor);
-      } else {
-        Reflect.deleteProperty(target, key);
-      }
-    },
-    mockReturnValue(value: unknown) {
-      hasReturnValue = true;
-      returnValue = value;
-      return spy;
-    },
-    mockImplementation(fn: (...args: unknown[]) => unknown) {
-      impl = fn;
-      hasReturnValue = false;
-      return spy;
+    toHaveBeenNthCalledWith: (n: number, ...expected: unknown[]) => {
+      assert(isMock(actual), "Expected a mock function created with fn() or spyOn()");
+      assert(Number.isInteger(n) && n >= 1, "Expected the call index to be a positive integer");
+      const calls = (actual as Mock).mock.calls;
+      const call = calls[n - 1];
+      const match = call !== undefined && deepEqual(call, expected);
+      check(
+        match,
+        `Expected mock ${phrase} have been called on call ${n} with ${JSON.stringify(expected)} but got ${call !== undefined ? JSON.stringify(call) : "no such call"}`,
+      );
     },
   };
-
-  target[key] = ((...args: unknown[]) => {
-    calls.push(args);
-    return hasReturnValue ? returnValue : impl(...args);
-  }) as T[K];
-
-  return spy;
 }

package/src/agent-runtime/mock.ts

@@ -0,0 +1,131 @@
+// `any` (not `unknown`) so a concretely-typed function - e.g. `fn((a: number, b: number) => a + b)` -
+// is assignable here; with `unknown` parameters, strict function-parameter variance would reject it.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFn = (...args: any[]) => any;
+
+export interface MockResult {
+  readonly type: "return" | "throw";
+  readonly value: unknown;
+}
+
+export interface MockContext {
+  readonly calls: readonly unknown[][];
+  readonly results: readonly MockResult[];
+  readonly instances: readonly unknown[];
+  readonly contexts: readonly unknown[];
+  readonly lastCall: readonly unknown[] | undefined;
+}
+
+export interface Mock {
+  (...args: unknown[]): unknown;
+  readonly mock: MockContext;
+  mockClear(): Mock;
+  mockReset(): Mock;
+  mockRestore(): void;
+  mockImplementation(implementation: AnyFn): Mock;
+  mockImplementationOnce(implementation: AnyFn): Mock;
+  mockReturnValue(value: unknown): Mock;
+  mockReturnValueOnce(value: unknown): Mock;
+  mockResolvedValue(value: unknown): Mock;
+  mockResolvedValueOnce(value: unknown): Mock;
+  mockRejectedValue(value: unknown): Mock;
+  mockRejectedValueOnce(value: unknown): Mock;
+  mockReturnThis(): Mock;
+  mockName(name: string): Mock;
+  getMockName(): string;
+}
+
+export const isMock = (value: unknown): value is Mock => typeof value === "function" && Array.isArray((value as Partial<Mock>).mock?.calls);
+
+export function createMockFunction(defaultImplementation: AnyFn | undefined, name: string): Mock {
+  const calls: unknown[][] = [];
+  const results: MockResult[] = [];
+  const instances: unknown[] = [];
+  const contexts: unknown[] = [];
+  const onceQueue: AnyFn[] = [];
+  let persistentImplementation: AnyFn | undefined = defaultImplementation;
+  let mockedName = name;
+
+  function invoke(this: unknown, ...args: unknown[]): unknown {
+    calls.push(args);
+    contexts.push(this);
+    if (new.target !== undefined) instances.push(this);
+
+    const impl = onceQueue.shift() ?? persistentImplementation ?? ((): undefined => undefined);
+    try {
+      const value = impl.apply(this, args);
+      results.push({ type: "return", value });
+      return value;
+    } catch (error) {
+      results.push({ type: "throw", value: error });
+      throw error;
+    }
+  }
+
+  const mock = invoke as unknown as Mock;
+
+  Object.defineProperty(mock, "mock", {
+    enumerable: true,
+    get(): MockContext {
+      return {
+        calls,
+        results,
+        instances,
+        contexts,
+        lastCall: calls.length > 0 ? calls[calls.length - 1] : undefined,
+      };
+    },
+  });
+
+  mock.mockClear = (): Mock => {
+    calls.length = 0;
+    results.length = 0;
+    instances.length = 0;
+    contexts.length = 0;
+    return mock;
+  };
+
+  mock.mockReset = (): Mock => {
+    mock.mockClear();
+    onceQueue.length = 0;
+    persistentImplementation = undefined;
+    return mock;
+  };
+
+  mock.mockRestore = (): void => {
+    mock.mockReset();
+  };
+
+  mock.mockImplementation = (implementation: AnyFn): Mock => {
+    persistentImplementation = implementation;
+    return mock;
+  };
+
+  mock.mockImplementationOnce = (implementation: AnyFn): Mock => {
+    onceQueue.push(implementation);
+    return mock;
+  };
+
+  mock.mockReturnValue = (value: unknown): Mock => mock.mockImplementation((): unknown => value);
+  mock.mockReturnValueOnce = (value: unknown): Mock => mock.mockImplementationOnce((): unknown => value);
+  mock.mockResolvedValue = (value: unknown): Mock => mock.mockImplementation((): Promise<unknown> => Promise.resolve(value));
+  mock.mockResolvedValueOnce = (value: unknown): Mock => mock.mockImplementationOnce((): Promise<unknown> => Promise.resolve(value));
+  mock.mockRejectedValue = (value: unknown): Mock => mock.mockImplementation((): Promise<unknown> => Promise.reject(value));
+  mock.mockRejectedValueOnce = (value: unknown): Mock => mock.mockImplementationOnce((): Promise<unknown> => Promise.reject(value));
+  mock.mockReturnThis = (): Mock =>
+    mock.mockImplementation(function (this: unknown): unknown {
+      return this;
+    });
+
+  mock.mockName = (newName: string): Mock => {
+    mockedName = newName;
+    return mock;
+  };
+  mock.getMockName = (): string => mockedName;
+
+  return mock;
+}
+
+export function fn(implementation?: AnyFn): Mock {
+  return createMockFunction(implementation, "fn()");
+}

package/src/agent-runtime/modifiers.ts

@@ -0,0 +1,102 @@
+import { createMatcher, describeCaught, matchesThrown, type Assertions, type ErrorMatch } from "./matchers.js";
+
+export interface Matchers<T> extends Assertions<T> {
+  readonly not: Matchers<T>;
+  readonly resolves: AsyncMatcher<Awaited<T>>;
+  readonly rejects: AsyncMatcher<unknown>;
+}
+
+type Promisify<M> = {
+  [K in keyof M]: M[K] extends (...args: infer A) => void ? (...args: A) => Promise<void> : never;
+};
+
+export interface AsyncMatcher<T> extends Promisify<Assertions<T>> {
+  readonly not: AsyncMatcher<T>;
+}
+
+type SyncMethodName = keyof Assertions<unknown>;
+
+type Settled = { ok: true; value: unknown } | { ok: false; value: unknown };
+
+async function settle(awaited: unknown): Promise<Settled> {
+  try {
+    return { ok: true, value: await awaited };
+  } catch (error) {
+    return { ok: false, value: error };
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof (value as PromiseLike<unknown>).then === "function";
+}
+
+function createAsyncMatcher<T>(awaited: unknown, mode: "resolves" | "rejects", negated: boolean): AsyncMatcher<T> {
+  async function invoke(method: SyncMethodName, args: unknown[]): Promise<void> {
+    if (!isPromiseLike(awaited)) {
+      throw new Error(`Expected a Promise for .${mode} but received ${describeCaught(awaited)}`);
+    }
+    const result = await settle(awaited);
+
+    if (mode === "resolves") {
+      if (!result.ok) {
+        throw new Error(`Expected promise to resolve but it rejected with ${describeCaught(result.value)}`);
+      }
+      const sync = createMatcher(result.value, negated) as unknown as Record<SyncMethodName, (...a: unknown[]) => void>;
+      sync[method](...args);
+      return;
+    }
+
+    // mode === "rejects"
+    if (result.ok) {
+      throw new Error(`Expected promise to reject but it resolved with ${JSON.stringify(result.value)}`);
+    }
+
+    if (method === "toThrow") {
+      const [errorMatch] = args as [ErrorMatch | undefined];
+      const matches = errorMatch === undefined || matchesThrown(result.value, errorMatch);
+      const passed = negated ? !matches : matches;
+      if (!passed) {
+        const phrase = negated ? "not to" : "to";
+        throw new Error(
+          errorMatch === undefined
+            ? `Expected promise ${phrase} reject`
+            : `Expected promise ${phrase} reject with a matching error but got ${describeCaught(result.value)}`,
+        );
+      }
+      return;
+    }
+
+    const sync = createMatcher(result.value, negated) as unknown as Record<SyncMethodName, (...a: unknown[]) => void>;
+    sync[method](...args);
+  }
+
+  return new Proxy({} as AsyncMatcher<T>, {
+    get(_target, prop: string | symbol): unknown {
+      if (prop === "not") return createAsyncMatcher(awaited, mode, !negated);
+      return (...args: unknown[]): Promise<void> => invoke(prop as SyncMethodName, args);
+    },
+  });
+}
+
+export function createResolvesMatcher<T>(awaited: unknown, negated = false): AsyncMatcher<T> {
+  return createAsyncMatcher<T>(awaited, "resolves", negated);
+}
+
+export function createRejectsMatcher<T>(awaited: unknown, negated = false): AsyncMatcher<T> {
+  return createAsyncMatcher<T>(awaited, "rejects", negated);
+}
+
+export function createExpectMatcher<T>(actual: T, negated = false): Matchers<T> {
+  return {
+    ...createMatcher(actual, negated),
+    get not(): Matchers<T> {
+      return createExpectMatcher(actual, !negated);
+    },
+    get resolves(): AsyncMatcher<Awaited<T>> {
+      return createResolvesMatcher(actual, negated);
+    },
+    get rejects(): AsyncMatcher<unknown> {
+      return createRejectsMatcher(actual, negated);
+    },
+  };
+}

package/src/agent-runtime/registry.ts

@@ -1,4 +1,11 @@
-import { type AgentMessage, type RunSummary, type TestError, type TestResult, type TestStatus, type TestSuiteResult } from "frida-test/protocol.js";
+import {
+  type AgentMessage,
+  type RunSummary,
+  type TestError,
+  type TestResult,
+  type TestStatus,
+  type TestSuiteResult,
+} from "frida-test/protocol.js";
 
 export type TestFn = () => void | Promise<void>;
 export type HookFn = () => void | Promise<void>;
@@ -152,7 +159,10 @@ async function runTestSuiteNode(node: TestSuiteNode, verbose: boolean, parentHoo
         durationMs: 0,
         error: { message: `parent suite "${node.name}" failed before this test could run` },
       }));
-      const counts: Counts = { total: 1 + children.length, passed: 0, failed: 1 + children.length };
+      // Count each reported child once; fall back to counting the suite itself
+      // only when it has none, so an empty-but-broken suite isn't invisible.
+      const failedCount = Math.max(1, children.length);
+      const counts: Counts = { total: failedCount, passed: 0, failed: failedCount };
       const result: TestResult = {
         name: node.name,
         status: "failed",
@@ -177,7 +187,8 @@ async function runTestSuiteNode(node: TestSuiteNode, verbose: boolean, parentHoo
         error: { message: `parent suite "${node.name}" failed before this test could run` },
       }));
       await runTeardownHooks(hooks.afterAll, verbose);
-      const counts: Counts = { total: 1 + children.length, passed: 0, failed: 1 + children.length };
+      const failedCount = Math.max(1, children.length);
+      const counts: Counts = { total: failedCount, passed: 0, failed: failedCount };
       const result: TestResult = {
         name: node.name,
         status: "failed",

package/src/agent-runtime/spy.ts

@@ -0,0 +1,30 @@
+import { createMockFunction, type AnyFn, type Mock } from "./mock.js";
+
+const assert = (condition: boolean, message: string): void => {
+  if (!condition) throw new Error(message);
+};
+
+export function spyOn<T extends object, K extends keyof T>(target: T, key: K): Mock {
+  const original = target[key];
+  assert(typeof original === "function", `${String(key)} is not a function`);
+
+  // Capture the descriptor so restore can put things back exactly as they were, including
+  // whether the method was an own property or inherited from the prototype chain.
+  const descriptor = Object.getOwnPropertyDescriptor(target, key);
+  const mock = createMockFunction(original as unknown as AnyFn, String(key));
+  let restored = false;
+
+  mock.mockRestore = (): void => {
+    if (restored) return;
+    restored = true;
+    mock.mockReset();
+    if (descriptor) {
+      Object.defineProperty(target, key, descriptor);
+    } else {
+      Reflect.deleteProperty(target, key);
+    }
+  };
+
+  target[key] = mock as unknown as T[K];
+  return mock;
+}

package/dist/bundler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bundler.d.ts","sourceRoot":"","sources":["../src/bundler.ts"],"names":[],"mappings":"AAwFA,wBAAsB,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA4DlG"}

package/dist/cli-frida-test-compiler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-frida-test-compiler.d.ts","sourceRoot":"","sources":["../src/cli-frida-test-compiler.ts"],"names":[],"mappings":""}

package/dist/cli-frida-test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-frida-test.d.ts","sourceRoot":"","sources":["../src/cli-frida-test.ts"],"names":[],"mappings":""}

package/dist/collector.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../src/collector.ts"],"names":[],"mappings":"AA4BA,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIjF"}