Files
reverse-engineering-anything/src/hopper/HopperErrorProjection.test.ts
T
74bdfd2ec2 test: assert structured recovery facts instead of recovery wording in src tests (#12721)
* test: assert structured recovery facts instead of recovery wording in src tests

Replace recovery-sentence locks with the structured fields that already
carry those facts, and own Batch 4 temporary directories through
createTestTempDirectory.

* test(hopper): keep recovery order that retry_action does not carry

retry_action names restart or unknown. It does not say to read
provider_operation_health before retrying, or to close_binary before
opening and retrying. Those order checks stay.

Co-authored-by: morluto <morluto@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
2026-11-19 23:05:20 -05:00

571 lines
19 KiB
TypeScript

import { releaseOwnedCleanup } from "../../tests/support/cleanupRelease.js";
import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js";
import { describe, expect, it } from "vitest";
import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
import {
HOPPER_STARTUP_TIMEOUT_REMEDIATION,
HopperProcessError,
HopperRemoteError,
HopperStartError,
HopperTimeoutError,
HopperCancelledError,
HopperProtocolError,
hopperAppleEventsAuthorizationRejection,
hopperErrorCatalogue,
} from "./HopperErrors.js";
import {
DEFAULT_HOPPER_DEMO_DIALOG_TIMEOUT_MS,
HOPPER_DEMO_DIALOG_TIMEOUT_SETTING,
MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS,
type DialogTimeoutRejection,
type HopperStartupFailureDiagnostic,
} from "./HopperStartupFailure.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import {
analysisErrorRemediationAction,
analysisErrorUserMessage,
} from "../domain/analysisErrorPresentation.js";
import { analysisErrorProjectionSchema } from "../domain/analysisErrorProjectionSchema.js";
import { analysisSettingLimit } from "../domain/analysisSettingDefinitions.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
describe("analysis error projection: Hopper provider failures", () => {
it("reports a timed-out active Hopper request and actionable retry guidance", () => {
const projected = projectAnalysisError(
new HopperTimeoutError(30_000, "trace_feature", 42, "busy"),
);
expect(projected).toMatchObject({
code: "provider_timeout",
category: "timeout",
retryable: true,
details: {
stage: "analysis",
operation: "trace_feature",
request_id: 42,
provider_state: "busy",
retry_action: "wait",
timeout_ms: 30_000,
},
});
expect(projected.message).toContain("binary_session.analysis_activity");
});
it("identifies the REA session that already owns a Hopper target", () => {
const error = new HopperStartError({
ownerRunId: "session-owner",
userMessage:
"This Hopper target is already open in REA session session-owner. Use that REA session or close it before opening this target again.",
});
expect(projectAnalysisError(error)).toMatchObject({
category: "unavailable",
message: expect.stringContaining("session-owner"),
remediation: {
action: expect.stringContaining("session-owner"),
},
});
});
it("projects an Apple Events denial as unavailable and not retryable from the same client", () => {
const projected = projectAnalysisError(
new HopperStartError({
launchRejection: hopperAppleEventsAuthorizationRejection,
launcherFailure: {
exit_code: 2,
signal: null,
stdout: { text: "", bytes: 0, retained_bytes: 0 },
stderr: {
text: "Cannot launch Hopper!\nNot authorized to send Apple events to Hopper Disassembler.\n",
bytes: 90,
retained_bytes: 90,
},
output_closed: true,
diagnostic_truncated: false,
},
}),
);
expect(projected).toMatchObject({
code: "provider_unavailable",
category: "unavailable",
retryable: false,
details: {
stage: "launch",
provider_state: "unknown",
retry_action: "unknown",
launch_rejection: {
boundary: "apple_events_authorization",
reason: "not_authorized",
responsibility: "client_or_disclaimed_runtime",
settings_pane: "privacy_security_automation",
entitlement_id: "com.apple.security.automation.apple-events",
},
launcher: { exit_code: 2, signal: null },
},
});
expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected);
});
it("keeps an ordinary Hopper start failure retryable", () => {
const projected = projectAnalysisError(
new HopperStartError({
userMessage: "Hopper's launcher helper failed before bridge readiness.",
}),
);
expect(projected).toMatchObject({
code: "provider_unavailable",
category: "unavailable",
retryable: true,
details: {
stage: "launch",
provider_state: "unknown",
retry_action: "retry",
},
});
expect(projected.details).not.toHaveProperty("launch_rejection");
});
it("retains the Hopper request and provider diagnostic on a remote failure", () => {
expect(
projectAnalysisError(
new HopperRemoteError(
7,
"Hopper analysis failed in the selected document",
{
diagnosticType: "bridge_exception",
operation: "trace_feature",
requestId: 43,
},
),
),
).toMatchObject({
code: "execution_failure",
details: {
stage: "analysis",
provider_code: 7,
diagnostic_type: "bridge_exception",
operation: "trace_feature",
request_id: 43,
},
message: expect.stringContaining("Hopper analysis failed"),
});
});
});
describe("analysis error projection: Hopper startup failures", () => {
it("maps the Linux startup compatibility exit codes without host internals", () => {
const expected = [
[70, "private_display_unavailable"],
[71, "x11_authorization_failed"],
[72, "unsupported_hopper_build"],
[73, "invalid_launch_command"],
[74, "process_ownership_mismatch"],
[75, "hopper_exited_during_startup"],
[76, "unsupported_demo_dialog"],
[77, "unexpected_display_geometry"],
[78, "x11_input_failed"],
[79, "runtime_dependency_unavailable"],
[80, "x11_socket_directory_unusable"],
[81, "demo_dialog_absent"],
[82, "invalid_dialog_timeout"],
] as const;
for (const [exitCode, code] of expected) {
const projected = projectAnalysisError(new HopperProcessError(exitCode));
expect(projected).toMatchObject({
code: "provider_unavailable",
details: { failure_code: code, exit_code: exitCode },
});
expect(projected.details).not.toHaveProperty("launch_rejection");
expect(projected.message).toMatch(/\S/u);
expect(JSON.stringify(projected)).not.toContain("/proc/");
}
});
it("does not attribute an absent post-authentication dialog to publisher verification", () => {
const projected = projectAnalysisError(new HopperProcessError(81));
expect(projected).toMatchObject({
code: "provider_unavailable",
details: {
stage: "launch",
failure_code: "demo_dialog_absent",
exit_code: 81,
},
});
expect(projected.details).not.toHaveProperty("launch_rejection");
expect(projected.message).toContain("REA_HOPPER_DEMO_DIALOG_TIMEOUT_MS");
});
it("reports a rejected demo dialog timeout through its setting fields", () => {
const dialogTimeout = {
setting: HOPPER_DEMO_DIALOG_TIMEOUT_SETTING,
value: "-5",
source: "setting",
minimum_ms: MINIMUM_HOPPER_DEMO_DIALOG_TIMEOUT_MS,
maximum_ms: MAX_NODE_TIMER_DELAY_MS,
default_ms: DEFAULT_HOPPER_DEMO_DIALOG_TIMEOUT_MS,
} satisfies DialogTimeoutRejection;
const projected = projectAnalysisError(
new HopperProcessError(82, {
diagnostic: {
component: "hopper_private_display",
operation: "launch",
reason: "invalid_dialog_timeout",
socket_directory: "/tmp/.X11-unix",
socket_directory_mode: null,
mount_read_only: null,
effective_socket_directory_mode: null,
effective_mount_read_only: null,
wsl: false,
strategy: "direct",
fallback_reason: null,
xvfb_stderr_bytes: 0,
status: "error",
failure_code: "invalid_dialog_timeout",
dialog_timeout: dialogTimeout,
} as HopperStartupFailureDiagnostic,
}),
);
expect(projected).toMatchObject({
code: "provider_unavailable",
details: {
stage: "launch",
failure_code: "invalid_dialog_timeout",
exit_code: 82,
diagnostics: { dialog_timeout: dialogTimeout },
},
});
expect(projected.details).not.toHaveProperty("launch_rejection");
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(
true,
);
});
});
describe("analysis error projection: retry guidance", () => {
it.each([
[
"unreadable output",
new AnalysisOutputError("inspect_firmware_regions", "report missing"),
"unreadable_output",
],
[
"adapter failure",
new ProviderAdapterError("firmware", "inspect_firmware_regions"),
"execution_failure",
],
[
"Hopper remote failure",
new HopperRemoteError(7, "Hopper analysis failed", {
diagnosticType: "bridge_exception",
operation: "trace_feature",
}),
"execution_failure",
],
])(
"does not recommend an unchanged retry for non-retryable %s",
(_name, error, code) => {
const projected = projectAnalysisError(error);
expect(projected).toMatchObject({ code, retryable: false });
for (const text of [projected.message, projected.remediation.action])
expect(text).not.toMatch(/\bretry\b/iu);
},
);
});
describe("analysis error projection: operational diagnostics", () => {
it("distinguishes an observed Hopper exit from an undetermined provider failure", () => {
const exitedError = new HopperProcessError(7, {
operation: "search_strings",
requestId: 4,
});
const exited = projectAnalysisError(exitedError);
expect(exited).toMatchObject({
code: "provider_unavailable",
retryable: true,
details: {
stage: "analysis",
provider_state: "exited",
retry_action: "restart_provider",
operation: "search_strings",
request_id: 4,
exit_code: 7,
},
});
expect(exited.message).toBe(analysisErrorUserMessage(exitedError));
expect(exited.remediation.action).toBe(
analysisErrorRemediationAction(exitedError),
);
expect(exited.message).toMatch(
/Hopper exited.*search_strings.*exit code 7/iu,
);
expect(exited.remediation.action).toMatch(/close_binary.*open.*retry/iu);
const unknownError = new HopperProcessError(null, {
operation: "search_strings",
requestId: 5,
});
const unknown = projectAnalysisError(unknownError);
expect(unknown.details).toMatchObject({
stage: "analysis",
provider_state: "unknown",
retry_action: "unknown",
operation: "search_strings",
request_id: 5,
exit_code: null,
});
expect(unknown.message).toBe(analysisErrorUserMessage(unknownError));
expect(unknown.remediation.action).toBe(
analysisErrorRemediationAction(unknownError),
);
expect(unknown.message).toMatch(
/could not determine.*busy, exited, or unreachable/iu,
);
expect(unknown.remediation.action).toMatch(
/provider_operation_health.*before retrying or restarting/iu,
);
const unreachableError = new HopperProcessError(null, {
operation: "search_strings",
providerState: "unreachable",
});
const unreachable = projectAnalysisError(unreachableError);
expect(unreachable).toMatchObject({
code: "provider_unavailable",
details: {
provider_state: "unreachable",
retry_action: "restart_provider",
operation: "search_strings",
exit_code: null,
},
message: analysisErrorUserMessage(unreachableError),
remediation: { action: analysisErrorRemediationAction(unreachableError) },
});
expect(unreachable.message).toMatch(
/unreachable.*process exit was not observed/iu,
);
expect(unreachable.remediation.action).toContain("close_binary");
expect(unreachable.remediation.action).toContain(
"Evidence and Unknown history",
);
expect(unreachable.remediation.action).toContain("export_evidence_bundle");
});
});
it("retains Hopper startup diagnostics beside generic and secondary context", () => {
const diagnostic = {
component: "hopper_private_display",
operation: "launch",
reason: "fixture_denial",
socket_directory: "/tmp/.X11-unix",
socket_directory_mode: null,
mount_read_only: null,
effective_socket_directory_mode: null,
effective_mount_read_only: null,
wsl: false,
strategy: "unavailable",
fallback_reason: null,
xvfb_stderr_bytes: 0,
status: "error",
failure_code: "private_display_unavailable",
} as const;
expect(
projectAnalysisError(new HopperProcessError(null, { diagnostic })).details
?.diagnostics,
).toEqual(diagnostic);
const generic = { caller_context: "retained" };
expect(
projectAnalysisError(
new HopperProcessError(null, { diagnostic, diagnostics: generic }),
),
).toMatchObject({
code: "provider_unavailable",
details: { diagnostics: generic, provider_diagnostics: diagnostic },
});
const secondary = new HopperProcessError(null, {
diagnostic,
}).retainSecondaryFailure(new HopperProcessError(null), {
retirement_error: "retained",
});
expect(projectAnalysisError(secondary).details).toMatchObject({
provider_diagnostics: diagnostic,
diagnostics: { retirement_error: "retained" },
});
});
describe("analysis error projection: caller lifetime", () => {
it("delivers each lifetime's Hopper startup recovery", () => {
const error = new HopperTimeoutError(
30_000,
undefined,
undefined,
"not_started",
"launch",
undefined,
{
limit: analysisSettingLimit(
"hopper.startup_timeout_ms",
30_000,
undefined,
),
},
);
const continuing = projectAnalysisError(error);
expect(continuing.details?.limit).toMatchObject({
setting: "hopper.startup_timeout_ms",
effective_value: 30_000,
applies_at: "next_startup",
update_mode: "runtime",
});
expect(continuing.remediation.action).toContain("update_analysis_settings");
expect(continuing.remediation.action).toContain(
"hopper.startup_timeout_ms",
);
const invocation = projectAnalysisError(error, "invocation");
expect(invocation.remediation.action).toBe(
HOPPER_STARTUP_TIMEOUT_REMEDIATION,
);
expect(invocation.details?.limit).toMatchObject({
setting: "hopper.startup_timeout_ms",
effective_value: 30_000,
scope: "rea-invocation",
applies_at: "next_invocation",
environment: "REA_HOPPER_STARTUP_TIMEOUT_MS",
});
});
});
describe("analysis error projection: Hopper caller lifetime", () => {
it.each([
[
new HopperProcessError(7, { operation: "search_strings", requestId: 4 }),
"close_binary",
"exit code 7",
],
[
new HopperProcessError(null, {
operation: "search_strings",
providerState: "unreachable",
}),
"export_evidence_bundle",
"process exit was not observed",
],
[
new HopperProcessError(null, { operation: "search_strings" }),
"binary_session.provider_operation_health",
"could not determine",
],
[
new HopperTimeoutError(30_000, "search_strings", 42, "busy"),
"binary_session.analysis_activity",
"remained busy",
],
[
new HopperTimeoutError(30_000, "search_strings", 42, "not_started"),
"binary_session",
"before it started",
],
] as const)(
"keeps Hopper outcome facts and scopes request recovery to the caller",
(error, continuingTool, outcome) => {
const continuing = projectAnalysisError(error);
const invocation = projectAnalysisError(error, "invocation");
expect(continuing.message).toContain(continuingTool);
expect(continuing.remediation.action).toContain(continuingTool);
expect(invocation.message).toContain(outcome);
expect(invocation.message).not.toContain(continuingTool);
expect(invocation.remediation.action).toContain("rerunning the command");
expect(invocation.remediation.action).not.toContain(continuingTool);
expect(invocation.details).toEqual(continuing.details);
expect(invocation.code).toBe(continuing.code);
expect(invocation.category).toBe(continuing.category);
expect(invocation.retryable).toBe(continuing.retryable);
expect(analysisErrorProjectionSchema.parse(invocation)).toEqual(
invocation,
);
},
);
it("keeps Hopper recovery scoped through composed cleanup and its history", () => {
const primary = new HopperProcessError(null, {
operation: "search_strings",
providerState: "unreachable",
});
const cleanup = new ProviderCleanupError("hopper", ["hopper-bridge"], {});
const composed = analysisErrorWithCleanupFailure(
primary,
cleanup,
).bindCleanupDependencies([cleanup]);
const invocationPrimary = projectAnalysisError(primary, "invocation");
const continuingPrimary = projectAnalysisError(primary);
const invocation = projectAnalysisError(composed, "invocation");
const continuing = projectAnalysisError(composed);
expect(invocation.message).toBe(invocationPrimary.message);
expect(continuing.message).toBe(continuingPrimary.message);
expect(invocation.details).toMatchObject({
resources: ["hopper-bridge"],
diagnostics: { primary_error: invocationPrimary },
});
expect(continuing.details).toMatchObject({
diagnostics: { primary_error: continuingPrimary },
});
releaseOwnedCleanup(cleanup);
expect(
projectAnalysisError(composed, "invocation").details?.cleanup_history,
).toMatchObject({ primary_error: invocationPrimary });
expect(
projectAnalysisError(composed).details?.cleanup_history,
).toMatchObject({ primary_error: continuingPrimary });
});
});
describe("Hopper error catalogue", () => {
it.each([
["", new HopperTimeoutError(30_000, "search_strings", 1, "busy")],
["", new HopperCancelledError()],
["", new HopperProtocolError("bad reply")],
...(
[
"remote",
"authorization",
"invalid_request",
"capability_unavailable",
"bridge_exception",
] as const
).map(
(diagnosticType) =>
[
`diagnostic_type=${diagnosticType}`,
new HopperRemoteError(7, "failed", { diagnosticType }),
] as const,
),
["", new HopperProcessError(7, { operation: "search_strings" })],
["", new HopperStartError()],
[
"Apple Events authorization denied",
new HopperStartError({
launchRejection: hopperAppleEventsAuthorizationRejection,
}),
],
] as const)(
"lists the projected code, category and retryability (%s)",
(discriminant, error) => {
const projected = projectAnalysisError(error);
expect(
hopperErrorCatalogue().find(
(row) => row.tag === error._tag && row.discriminant === discriminant,
),
).toEqual({
tag: error._tag,
discriminant,
code: projected.code,
category: projected.category,
retryableByDefault: projected.retryable,
});
},
);
});