frida-test 0.1.7 → 0.1.8

package/README.md

@@ -1,6 +1,6 @@
 # frida-test Documentation
 
-This is a small test framework which runs on the target. It is used to unit test Frida code running on actual devices. It was originaly developed to test the Frida agent code used in [frooky](https://github.com/cpholguera/frooky).
+This is a small test framework which runs on the target. It is used to unit test Frida code running on actual devices. It was originally developed to test the Frida agent code used in [frooky](https://github.com/cpholguera/frooky).
 
 The following chapters explain how to write and run tests.
 
@@ -8,6 +8,7 @@ The following chapters explain how to write and run tests.
 
 ```sh
 npm install --save-dev frida-test
+
 ```
 
 ## Writing Tests
@@ -28,6 +29,7 @@ describe('Classloader', () => {
     }).toThrow(new Error("Class 'badClass' is not available."));
   })
 });
+
 ```
 
 Tests can be nested to any depth and can be synchronous or asynchronous.
@@ -49,6 +51,7 @@ myProject/
 └── shared/
     ├── helper.ts
     └── helper.test.ts
+
 ```
 
 ## Matchers
@@ -82,16 +85,26 @@ myProject/
 
 ```sh
 frida-test [options] <dir...>
+
 ```
 
 ### Options
 
 | Option | Description |
 | --- | --- |
-| `-i, --id <id>` | Bundle/package id or app name (spawns the app) |
-| `-p, --pid <id>` | Attach to a running process instead |
-| `-U, --usb` | Use the USB device |
-| `-D, --device <id>` | Use a specific device by id |
+| `-D, --device <id>` | Connect to device with the given ID |
+| `-U, --usb` | Connect to USB device |
+| `-R, --remote` | Connect to remote frida-server |
+| `-H, --host <host>` | Connect to remote frida-server on HOST |
+| `--certificate <cert>` | Speak TLS with HOST, expecting CERTIFICATE |
+| `--origin <origin>` | Connect to remote server with "Origin" header set to ORIGIN |
+| `--token <token>` | Authenticate with HOST using TOKEN |
+| `--keepalive-interval <interval>` | Set keepalive interval in seconds, or 0 to disable (defaults to -1) |
+| `-f, --file <target>` | Spawn FILE |
+| `-F, --attach-frontmost` | Attach to frontmost application |
+| `-n, --attach-name <name>` | Attach to NAME |
+| `-N, --attach-identifier <id>` | Attach to IDENTIFIER |
+| `-p, --attach-pid <pid>` | Attach to PID |
 | `-o, --out <path>` | Path of the output file for JSON reporter (default: disabled) |
 | `-t, --timeout <s>` | Abort the run after this many seconds (default: `600`, `0` disables) |
 | `-d, --delay <s>` | Start running the test suites after this many seconds (default: `0`) |
@@ -102,24 +115,29 @@ frida-test [options] <dir...>
 ### `frida-test` Examples
 
 ```sh
-# Android app on a USB device, tests in ./tests/android and ./tests/shared
-frida-test -i org.owasp.mastestapp -U ./tests/android ./tests/shared
+# Spawn an Android app on a USB device, tests in ./tests/android and ./tests/shared
+frida-test -U -f org.owasp.mastestapp ./tests/android ./tests/shared
 
-# Attach to a running process by pid
-frida-test --pid 4926 -u ./tests/android
+# Attach to a running process by PID on a USB device
+frida-test -U -p 4926 ./tests/android
+
+# Attach to a running iOS app by identifier
+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
 
-# iOS app in the local simulator
-frida-test -i org.owasp.mastestapp.MASTestApp-iOS ./tests/ios ./tests/shared
 ```
 
 ## Compile Agent
 
-`frida-test` automatically bundles the test suites, and compiles them together with the testing framework into a Frida agent.
+`frida-test` automatically bundles the test suites and compiles them together with the testing framework into a Frida agent.
 
 If you only want to compile this agent, use `frida-test-compile`:
 
 ```sh
 frida-test-compile [options] <dir...>
+
 ```
 
 | Option | Description |
@@ -130,9 +148,10 @@ frida-test-compile [options] <dir...>
 ### `frida-test-compile` Examples
 
 ```sh
-# Collects all tests in ./tests, compiles the frida-test agent, and print it to stdout
+# Collects all tests in ./tests, compiles the frida-test agent, and prints it to stdout
 frida-test-compile ./tests
 
-# Collects all tests in ./tests, compile the frida-test agent, and stores it in the path ./frida-test-agent.js
+# 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/dist/cli-frida-test.js

@@ -12,10 +12,19 @@ const usage = `
   Usage: frida-test [options] <src_path>...
 
   Options:
-    -i, --id <id>                   Bundle/package id or app name (spawns the app)
-    -p, --pid <id>                  Attach to a running process instead
-    -U, --usb                       Use the USB device
-    -D, --device <id>               Use a specific device by id
+    -D, --device <id>               Connect to device with the given ID
+    -U, --usb                       Connect to USB device
+    -R, --remote                    Connect to remote frida-server
+    -H, --host <host>               Connect to remote frida-server on HOST
+    --certificate <cert>            Speak TLS with HOST, expecting CERTIFICATE
+    --origin <origin>               Connect to remote server with "Origin" header set to ORIGIN
+    --token <token>                 Authenticate with HOST using TOKEN
+    --keepalive-interval <interval> Set keepalive interval in seconds, or 0 to disable (defaults to -1)
+    -f, --file <target>             Spawn FILE
+    -F, --attach-frontmost          Attach to frontmost application
+    -n, --attach-name <name>        Attach to NAME
+    -N, --attach-identifier <id>    Attach to IDENTIFIER
+    -p, --attach-pid <pid>          Attach to PID
     -o, --out <path>                Path of the output file for JSON reporter (default: disabled)
     -t, --timeout <s>               Abort the run after this many seconds (default: 600, 0 disables)
     -d, --delay <s>                 Start running the test suites after this many seconds (default: 0)
@@ -24,8 +33,8 @@ const usage = `
     -h, --help                      Show this help message
 
   Examples:
-    frida-test -U -i org.owasp.mastestapp ./test -r json -o ./testing/reports/out.json
-    frida-test -U --pid 4926 ./src/hooks.test.ts ./lib/utils
+    frida-test -U -f org.owasp.mastestapp ./test -o ./testing/reports/out.json
+    frida-test -H 192.168.1.10:27042 --token secret -p 4926 ./src/hooks.test.ts
 `;
 class CliError extends Error {
 }
@@ -39,14 +48,33 @@ function parseNonNegativeInt(value, name) {
     }
     return n;
 }
+function parseKeepaliveInterval(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < -1) {
+        throw new Error("keepalive-interval must be an integer >= -1");
+    }
+    return n;
+}
 async function main() {
     const { values, positionals } = parseArgs({
         allowPositionals: true,
         options: {
-            id: { type: "string", short: "i" },
-            pid: { type: "string", short: "p" },
-            usb: { type: "boolean", short: "U", default: false },
+            // Device options
             device: { type: "string", short: "D" },
+            usb: { type: "boolean", short: "U", default: false },
+            remote: { type: "boolean", short: "R", default: false },
+            host: { type: "string", short: "H" },
+            certificate: { type: "string" },
+            origin: { type: "string" },
+            token: { type: "string" },
+            "keepalive-interval": { type: "string" },
+            // Target options
+            file: { type: "string", short: "f" },
+            "attach-frontmost": { type: "boolean", short: "F", default: false },
+            "attach-name": { type: "string", short: "n" },
+            "attach-identifier": { type: "string", short: "N" },
+            "attach-pid": { type: "string", short: "p" },
+            // Test runner options
             out: { type: "string", short: "o" },
             delay: { type: "string", short: "d", default: "0" },
             timeout: { type: "string", short: "t", default: "600" },
@@ -63,22 +91,68 @@ async function main() {
     if (positionals.length === 0) {
         fail("Missing required argument <src_path>...");
     }
-    if (Boolean(values.id) === Boolean(values.pid)) {
-        fail("Must provide either --id (-i) or --pid (-p), but not both");
+    const primaryDeviceFlags = [values.device !== undefined, values.usb, values.remote, values.host !== undefined].filter(Boolean).length;
+    if (primaryDeviceFlags > 1) {
+        fail("Cannot specify multiple primary device options (-D, -U, -R, -H)");
+    }
+    const hasRemoteParams = values.certificate !== undefined || values.origin !== undefined || values.token !== undefined || values["keepalive-interval"] !== undefined;
+    if (hasRemoteParams && (values.device !== undefined || values.usb)) {
+        fail("Remote connection options (--certificate, --origin, --token, --keepalive-interval) cannot be used with -D or -U");
+    }
+    let deviceSelector;
+    if (values.device !== undefined) {
+        deviceSelector = { id: values.device };
+    }
+    else if (values.usb) {
+        deviceSelector = "usb";
+    }
+    else if (values.host !== undefined || values.remote || hasRemoteParams) {
+        const keepaliveInterval = values["keepalive-interval"] !== undefined ? parseKeepaliveInterval(values["keepalive-interval"]) : undefined;
+        deviceSelector = {
+            host: values.host ?? "127.0.0.1:27042",
+            ...(values.certificate && { certificate: values.certificate }),
+            ...(values.origin && { origin: values.origin }),
+            ...(values.token && { token: values.token }),
+            ...(keepaliveInterval !== undefined && { keepaliveInterval }),
+        };
+    }
+    else {
+        deviceSelector = "local";
+    }
+    const targetFlags = [
+        values.file !== undefined ? "file" : null,
+        values["attach-frontmost"] ? "attach-frontmost" : null,
+        values["attach-name"] !== undefined ? "attach-name" : null,
+        values["attach-identifier"] !== undefined ? "attach-identifier" : null,
+        values["attach-pid"] !== undefined ? "attach-pid" : null,
+    ].filter(Boolean);
+    if (targetFlags.length === 0) {
+        fail("Must provide a target option: -f, -F, -n, -N, or -p");
+    }
+    if (targetFlags.length > 1) {
+        fail("Must provide only one target option (-f, -F, -n, -N, or -p)");
     }
     let targetDef;
-    if (values.id) {
-        targetDef = { id: values.id };
+    if (values.file !== undefined) {
+        targetDef = { file: values.file };
+    }
+    else if (values["attach-frontmost"]) {
+        targetDef = { frontmost: true };
+    }
+    else if (values["attach-name"] !== undefined) {
+        targetDef = { name: values["attach-name"] };
+    }
+    else if (values["attach-identifier"] !== undefined) {
+        targetDef = { identifier: values["attach-identifier"] };
     }
     else {
-        const parsedPid = parseNonNegativeInt(values.pid, "pid");
+        const parsedPid = parseNonNegativeInt(values["attach-pid"], "attach-pid");
         if (parsedPid === 0)
             fail("Invalid pid: must be greater than 0");
         targetDef = { pid: parsedPid };
     }
     const delay = parseNonNegativeInt(values.delay, "delay");
     const timeout = parseNonNegativeInt(values.timeout, "timeout");
-    const deviceSelector = values.device !== undefined ? { id: values.device } : values.usb ? "usb" : "local";
     logger.info(`Collecting tests from ${positionals.join(", ")}...`);
     const testSuitePaths = await collectTestSuitePaths(positionals);
     logger.info(`Bundling testSuites with frida-test agent...`);

package/dist/device.d.ts

@@ -1,11 +1,23 @@
 import type { Device } from "frida";
-export type DeviceSelector = "usb" | "local" | {
+export type DeviceSelector = "usb" | "local" | "remote" | {
     id: string;
+} | {
+    host: string;
+    certificate?: string;
+    origin?: string;
+    token?: string;
+    keepaliveInterval?: number;
 };
 export type TargetDef = {
-    pid: number;
+    file: string;
 } | {
-    id: string;
+    frontmost: true;
+} | {
+    name: string;
+} | {
+    identifier: string;
+} | {
+    pid: number;
 };
 export declare function resolveDevice(selector?: DeviceSelector): Promise<Device>;
 export interface Target {

package/dist/device.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAGpC,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAC9D,MAAM,MAAM,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,wBAAsB,aAAa,CAAC,QAAQ,GAAE,cAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIvF;AAED,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BzF"}
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAGpC,MAAM,MAAM,cAAc,GACtB,KAAK,GACL,OAAO,GACP,QAAQ,GACR;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GACd;IACE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEN,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7H,wBAAsB,aAAa,CAAC,QAAQ,GAAE,cAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAcvF;AAED,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDzF"}

package/dist/device.js

@@ -4,35 +4,65 @@ export async function resolveDevice(selector = "local") {
         return frida.getUsbDevice();
     if (selector === "local")
         return frida.getLocalDevice();
-    return frida.getDevice(selector.id);
+    if (selector === "remote")
+        return frida.getRemoteDevice();
+    if ("id" in selector)
+        return frida.getDevice(selector.id);
+    // Pass network parameters to addRemoteDevice
+    const manager = frida.getDeviceManager();
+    return manager.addRemoteDevice(selector.host, {
+        certificate: selector.certificate,
+        origin: selector.origin,
+        token: selector.token,
+        keepaliveInterval: selector.keepaliveInterval,
+    });
 }
 export async function resolveTarget(device, targetDef) {
-    if ("pid" in targetDef)
-        return { pid: targetDef.pid, wasSpawned: false };
-    const { id } = targetDef;
-    if (!id.trim())
-        throw new Error("Target id must not be empty");
-    try {
-        const pid = await device.spawn(id);
+    if ("file" in targetDef) {
+        const file = targetDef.file.trim();
+        if (!file)
+            throw new Error("Target file/program must not be empty");
+        const pid = await device.spawn(file);
         return { pid, wasSpawned: true };
     }
-    catch (spawnError) {
-        const needle = id.toLowerCase();
+    if ("pid" in targetDef) {
+        return { pid: targetDef.pid, wasSpawned: false };
+    }
+    if ("frontmost" in targetDef) {
+        const app = await device.getFrontmostApplication();
+        if (!app) {
+            throw new Error("No frontmost application found on the target device");
+        }
+        return { pid: app.pid, wasSpawned: false };
+    }
+    if ("name" in targetDef) {
+        const targetName = targetDef.name.trim();
+        if (!targetName)
+            throw new Error("Target process name must not be empty");
         const processes = await device.enumerateProcesses();
+        const needle = targetName.toLowerCase();
         const tiers = [
-            processes.filter((p) => p.name === id),
+            processes.filter((p) => p.name === targetName),
             processes.filter((p) => p.name.toLowerCase() === needle),
             processes.filter((p) => p.name.toLowerCase().includes(needle)),
         ];
         const matches = tiers.find((tier) => tier.length > 0) ?? [];
         if (matches.length === 0) {
-            const reason = spawnError instanceof Error ? spawnError.message : String(spawnError);
-            throw new Error(`Unable to spawn '${id}' and no matching running process was found (spawn failed: ${reason}).`);
+            throw new Error(`No running process matching '${targetName}' was found.`);
         }
         if (matches.length > 1) {
             const names = matches.map((p) => `${p.name} (pid ${p.pid})`).join(", ");
-            throw new Error(`Ambiguous target '${id}', matches: ${names}`);
+            throw new Error(`Ambiguous process target '${targetName}', matches: ${names}`);
         }
         return { pid: matches[0].pid, wasSpawned: false };
     }
+    const identifier = targetDef.identifier.trim();
+    if (!identifier)
+        throw new Error("Target identifier must not be empty");
+    const apps = await device.enumerateApplications();
+    const matchedApp = apps.find((a) => a.identifier === identifier);
+    if (!matchedApp || !matchedApp.pid || matchedApp.pid === 0) {
+        throw new Error(`Application '${identifier}' is not currently running.`);
+    }
+    return { pid: matchedApp.pid, wasSpawned: false };
 }

package/dist/runner.d.ts

@@ -1,6 +1,6 @@
 import type { Device } from "frida";
-import type { Target } from "./device.js";
 import type { RunSummary, TestSuiteResult } from "./protocol.js";
+import type { Target } from "./target.js";
 export declare class TestRunner {
     private readonly device;
     private readonly target;

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAA4B,MAAM,OAAO,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIjE,qBAAa,UAAU;IAQnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,UAAU,CAAC,CAAQ;IAE3B,YACmB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,EAC/B;IAEJ,IAAI,YAAY,IAAI,SAAS,eAAe,EAAE,CAE7C;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAyBhC;IAEK,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CASpC;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAS7B;IAED,OAAO,CAAC,SAAS;CA6BlB"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAA4B,MAAM,OAAO,CAAC;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,qBAAa,UAAU;IAQnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,UAAU,CAAC,CAAQ;IAE3B,YACmB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,EAC/B;IAEJ,IAAI,YAAY,IAAI,SAAS,eAAe,EAAE,CAE7C;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAyBhC;IAEK,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CASpC;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAS7B;IAED,OAAO,CAAC,SAAS;CA6BlB"}

package/dist/target.d.ts

@@ -0,0 +1,18 @@
+import type { Device } from "frida";
+export interface Target {
+    pid: number;
+    wasSpawned: boolean;
+}
+export type TargetDef = {
+    file: string;
+} | {
+    frontmost: true;
+} | {
+    name: string;
+} | {
+    identifier: string;
+} | {
+    pid: number;
+};
+export declare function resolveTarget(device: Device, targetDef: TargetDef): Promise<Target>;
+//# sourceMappingURL=target.d.ts.map

package/dist/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEpC,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;CACrB;AACD,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7H,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CA4DzF"}

package/dist/target.js

@@ -0,0 +1,54 @@
+export async function resolveTarget(device, targetDef) {
+    // Spawn target binary or app (-f, --file)
+    if ("file" in targetDef) {
+        const file = targetDef.file.trim();
+        if (!file)
+            throw new Error("Target file/program must not be empty");
+        const pid = await device.spawn(file);
+        return { pid, wasSpawned: true };
+    }
+    // Attach by PID (-p, --attach-pid)
+    if ("pid" in targetDef) {
+        return { pid: targetDef.pid, wasSpawned: false };
+    }
+    // Attach to frontmost application (-F, --attach-frontmost)
+    if ("frontmost" in targetDef) {
+        const app = await device.getFrontmostApplication();
+        if (!app) {
+            throw new Error("No frontmost application found on the target device");
+        }
+        return { pid: app.pid, wasSpawned: false };
+    }
+    // Attach by process name (-n, --attach-name)
+    if ("name" in targetDef) {
+        const targetName = targetDef.name.trim();
+        if (!targetName)
+            throw new Error("Target process name must not be empty");
+        const processes = await device.enumerateProcesses();
+        const needle = targetName.toLowerCase();
+        const tiers = [
+            processes.filter((p) => p.name === targetName),
+            processes.filter((p) => p.name.toLowerCase() === needle),
+            processes.filter((p) => p.name.toLowerCase().includes(needle)),
+        ];
+        const matches = tiers.find((tier) => tier.length > 0) ?? [];
+        if (matches.length === 0) {
+            throw new Error(`No running process matching '${targetName}' was found.`);
+        }
+        if (matches.length > 1) {
+            const names = matches.map((p) => `${p.name} (pid ${p.pid})`).join(", ");
+            throw new Error(`Ambiguous process target '${targetName}', matches: ${names}`);
+        }
+        return { pid: matches[0].pid, wasSpawned: false };
+    }
+    // Attach to running application by identifier (-N, --attach-identifier) without spawning
+    const identifier = targetDef.identifier.trim();
+    if (!identifier)
+        throw new Error("Target identifier must not be empty");
+    const apps = await device.enumerateApplications();
+    const matchedApp = apps.find((a) => a.identifier === identifier);
+    if (!matchedApp || !matchedApp.pid || matchedApp.pid === 0) {
+        throw new Error(`Application '${identifier}' is not currently running.`);
+    }
+    return { pid: matchedApp.pid, wasSpawned: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frida-test",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "license": "GPL-3.0-only",
   "homepage": "https://github.com/bernhste/frida-test/blob/main/README.md",
@@ -49,7 +49,7 @@
     "build": "tsc -b",
     "watch": "tsc -b --watch",
     "clean": "tsc -b --clean && rimraf dist",
-    "test:android": "npm run build && frida-test -U -i 'com.google.android.dialer' ./tests/",
+    "test:android": "npm run build && frida-test -U -f 'com.google.android.dialer' ./tests/",
     "prepublishOnly": "npm run clean && npm run build && npm run test:android"
   },
   "allowScripts": {