taphound 0.2.0-dev.1

package/dist/application/runtime/step-runner.js

@@ -0,0 +1,429 @@
+import { appProcessPids, primaryAppPid } from "../../domain/app-process.js";
+import { ActionExecutor } from "../interaction/action-executor.js";
+import { FallbackResolver } from "../interaction/fallback-resolver.js";
+import { ScrollToExecutor } from "../interaction/scroll-to-executor.js";
+import { resolveLocator } from "../locator/locator-resolver.js";
+import { ExpectationEvaluator } from "../assertion/expectation-evaluator.js";
+import { IdleWaiter } from "../wait/idle-waiter.js";
+import { hasExactlyOneEnabledFocusedElement } from "../generation/focused-input.js";
+function stepPath(index, suffix) {
+    return `steps/${String(index + 1).padStart(3, "0")}-${suffix}`;
+}
+function targetForPoint(point) {
+    return {
+        point,
+        bounds: {
+            left: Math.max(0, point.x - 1),
+            top: Math.max(0, point.y - 1),
+            right: Math.max(1, point.x + 1),
+            bottom: Math.max(1, point.y + 1)
+        }
+    };
+}
+export class StepRunner {
+    options;
+    actionExecutor;
+    fallbackResolver;
+    idleWaiter;
+    expectationEvaluator;
+    scrollToExecutor;
+    constructor(options) {
+        this.options = options;
+        this.actionExecutor = new ActionExecutor(options.adb, options.deviceSerial);
+        this.fallbackResolver = new FallbackResolver(options.androidCli, options.deviceSerial);
+        this.idleWaiter = new IdleWaiter(options.androidCli, options.clock, options.deviceSerial);
+        this.expectationEvaluator = new ExpectationEvaluator(options.adb, options.androidCli, options.logcat, options.clock);
+        this.scrollToExecutor = new ScrollToExecutor({
+            androidCli: options.androidCli,
+            actionExecutor: this.actionExecutor,
+            idleWaiter: this.idleWaiter,
+            deviceSerial: options.deviceSerial,
+            idle: options.idle,
+            ...(options.generatedReplayPolicy === true
+                ? {
+                    readLayout: async () => (this.captureGeneratedLayout(this.currentSignal)),
+                    beforeMutation: async () => {
+                        await this.assertGeneratedForeground(undefined, "ACTIVITY_BEFORE_MISMATCH", this.currentSignal);
+                    },
+                    requireLiveContainerCapability: true
+                }
+                : {})
+        });
+    }
+    identity = (signal) => ({
+        packageName: this.options.packageName,
+        deviceSerial: this.options.deviceSerial,
+        ...(signal === undefined ? {} : { signal }),
+        timeoutMs: this.options.idle.timeoutMs
+    });
+    primaryPid = async (identity) => {
+        const processes = await this.options.adb.appProcesses(identity);
+        this.options.logcat.scopeToPids(appProcessPids(processes));
+        return primaryAppPid(processes, this.options.packageName);
+    };
+    async generatedForeground(expectedActivity, code, signal) {
+        const foreground = await this.options.adb.foregroundComponent(this.identity(signal));
+        if (foreground.packageName !== this.options.packageName
+            || foreground.activity !== expectedActivity) {
+            throw Object.assign(new Error(`Expected foreground ${this.options.packageName}/${expectedActivity}, found ${foreground.packageName}/${foreground.activity}`), { code });
+        }
+        return foreground;
+    }
+    async assertGeneratedForeground(expectedActivity, code = "ACTIVITY_BEFORE_MISMATCH", signal) {
+        await this.generatedForeground(expectedActivity ?? this.currentExpectedActivity, code, signal);
+    }
+    currentExpectedActivity = "";
+    currentSignal;
+    async observeExpectedActivity(expectedActivity, expectedPid, input) {
+        const deadline = this.options.clock.now() + input.timeoutMs;
+        const identity = () => ({
+            packageName: this.options.packageName,
+            deviceSerial: this.options.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: Math.max(1, deadline - this.options.clock.now())
+        });
+        const foreground = await this.options.adb.foregroundComponent(identity());
+        if (foreground.packageName !== this.options.packageName
+            || (expectedActivity !== undefined
+                && foreground.activity !== expectedActivity)) {
+            return {
+                status: "failed",
+                message: `Generated Expect foreground changed to ${foreground.packageName}/${foreground.activity}`
+            };
+        }
+        const pid = await this.primaryPid(identity());
+        if (pid !== expectedPid) {
+            return {
+                status: "failed",
+                message: `Generated Expect process changed from ${String(expectedPid)} to ${String(pid)}`
+            };
+        }
+        return { status: "observed", activity: foreground.activity };
+    }
+    async observeExpectedLayout(expectedActivity, expectedPid, input) {
+        const deadline = this.options.clock.now() + input.timeoutMs;
+        const observationInput = () => ({
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: Math.max(1, deadline - this.options.clock.now())
+        });
+        const before = await this.observeExpectedActivity(expectedActivity, expectedPid, observationInput());
+        if (before.status === "failed")
+            return before;
+        const layout = await this.options.androidCli.layout({
+            deviceSerial: this.options.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: observationInput().timeoutMs
+        });
+        const after = await this.observeExpectedActivity(expectedActivity, expectedPid, observationInput());
+        return after.status === "failed"
+            ? after
+            : { status: "observed", layout };
+    }
+    async captureGeneratedLayout(signal) {
+        await this.assertGeneratedForeground(this.currentExpectedActivity, "ACTIVITY_BEFORE_MISMATCH", signal);
+        const layout = await this.options.androidCli.layout({
+            deviceSerial: this.options.deviceSerial,
+            ...(signal === undefined ? {} : { signal }),
+            timeoutMs: this.options.idle.timeoutMs
+        });
+        await this.assertGeneratedForeground(this.currentExpectedActivity, "ACTIVITY_BEFORE_MISMATCH", signal);
+        return layout;
+    }
+    async run(step, index, signal) {
+        const startedAt = this.options.clock.now();
+        const logcatPath = stepPath(index, "logcat.txt");
+        const activityReport = {
+            before: {
+                status: "notRun",
+                expected: step.activity.before
+            },
+            after: {
+                status: "notRun",
+                expected: step.activity.after
+            }
+        };
+        const report = {
+            index,
+            action: step.action,
+            status: "notRun",
+            startedAtMs: startedAt,
+            finishedAtMs: startedAt,
+            durationMs: 0,
+            activity: activityReport,
+            logcatPath
+        };
+        const finish = async (status, failure) => {
+            const finishedAt = this.options.clock.now();
+            report.finishedAtMs = finishedAt;
+            report.durationMs = finishedAt - startedAt;
+            report.status = status === "cancelled" ? "notRun" : status;
+            const log = this.options.logcat
+                .linesBetween(startedAt, finishedAt)
+                .map((line) => line.raw)
+                .join("\n");
+            await this.options.artifacts.writeText(logcatPath, log.length === 0 ? "" : `${log}\n`);
+            if (status === "failed" && failure !== undefined) {
+                return { status, report, failure };
+            }
+            return status === "cancelled"
+                ? { status, report }
+                : { status: "passed", report };
+        };
+        const fail = async (code, message) => finish("failed", {
+            code,
+            message,
+            phase: "replay",
+            stepIndex: index
+        });
+        if (signal?.aborted === true) {
+            return finish("cancelled");
+        }
+        const identity = this.identity(signal);
+        this.currentExpectedActivity = step.activity.before;
+        this.currentSignal = signal;
+        let before;
+        try {
+            before = this.options.generatedReplayPolicy === true
+                ? (await this.generatedForeground(step.activity.before, "ACTIVITY_BEFORE_MISMATCH", signal)).activity
+                : await this.options.adb.currentActivity(identity);
+        }
+        catch (error) {
+            if (error !== null
+                && typeof error === "object"
+                && "code" in error
+                && error.code === "ACTIVITY_BEFORE_MISMATCH") {
+                return fail("ACTIVITY_BEFORE_MISMATCH", errorMessage(error));
+            }
+            throw error;
+        }
+        activityReport.before = {
+            status: before === step.activity.before ? "passed" : "failed",
+            expected: step.activity.before,
+            actual: before
+        };
+        if (before !== step.activity.before) {
+            return fail("ACTIVITY_BEFORE_MISMATCH", `Expected Activity ${step.activity.before}, found ${before}`);
+        }
+        const generatedPid = this.options.generatedReplayPolicy === true
+            ? await this.primaryPid(identity)
+            : undefined;
+        if (this.options.generatedReplayPolicy === true
+            && generatedPid === null) {
+            return fail("APP_CRASHED", "Generated replay process is not running");
+        }
+        let target;
+        if (step.action === "scrollTo") {
+            const scroll = await this.scrollToExecutor.execute(step, signal);
+            report.scroll = {
+                swipesUsed: scroll.swipesUsed,
+                maxSwipes: step.maxSwipes
+            };
+            if (scroll.status === "cancelled") {
+                return finish("cancelled");
+            }
+            if (scroll.status === "failed") {
+                if (scroll.idle !== undefined) {
+                    await this.options.artifacts.writeJson(stepPath(index, "layout-diff.json"), scroll.idle.lastDiff);
+                    report.idle = {
+                        status: "timeout",
+                        polls: scroll.idle.polls,
+                        lastDiff: [...scroll.idle.lastDiff]
+                    };
+                }
+                return fail(scroll.code, scroll.message);
+            }
+        }
+        else {
+            let layout;
+            try {
+                layout = this.options.generatedReplayPolicy === true
+                    ? await this.captureGeneratedLayout(signal)
+                    : await this.options.androidCli.layout({
+                        deviceSerial: this.options.deviceSerial,
+                        ...(signal === undefined ? {} : { signal }),
+                        timeoutMs: this.options.idle.timeoutMs
+                    });
+            }
+            catch (error) {
+                if (error !== null
+                    && typeof error === "object"
+                    && "code" in error
+                    && error.code === "ACTIVITY_BEFORE_MISMATCH") {
+                    return fail("ACTIVITY_BEFORE_MISMATCH", errorMessage(error));
+                }
+                throw error;
+            }
+            if (step.action === "click"
+                || step.action === "longClick"
+                || step.action === "swipe") {
+                const resolution = resolveLocator(layout, step.locator);
+                if (resolution.status === "found") {
+                    target = {
+                        point: resolution.point,
+                        ...(resolution.element.bounds === undefined
+                            ? {}
+                            : { bounds: resolution.element.bounds })
+                    };
+                    report.locator = {
+                        status: "found",
+                        matchedBy: resolution.matchedBy,
+                        fallbackUsed: false
+                    };
+                }
+                else {
+                    const annotatedPath = stepPath(index, "fallback-annotated.png");
+                    const fallback = await this.fallbackResolver.resolve(step, this.options.artifacts.path(annotatedPath), signal);
+                    if (fallback.status !== "found") {
+                        const code = fallback.status === "failed"
+                            ? fallback.code
+                            : resolution.code;
+                        const message = fallback.status === "failed"
+                            ? fallback.message
+                            : resolution.message;
+                        report.locator = {
+                            status: "failed",
+                            fallbackUsed: fallback.status === "failed"
+                                && fallback.label !== undefined
+                                && fallback.annotatedScreenshotPath !== undefined,
+                            ...(fallback.status === "failed" && fallback.label !== undefined
+                                ? { fallbackLabel: fallback.label }
+                                : {}),
+                            ...(fallback.status === "failed"
+                                && fallback.annotatedScreenshotPath !== undefined
+                                ? { annotatedScreenshotPath: annotatedPath }
+                                : {}),
+                            message
+                        };
+                        return fail(code, message);
+                    }
+                    target = targetForPoint(fallback.point);
+                    report.locator = {
+                        status: "found",
+                        fallbackUsed: true,
+                        fallbackLabel: fallback.label,
+                        annotatedScreenshotPath: annotatedPath
+                    };
+                }
+            }
+            if (step.action === "inputText"
+                && this.options.requireFocusedInput === true
+                && !hasExactlyOneEnabledFocusedElement(layout)) {
+                return fail("ACTION_FAILED", "inputText requires exactly one enabled focused Layout element");
+            }
+            if (this.options.generatedReplayPolicy === true) {
+                try {
+                    await this.assertGeneratedForeground(step.activity.before, "ACTIVITY_BEFORE_MISMATCH", signal);
+                }
+                catch (error) {
+                    return fail("ACTIVITY_BEFORE_MISMATCH", errorMessage(error));
+                }
+            }
+            const action = await this.actionExecutor.execute(step, target, signal);
+            if (action.status === "failed") {
+                return fail(action.code, action.message);
+            }
+            const idle = await this.idleWaiter.waitUntilIdle(this.options.idle, signal);
+            report.idle = idle.status === "timeout"
+                ? {
+                    status: "timeout",
+                    polls: idle.polls,
+                    lastDiff: [...idle.lastDiff]
+                }
+                : {
+                    status: idle.status,
+                    polls: idle.polls
+                };
+            if (idle.status === "cancelled") {
+                return finish("cancelled");
+            }
+            if (idle.status === "timeout") {
+                await this.options.artifacts.writeJson(stepPath(index, "layout-diff.json"), idle.lastDiff);
+                return fail(idle.code, "Layout did not become stable before timeout");
+            }
+        }
+        const pid = await this.primaryPid(identity);
+        if (pid === null) {
+            return fail("APP_CRASHED", "App process is no longer running");
+        }
+        if (generatedPid !== undefined
+            && generatedPid !== null
+            && pid !== generatedPid) {
+            return fail("APP_CRASHED", "Generated replay process identity changed");
+        }
+        let after;
+        try {
+            after = this.options.generatedReplayPolicy === true
+                ? (await this.generatedForeground(step.activity.after, "ACTIVITY_AFTER_MISMATCH", signal)).activity
+                : await this.options.adb.currentActivity(identity);
+        }
+        catch (error) {
+            if (error !== null
+                && typeof error === "object"
+                && "code" in error
+                && error.code === "ACTIVITY_AFTER_MISMATCH") {
+                return fail("ACTIVITY_AFTER_MISMATCH", errorMessage(error));
+            }
+            throw error;
+        }
+        activityReport.after = {
+            status: after === step.activity.after ? "passed" : "failed",
+            expected: step.activity.after,
+            actual: after
+        };
+        if (after !== step.activity.after) {
+            return fail("ACTIVITY_AFTER_MISMATCH", `Expected Activity ${step.activity.after}, found ${after}`);
+        }
+        if (step.expect !== undefined) {
+            const expectation = await this.expectationEvaluator.evaluate(step.expect, {
+                packageName: this.options.packageName,
+                deviceSerial: this.options.deviceSerial,
+                stepStartedAt: startedAt
+            }, signal, generatedPid === undefined || generatedPid === null
+                ? {}
+                : {
+                    activity: (input) => this.observeExpectedActivity(undefined, generatedPid, input),
+                    layout: (input) => this.observeExpectedLayout(step.activity.after, generatedPid, input)
+                });
+            if (expectation.status === "cancelled") {
+                report.expectation = {
+                    type: expectation.type,
+                    status: "notRun"
+                };
+                return finish("cancelled");
+            }
+            report.expectation = expectation.status === "passed"
+                ? {
+                    type: expectation.type,
+                    status: "passed"
+                }
+                : {
+                    type: expectation.type,
+                    status: "failed",
+                    code: expectation.code,
+                    message: expectation.message
+                };
+            if (expectation.status === "failed") {
+                return fail(expectation.code, expectation.message);
+            }
+            if (this.options.generatedReplayPolicy === true) {
+                const expectedActivity = step.expect.type === "activity"
+                    ? step.expect.value
+                    : step.activity.after;
+                try {
+                    await this.assertGeneratedForeground(expectedActivity, "ACTIVITY_AFTER_MISMATCH", signal);
+                    const guardedPid = await this.primaryPid(identity);
+                    if (guardedPid !== generatedPid) {
+                        return await fail("ACTIVITY_AFTER_MISMATCH", "Generated replay process changed after Expect");
+                    }
+                }
+                catch (error) {
+                    return fail("ACTIVITY_AFTER_MISMATCH", errorMessage(error));
+                }
+            }
+        }
+        return finish("passed");
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/application/runtime/verify-runtime.d.ts

@@ -0,0 +1,44 @@
+import type { TapHoundConfig } from "../../domain/config.js";
+import type { Journey } from "../../domain/journey.js";
+import { type TapHoundReport } from "../../domain/report.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { ArtifactStore } from "../../ports/artifact-store.js";
+import type { Clock } from "../../ports/clock.js";
+import type { ReportWriter } from "../report/report-writer.js";
+import { type StepRunResult, type StepRunnerOptions } from "./step-runner.js";
+export interface VerifyInput {
+    config: TapHoundConfig;
+    journey: Journey;
+    projectRoot: string;
+    deviceSerial: string;
+    toolVersions: Record<string, string>;
+    requireFocusedInput?: boolean | undefined;
+    generatedReplayPolicy?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface StepRunnerLike {
+    run: (step: Journey["steps"][number], index: number, signal?: AbortSignal) => Promise<StepRunResult>;
+}
+export interface VerifyRuntimeDependencies {
+    androidCli: AndroidCliPort;
+    adb: AdbPort;
+    clock: Clock;
+    artifactStore: ArtifactStore;
+    reportWriter: Pick<ReportWriter, "writeAndPublish">;
+    now: () => Date;
+    createRunId: () => string;
+    createStepRunner?: ((options: StepRunnerOptions) => StepRunnerLike) | undefined;
+}
+export interface VerifyResult {
+    status: "passed" | "failed" | "error";
+    exitCode: 0 | 1 | 2 | 3 | 4;
+    report: TapHoundReport;
+    reportPath: string;
+    summaryPath: string;
+}
+export declare class VerifyRuntime {
+    private readonly dependencies;
+    constructor(dependencies: VerifyRuntimeDependencies);
+    verify(input: VerifyInput): Promise<VerifyResult>;
+}