frida-test 0.1.1

package/dist/runner.js

@@ -0,0 +1,95 @@
+import { logger } from "./logger.js";
+import { isAgentMessage } from "./protocol.js";
+import { printTestSuiteResult } from "./reporter/console.js";
+export class TestRunner {
+    device;
+    target;
+    agentBundle;
+    verbose;
+    session;
+    script;
+    initialized = false;
+    results = [];
+    fatalError;
+    constructor(device, target, agentBundle, verbose) {
+        this.device = device;
+        this.target = target;
+        this.agentBundle = agentBundle;
+        this.verbose = verbose;
+    }
+    get suiteResults() {
+        return this.results;
+    }
+    async initialize() {
+        if (this.initialized) {
+            throw new Error("TestRunner already initialized");
+        }
+        const session = await this.device.attach(this.target.pid);
+        try {
+            const script = await session.createScript(this.agentBundle);
+            script.message.connect((message, data) => this.onMessage(message, data));
+            script.destroyed.connect(() => {
+                this.fatalError ??= new Error("Script was destroyed unexpectedly");
+            });
+            await script.load();
+            this.session = session;
+            this.script = script;
+            this.initialized = true;
+            if (this.target.wasSpawned) {
+                await this.device.resume(this.target.pid);
+            }
+        }
+        catch (error) {
+            await session.detach().catch(() => { });
+            throw error;
+        }
+    }
+    async runTests() {
+        if (!this.initialized || this.script === undefined) {
+            throw new Error("TestRunner not initialized; call initialize() first");
+        }
+        const summary = await this.script.exports.runTests(this.verbose);
+        if (this.fatalError !== undefined) {
+            throw this.fatalError;
+        }
+        return summary;
+    }
+    async dispose() {
+        try {
+            await this.script?.unload();
+        }
+        finally {
+            await this.session?.detach();
+            this.script = undefined;
+            this.session = undefined;
+            this.initialized = false;
+        }
+    }
+    onMessage(message, _data) {
+        if (message.type === "error") {
+            this.fatalError = new Error(message.stack ?? message.description);
+            return;
+        }
+        const payload = message.payload;
+        if (!isAgentMessage(payload)) {
+            if (this.verbose) {
+                logger.info(`Ignoring non-agent message: ${JSON.stringify(payload)}`);
+            }
+            return;
+        }
+        switch (payload.type) {
+            case "agent-ready":
+                break;
+            case "test-suite-started":
+                logger.info(`Test suite "${payload.name}" started...`);
+                break;
+            case "test-suite-finished":
+                logger.info(`Test suite "${payload.name}" finished.`);
+                printTestSuiteResult(payload.result);
+                this.results.push(payload.result);
+                break;
+            case "run-finished":
+                break;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "frida-test",
+  "version": "0.1.1",
+  "type": "module",
+  "license": "GPL-3.0-only",
+  "homepage": "https://github.com/bernhste/frida-test/blob/main/README.md",
+  "description": "frida-test is a small unit framework based on Frida. It is used to unit test Frida code running on actual devices.",
+  "keywords": [
+    "frida",
+    "testing",
+    "instrumentation",
+    "hooking"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bernhste/frida-test.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "frida-test": "bin/frida-test.js",
+    "frida-test-compiler": "bin/frida-test-compiler.js"
+  },
+  "types": "./src/agent-runtime/globals.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/agent-runtime/globals.d.ts",
+      "default": "./src/agent-runtime/globals.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/agent-runtime"
+  ],
+  "scripts": {
+    "build": "npx tsc -b  &&  npm link",
+    "test:android": "npm run build && frida-test -U  -i 'com.google.android.dialer' ./tests/",
+    "watch": "npx tsc -b --watch",
+    "clean": "npx tsc -b --clean && npx rimraf dist"
+  },
+  "allowScripts": {
+    "frida": true
+  },
+  "dependencies": {
+    "chalk": "^6.0.0",
+    "frida-compile": "^19.0.5"
+  },
+  "devDependencies": {
+    "@types/frida-gum": "^19.10.0",
+    "@types/node": "^26.4.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^7.0.2"
+  }
+}

package/src/agent-runtime/agentRuntime.ts

@@ -0,0 +1,25 @@
+// AUTO-GENERATED by frida-test - do not edit
+import type { AgentMessage, RunSummary } from "../../src/protocol.js";
+import "./globals.js";
+import "./matchers.js";
+import { registry, runTests } from "./registry.js";
+
+/// IMPORT TESTS SUITES ///
+
+function emit(message: AgentMessage): void {
+  send(message);
+}
+
+let running: Promise<RunSummary> | null = null;
+
+rpc.exports = {
+  runTests(verbose: boolean = false): Promise<RunSummary> {
+    running ??= runTests(registry, emit, verbose).then((summary) => {
+      emit({ type: "run-finished" });
+      return summary;
+    });
+    return running;
+  },
+};
+
+emit({ type: "agent-ready" });

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

@@ -0,0 +1,9 @@
+type Matcher<T> = import("./matchers.js").Matcher<T>;
+type Spy = import("./matchers.js").Spy;
+type TestFn = import("./registry.js").TestFn;
+
+declare function describe(name: string, fn: TestFn): void;
+declare function it(name: string, fn: TestFn): void;
+declare function test(name: string, fn: TestFn): void;
+declare function expect<T>(actual: T): Matcher<T>;
+declare function spyOn<T extends object, K extends keyof T>(target: T, key: K): Spy;

package/src/agent-runtime/globals.ts

@@ -0,0 +1,13 @@
+import { expect, spyOn, type Matcher, type Spy } from "./matchers.js";
+import type { TestFn } from "./registry.js";
+import { describe, it, test } from "./registry.js";
+
+declare global {
+  function describe(name: string, fn: TestFn): void;
+  function it(name: string, fn: TestFn): void;
+  function test(name: string, fn: TestFn): void;
+  function expect<T>(actual: T): Matcher<T>;
+  function spyOn<T extends object, K extends keyof T>(target: T, key: K): Spy;
+}
+
+Object.assign(globalThis, { describe, it, test, expect, spyOn });

package/src/agent-runtime/matchers.ts

@@ -0,0 +1,243 @@
+export type Containable<T> = T extends readonly (infer U)[] ? U : T extends string ? string : never;
+export type Numeric<T> = T extends number ? number : never;
+
+export interface Matcher<T> {
+  toBe(expected: T): void;
+  toEqual(expected: T): void;
+  toBeTruthy(): void;
+  toBeFalsy(): void;
+  toBeNull(): void;
+  toBeDefined(): void;
+  toBeUndefined(): void;
+  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>;
+  toHaveBeenCalled(): 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;
+}
+
+const assert = (condition: boolean, message: string): void => {
+  if (!condition) throw new Error(message);
+};
+
+const deepEqual = (a: unknown, b: unknown, seen: Array<[unknown, unknown]> = []): boolean => {
+  if (Object.is(a, b)) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+
+  const tagA = Object.prototype.toString.call(a);
+  const tagB = Object.prototype.toString.call(b);
+  if (tagA !== tagB) return false;
+
+  if (a instanceof Date) return a.getTime() === (b as Date).getTime();
+  if (a instanceof RegExp) return a.source === (b as RegExp).source && a.flags === (b as RegExp).flags;
+
+  if (seen.some(([sa, sb]) => sa === a && sb === b)) return true;
+  const nextSeen: Array<[unknown, unknown]> = [...seen, [a, b]];
+
+  if (a instanceof Map) {
+    const bm = b as Map<unknown, unknown>;
+    if (a.size !== bm.size) return false;
+    for (const [key, val] of a) {
+      if (!bm.has(key) || !deepEqual(val, bm.get(key), nextSeen)) return false;
+    }
+    return true;
+  }
+
+  if (a instanceof Set) {
+    const bs = [...(b as Set<unknown>)];
+    if (a.size !== bs.length) return false;
+    for (const val of a) {
+      if (!bs.some((other) => deepEqual(val, other, nextSeen))) return false;
+    }
+    return true;
+  }
+
+  const ra = a as Record<string, unknown>;
+  const rb = b as Record<string, unknown>;
+  const keysA = Object.keys(ra).filter((k) => ra[k] !== undefined);
+  const keysB = Object.keys(rb).filter((k) => rb[k] !== undefined);
+  if (keysA.length !== keysB.length) return false;
+  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> {
+  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)}`),
+
+    toEqual: (expected) =>
+      check(deepEqual(actual, expected), `Expected ${JSON.stringify(actual, null, 2)} ${phrase} equal ${JSON.stringify(expected, null, 2)}`),
+
+    toBeTruthy: () => check(Boolean(actual), `Expected ${String(actual)} ${phrase} be truthy`),
+    toBeFalsy: () => check(!actual, `Expected ${String(actual)} ${phrase} be falsy`),
+    toBeNull: () => check(actual === null, `Expected ${String(actual)} ${phrase} be null`),
+    toBeDefined: () => check(actual !== undefined, `Expected ${String(actual)} ${phrase} be defined`),
+    toBeUndefined: () => check(actual === undefined, `Expected ${String(actual)} ${phrase} be undefined`),
+
+    toBeGreaterThan: (expected) => {
+      assertIsNumber(actual, "actual");
+      assertIsNumber(expected, "expected");
+      check(actual > expected, `Expected ${actual} ${phrase} be greater than ${expected}`);
+    },
+
+    toBeLessThan: (expected) => {
+      assertIsNumber(actual, "actual");
+      assertIsNumber(expected, "expected");
+      check(actual < expected, `Expected ${actual} ${phrase} be less than ${expected}`);
+    },
+
+    toContain: (expected) => {
+      assert(typeof actual === "string" || Array.isArray(actual), "Expected an array or string");
+      const contains =
+        typeof actual === "string" ? actual.includes(expected as string) : (actual as readonly unknown[]).some((item) => deepEqual(item, expected));
+      check(contains, `Expected ${JSON.stringify(actual)} ${phrase} contain ${JSON.stringify(expected)}`);
+    },
+
+    toThrow: (errorMatch) => {
+      assert(typeof actual === "function", "Expected a function");
+      let caught: unknown;
+      let threw = false;
+      let result: unknown;
+      try {
+        result = (actual as () => unknown)();
+      } catch (e) {
+        threw = true;
+        caught = e;
+      }
+
+      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");
+      }
+
+      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
+      }
+      check(resolved, `Expected promise ${phrase} resolve`);
+      if (negated || expected === undefined) return;
+      assert(deepEqual(caught, expected), `Expected ${JSON.stringify(caught)} to equal ${JSON.stringify(expected)}`);
+    },
+
+    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(isSpy(actual), "Expected a spy created with spyOn()");
+      check((actual as Spy).calls.length > 0, `Expected spy ${phrase} have been called`);
+    },
+
+    toHaveBeenCalledWith: (...expected: unknown[]) => {
+      assert(isSpy(actual), "Expected a spy created with spyOn()");
+      const calls = (actual as Spy).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)}`);
+    },
+
+    get not(): Matcher<T> {
+      return createMatcher(actual, !negated);
+    },
+  };
+}
+
+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;
+    },
+  };
+
+  target[key] = ((...args: unknown[]) => {
+    calls.push(args);
+    return hasReturnValue ? returnValue : impl(...args);
+  }) as T[K];
+
+  return spy;
+}

package/src/agent-runtime/registry.ts

@@ -0,0 +1,160 @@
+// agent/registry.ts
+import { type AgentMessage, type RunSummary, type TestError, type TestResult, type TestStatus, type TestSuiteResult } from "../../src/protocol.js";
+
+export type TestFn = () => void | Promise<void>;
+
+type NodeKind = "describe" | "it";
+
+interface TestSuiteNode {
+  kind: NodeKind;
+  name: string;
+  fn: TestFn;
+  children?: TestSuiteNode[];
+}
+
+export const registry: TestSuiteNode[] = [];
+const stack: TestSuiteNode[][] = [];
+
+function registerNode(kind: NodeKind, name: string, fn: TestFn): void {
+  (stack.at(-1) ?? registry).push({ kind, name, fn });
+}
+
+export const describe = (name: string, fn: TestFn): void => registerNode("describe", name, fn);
+
+export const it = (name: string, fn: TestFn): void => registerNode("it", name, fn);
+export const test = it; // alias
+
+function serializeError(err: unknown, verbose: boolean): TestError {
+  if (err instanceof Error) {
+    return { message: err.message, stack: verbose ? err.stack : undefined };
+  }
+  return { message: String(err) };
+}
+
+interface Counts {
+  total: number;
+  passed: number;
+  failed: number;
+}
+
+const ZERO_COUNTS: Counts = { total: 0, passed: 0, failed: 0 };
+
+function addCounts(a: Counts, b: Counts): Counts {
+  return { total: a.total + b.total, passed: a.passed + b.passed, failed: a.failed + b.failed };
+}
+
+let expandLock: Promise<void> = Promise.resolve();
+
+function withExpandLock<T>(fn: () => Promise<T>): Promise<T> {
+  const run = expandLock.then(fn, fn);
+  expandLock = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+async function expand(node: TestSuiteNode, verbose: boolean): Promise<{ children: TestSuiteNode[]; error?: TestError }> {
+  return withExpandLock(async () => {
+    const children: TestSuiteNode[] = [];
+    stack.push(children);
+    try {
+      await node.fn();
+      return { children };
+    } catch (err) {
+      return { children, error: serializeError(err, verbose) };
+    } finally {
+      stack.pop();
+    }
+  });
+}
+
+async function runTestSuiteNode(node: TestSuiteNode, verbose: boolean): Promise<{ result: TestResult; counts: Counts }> {
+  const start = Date.now();
+
+  if (node.kind === "describe") {
+    const { children: nodes, error } = await expand(node, verbose);
+    node.children = nodes;
+
+    if (error) {
+      const children: TestResult[] = nodes.map((child) => ({
+        name: child.name,
+        status: "failed",
+        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 };
+      const result: TestResult = {
+        name: node.name,
+        status: "failed",
+        durationMs: Date.now() - start,
+        error,
+        children,
+      };
+      return { result, counts };
+    }
+
+    const children: TestResult[] = [];
+    let counts = ZERO_COUNTS;
+    for (const child of node.children) {
+      const childRun = await runTestSuiteNode(child, verbose);
+      children.push(childRun.result);
+      counts = addCounts(counts, childRun.counts);
+    }
+
+    const status: TestStatus = counts.failed > 0 ? "failed" : "passed";
+    const result: TestResult = { name: node.name, status, durationMs: Date.now() - start, children };
+    return { result, counts };
+  }
+
+  // Leaf test.
+  try {
+    await node.fn();
+    const result: TestResult = { name: node.name, status: "passed", durationMs: Date.now() - start };
+    return { result, counts: { total: 1, passed: 1, failed: 0 } };
+  } catch (err) {
+    const result: TestResult = {
+      name: node.name,
+      status: "failed",
+      durationMs: Date.now() - start,
+      error: serializeError(err, verbose),
+    };
+    return { result, counts: { total: 1, passed: 0, failed: 1 } };
+  }
+}
+
+export async function runTests(nodes: TestSuiteNode[], emit: (message: AgentMessage) => void, verbose: boolean = false): Promise<RunSummary> {
+  const start = Date.now();
+
+  const settled = await Promise.allSettled(
+    nodes.map(async (node) => {
+      emit({ type: "test-suite-started", name: node.name });
+      const { result: testResult, counts } = await runTestSuiteNode(node, verbose);
+      const suiteResult: TestSuiteResult = { name: node.name, testResult, status: testResult.status };
+      emit({ type: "test-suite-finished", name: node.name, result: suiteResult });
+      return { suiteResult, counts };
+    }),
+  );
+
+  const testSuitesResults: TestSuiteResult[] = [];
+  let counts = ZERO_COUNTS;
+
+  settled.forEach((outcome, i) => {
+    if (outcome.status === "fulfilled") {
+      testSuitesResults.push(outcome.value.suiteResult);
+      counts = addCounts(counts, outcome.value.counts);
+      return;
+    }
+
+    const error = serializeError(outcome.reason, verbose);
+    const testSuiteResult: TestSuiteResult = {
+      name: nodes[i].name,
+      testResult: { name: nodes[i].name, status: "failed", durationMs: 0, error },
+      status: "failed",
+    };
+    testSuitesResults.push(testSuiteResult);
+    counts = addCounts(counts, { total: 1, passed: 0, failed: 1 });
+  });
+
+  return { ...counts, durationMs: Date.now() - start, testSuitesResults };
+}