frida-test 0.2.0 → 0.3.0

package/README.md

@@ -8,7 +8,16 @@ The following chapters explain how to write and run tests.
 
 ```sh
 npm install --save-dev frida-test
+```
+
+After the installation, import the type `frida-test` into you project by adding the following configuration to the `tsconfig.json`:
 
+```json
+{
+  "compilerOptions": {
+    "types": ["frida-test"]
+  }
+}
 ```
 
 ## Writing Tests
@@ -29,7 +38,6 @@ describe('Classloader', () => {
     }).toThrow(new Error("Class 'badClass' is not available."));
   })
 });
-
 ```
 
 Tests can be nested to any depth and can be synchronous or asynchronous.
@@ -51,7 +59,6 @@ myProject/
 └── shared/
     ├── helper.ts
     └── helper.test.ts
-
 ```
 
 ## Matchers
@@ -79,13 +86,47 @@ 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.
 
 ```sh
 frida-test [options] <dir...>
-
 ```
 
 ### Options
@@ -126,7 +167,6 @@ frida-test -U -N org.owasp.mastestapp.MASTestApp-iOS ./tests/ios ./tests/shared
 
 # Connect to a remote frida-server on HOST with authentication
 frida-test -H 192.168.1.10:27042 --token secret -p 4926 ./tests/shared
-
 ```
 
 ## Compile Agent
@@ -137,7 +177,6 @@ If you only want to compile this agent, use `frida-test-compile`:
 
 ```sh
 frida-test-compile [options] <dir...>
-
 ```
 
 | Option | Description |
@@ -153,5 +192,4 @@ frida-test-compile ./tests
 
 # Collects all tests in ./tests, compiles the frida-test agent, and stores it in ./frida-test-agent.js
 frida-test-compile ./tests -o ./frida-test-agent.js
-
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frida-test",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.17.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 };
 }