frida-test 0.2.1 → 0.3.1

package/README.md

@@ -86,6 +86,41 @@ myProject/
 > [!NOTE]
 > `frida-test` test itself. So for examples for all Matches and more, have a look a the `*.test.ts` located in the [test folder](./tests/)
 
+### Setup and Teardown
+
+Use `beforeEach()` / `afterEach()` and `beforeAll()` / `afterAll()` to run code before or after tests. They can be declared at the top level of a file or inside a `describe()` block:
+
+- `beforeEach()` / `afterEach()`: Run before/after every `it()` in the same and nested `describe()` blocks.
+- `beforeAll()` / `afterAll()`: Run once before/after all tests in the same `describe()` block (or, at the top level, once before/after the whole file).
+
+Hooks declared in an outer `describe()` also apply to tests in nested `describe()` blocks. `beforeEach` hooks run outer-to-inner; `afterEach` hooks run inner-to-outer.
+
+```typescript
+describe('ClassLoader', () => {
+  let loader: ClassLoader;
+
+  beforeAll(() => {
+    loader = new ClassLoader();
+  });
+
+  beforeEach(() => {
+    loader.reset();
+  });
+
+  afterEach(() => {
+    loader.clearCache();
+  });
+
+  afterAll(() => {
+    loader.destroy();
+  });
+
+  it('should load a known class', () => {
+    expect(loader.load('com.example.Foo')).toBeDefined();
+  });
+});
+```
+
 ## Running Tests
 
 `frida-test` takes one or more directories, collects every `*.test.ts` file below them, compiles them together with the framework agent, and runs the resulting agent on the target.

package/dist/bundler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundler.d.ts","sourceRoot":"","sources":["../src/bundler.ts"],"names":[],"mappings":"AAwEA,wBAAsB,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA2DlG"}
+{"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/bundler.js

@@ -63,6 +63,20 @@ async function deleteWorkDir(workDir) {
         logger.warn(`Failed to remove temporary work dir "${workDir}": ${err.message}`);
     }
 }
+async function prepareTypeCheckConfig(projectRoot, workDir) {
+    const realTsconfigPath = path.join(projectRoot, "tsconfig.json");
+    if (!existsSync(realTsconfigPath))
+        return;
+    const scratchConfig = {
+        extends: realTsconfigPath.replace(/\\/g, "/"),
+        compilerOptions: {
+            rootDir: projectRoot.replace(/\\/g, "/"),
+        },
+        include: [],
+        exclude: [],
+    };
+    await writeFile(path.join(workDir, "tsconfig.json"), JSON.stringify(scratchConfig, null, 2), "utf8");
+}
 export async function bundleAgent(testSuitePaths, keep = false) {
     if (testSuitePaths.length === 0) {
         throw new Error("bundleAgent requires at least one test suite path.");
@@ -87,19 +101,19 @@ export async function bundleAgent(testSuitePaths, keep = false) {
             .join("\n");
         await rm(entrypointPath, { force: true });
         await writeFile(entrypointPath, agentSource.replace(IMPORT_MARKER, importStatements), "utf8");
+        await prepareTypeCheckConfig(projectRoot, workDir);
         const outfilePath = path.join(workDir, AGENT_BUNDLE_FILENAME);
         const fridaCompile = getFridaCompileBin(projectRoot);
         const args = fridaCompile.useLocal ? [entrypointPath, "-o", outfilePath] : ["frida-compile", entrypointPath, "-o", outfilePath];
         try {
             execFileSync(fridaCompile.path, args, {
-                cwd: projectRoot,
+                cwd: workDir,
                 shell: process.platform === "win32",
-                encoding: "utf8",
+                stdio: "inherit",
             });
         }
         catch (err) {
-            const stderr = err.stderr?.toString().trim();
-            throw new Error(`frida-compile failed for entrypoint "${entrypointPath}" with suites [${testSuitePaths.join(", ")}]: ${stderr || err.message}`, { cause: err });
+            throw new Error(`frida-compile failed for entrypoint "${entrypointPath}" with suites [${testSuitePaths.join(", ")}] (see compiler output above for details)`, { cause: err });
         }
         logger.info(`Agent bundle sucessfully created and saved at ${outfilePath}.`);
         return await readFile(outfilePath, "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frida-test",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "license": "GPL-3.0-only",
   "homepage": "https://github.com/bernhste/frida-test/blob/main/README.md",
@@ -49,12 +49,9 @@
     "build": "tsc -b",
     "watch": "tsc -b --watch",
     "clean": "tsc -b --clean && rimraf dist",
-    "test:android": "npm run build && frida-test -U -f 'com.google.android.dialer' ./tests/",
+    "test:android": "npm run build && npx frida-test -U -f 'com.google.android.dialer' ./tests/",
     "prepublishOnly": "npm run clean && npm run build && npm run test:android"
   },
-  "allowScripts": {
-    "frida": true
-  },
   "dependencies": {
     "chalk": "^6.0.0",
     "frida-compile": "^19.0.5"
@@ -64,5 +61,8 @@
     "@types/node": "^26.4.0",
     "rimraf": "^6.1.3",
     "typescript": "^7.0.2"
+  },
+  "allowScripts": {
+    "frida@17.18.0": true
   }
 }

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

@@ -1,9 +1,14 @@
 type Matcher<T> = import("./matchers.js").Matcher<T>;
 type Spy = import("./matchers.js").Spy;
 type TestFn = import("./registry.js").TestFn;
+type HookFn = import("./registry.js").HookFn;
 
 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 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;

package/src/agent-runtime/globals.ts

@@ -1,13 +1,17 @@
 import { expect, spyOn, type Matcher, type Spy } from "./matchers.js";
-import type { TestFn } from "./registry.js";
-import { describe, it, test } from "./registry.js";
+import type { HookFn, TestFn } from "./registry.js";
+import { afterAll, afterEach, beforeAll, beforeEach, 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 beforeEach(fn: HookFn): void;
+  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;
 }
 
-Object.assign(globalThis, { describe, it, test, expect, spyOn });
+Object.assign(globalThis, { describe, it, test, beforeEach, afterEach, beforeAll, afterAll, expect, spyOn });

package/src/agent-runtime/registry.ts

@@ -1,6 +1,7 @@
 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>;
 
 type NodeKind = "describe" | "it";
 
@@ -9,13 +10,40 @@ interface TestSuiteNode {
   name: string;
   fn: TestFn;
   children?: TestSuiteNode[];
+  hooks?: HooksBag;
+}
+
+interface HooksBag {
+  beforeEach: HookFn[];
+  afterEach: HookFn[];
+  beforeAll: HookFn[];
+  afterAll: HookFn[];
+}
+
+interface EachHooks {
+  beforeEach: HookFn[];
+  afterEach: HookFn[];
+}
+
+function createHooksBag(): HooksBag {
+  return { beforeEach: [], afterEach: [], beforeAll: [], afterAll: [] };
+}
+
+interface Frame {
+  children: TestSuiteNode[];
+  hooks: HooksBag;
 }
 
 export const registry: TestSuiteNode[] = [];
-const stack: TestSuiteNode[][] = [];
+const rootHooks: HooksBag = createHooksBag();
+const stack: Frame[] = [{ children: registry, hooks: rootHooks }];
+
+function currentFrame(): Frame {
+  return stack[stack.length - 1];
+}
 
 function registerNode(kind: NodeKind, name: string, fn: TestFn): void {
-  (stack.at(-1) ?? registry).push({ kind, name, fn });
+  currentFrame().children.push({ kind, name, fn });
 }
 
 export const describe = (name: string, fn: TestFn): void => registerNode("describe", name, fn);
@@ -23,6 +51,22 @@ export const describe = (name: string, fn: TestFn): void => registerNode("descri
 export const it = (name: string, fn: TestFn): void => registerNode("it", name, fn);
 export const test = it; // alias
 
+export const beforeEach = (fn: HookFn): void => {
+  currentFrame().hooks.beforeEach.push(fn);
+};
+
+export const afterEach = (fn: HookFn): void => {
+  currentFrame().hooks.afterEach.push(fn);
+};
+
+export const beforeAll = (fn: HookFn): void => {
+  currentFrame().hooks.beforeAll.push(fn);
+};
+
+export const afterAll = (fn: HookFn): void => {
+  currentFrame().hooks.afterAll.push(fn);
+};
+
 function serializeError(err: unknown, verbose: boolean): TestError {
   if (err instanceof Error) {
     return { message: err.message, stack: verbose ? err.stack : undefined };
@@ -30,6 +74,31 @@ function serializeError(err: unknown, verbose: boolean): TestError {
   return { message: String(err) };
 }
 
+// Setup hooks (beforeEach/beforeAll): stop at the first failure since later hooks may depend on earlier ones.
+async function runSetupHooks(hooks: HookFn[], verbose: boolean): Promise<TestError | undefined> {
+  for (const hook of hooks) {
+    try {
+      await hook();
+    } catch (err) {
+      return serializeError(err, verbose);
+    }
+  }
+  return undefined;
+}
+
+// Teardown hooks (afterEach/afterAll): run every hook regardless of earlier failures, to give cleanup a chance to run.
+async function runTeardownHooks(hooks: HookFn[], verbose: boolean): Promise<TestError | undefined> {
+  let firstError: TestError | undefined;
+  for (const hook of hooks) {
+    try {
+      await hook();
+    } catch (err) {
+      firstError ??= serializeError(err, verbose);
+    }
+  }
+  return firstError;
+}
+
 interface Counts {
   total: number;
   passed: number;
@@ -53,27 +122,28 @@ function withExpandLock<T>(fn: () => Promise<T>): Promise<T> {
   return run;
 }
 
-async function expand(node: TestSuiteNode, verbose: boolean): Promise<{ children: TestSuiteNode[]; error?: TestError }> {
+async function expand(node: TestSuiteNode, verbose: boolean): Promise<{ children: TestSuiteNode[]; hooks: HooksBag; error?: TestError }> {
   return withExpandLock(async () => {
-    const children: TestSuiteNode[] = [];
-    stack.push(children);
+    const frame: Frame = { children: [], hooks: createHooksBag() };
+    stack.push(frame);
     try {
       await node.fn();
-      return { children };
+      return { children: frame.children, hooks: frame.hooks };
     } catch (err) {
-      return { children, error: serializeError(err, verbose) };
+      return { children: frame.children, hooks: frame.hooks, error: serializeError(err, verbose) };
     } finally {
       stack.pop();
     }
   });
 }
 
-async function runTestSuiteNode(node: TestSuiteNode, verbose: boolean): Promise<{ result: TestResult; counts: Counts }> {
+async function runTestSuiteNode(node: TestSuiteNode, verbose: boolean, parentHooks: EachHooks): Promise<{ result: TestResult; counts: Counts }> {
   const start = Date.now();
 
   if (node.kind === "describe") {
-    const { children: nodes, error } = await expand(node, verbose);
+    const { children: nodes, hooks, error } = await expand(node, verbose);
     node.children = nodes;
+    node.hooks = hooks;
 
     if (error) {
       const children: TestResult[] = nodes.map((child) => ({
@@ -93,42 +163,99 @@ async function runTestSuiteNode(node: TestSuiteNode, verbose: boolean): Promise<
       return { result, counts };
     }
 
+    const combinedHooks: EachHooks = {
+      beforeEach: [...parentHooks.beforeEach, ...hooks.beforeEach],
+      afterEach: [...hooks.afterEach, ...parentHooks.afterEach],
+    };
+
+    const beforeAllError = await runSetupHooks(hooks.beforeAll, verbose);
+    if (beforeAllError) {
+      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` },
+      }));
+      await runTeardownHooks(hooks.afterAll, verbose);
+      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: beforeAllError,
+        children,
+      };
+      return { result, counts };
+    }
+
     const children: TestResult[] = [];
     let counts = ZERO_COUNTS;
     for (const child of node.children) {
-      const childRun = await runTestSuiteNode(child, verbose);
+      const childRun = await runTestSuiteNode(child, verbose, combinedHooks);
       children.push(childRun.result);
       counts = addCounts(counts, childRun.counts);
     }
 
+    const afterAllError = await runTeardownHooks(hooks.afterAll, verbose);
+    if (afterAllError) {
+      children.push({ name: "afterAll hook", status: "failed", durationMs: 0, error: afterAllError });
+      counts = addCounts(counts, { total: 1, passed: 0, failed: 1 });
+    }
+
     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 } };
+  const beforeEachError = await runSetupHooks(parentHooks.beforeEach, verbose);
+  let result: TestResult;
+  let counts: Counts;
+  if (beforeEachError) {
+    result = { name: node.name, status: "failed", durationMs: 0, error: beforeEachError };
+    counts = { total: 1, passed: 0, failed: 1 };
+  } else {
+    try {
+      await node.fn();
+      result = { name: node.name, status: "passed", durationMs: 0 };
+      counts = { total: 1, passed: 1, failed: 0 };
+    } catch (err) {
+      result = { name: node.name, status: "failed", durationMs: 0, error: serializeError(err, verbose) };
+      counts = { total: 1, passed: 0, failed: 1 };
+    }
   }
+
+  const afterEachError = await runTeardownHooks(parentHooks.afterEach, verbose);
+  if (afterEachError && result.status === "passed") {
+    result = { ...result, status: "failed", error: afterEachError };
+    counts = { total: 1, passed: 0, failed: 1 };
+  }
+
+  return { result: { ...result, durationMs: Date.now() - start }, counts };
 }
 
 export async function runTests(nodes: TestSuiteNode[], emit: (message: AgentMessage) => void, verbose: boolean = false): Promise<RunSummary> {
   const start = Date.now();
 
+  const beforeAllError = await runSetupHooks(rootHooks.beforeAll, verbose);
+  if (beforeAllError) {
+    const testSuitesResults: TestSuiteResult[] = nodes.map((node) => {
+      emit({ type: "test-suite-started", name: node.name });
+      const testResult: TestResult = { name: node.name, status: "failed", durationMs: 0, error: beforeAllError };
+      const suiteResult: TestSuiteResult = { name: node.name, testResult, status: "failed" };
+      emit({ type: "test-suite-finished", name: node.name, result: suiteResult });
+      return suiteResult;
+    });
+    await runTeardownHooks(rootHooks.afterAll, verbose);
+    return { total: nodes.length, passed: 0, failed: nodes.length, durationMs: Date.now() - start, testSuitesResults };
+  }
+
+  const parentHooks: EachHooks = { beforeEach: rootHooks.beforeEach, afterEach: rootHooks.afterEach };
+
   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 { result: testResult, counts } = await runTestSuiteNode(node, verbose, parentHooks);
       const suiteResult: TestSuiteResult = { name: node.name, testResult, status: testResult.status };
       emit({ type: "test-suite-finished", name: node.name, result: suiteResult });
       return { suiteResult, counts };
@@ -155,5 +282,15 @@ export async function runTests(nodes: TestSuiteNode[], emit: (message: AgentMess
     counts = addCounts(counts, { total: 1, passed: 0, failed: 1 });
   });
 
+  const afterAllError = await runTeardownHooks(rootHooks.afterAll, verbose);
+  if (afterAllError) {
+    testSuitesResults.push({
+      name: "afterAll hook",
+      status: "failed",
+      testResult: { name: "afterAll hook", status: "failed", durationMs: 0, error: afterAllError },
+    });
+    counts = addCounts(counts, { total: 1, passed: 0, failed: 1 });
+  }
+
   return { ...counts, durationMs: Date.now() - start, testSuitesResults };
 }