Skip to content

Commit 8688bf9

Browse files
committed
fix(test): key the e2e appless-cleanup skip on the reason instead of its message
The mic-permission cleanup skip matched an exact error string, so a reworded refusal would silently resume retrying a command that can never succeed. It now keys on details.reason, and the suite asserts a byte-identical message with no reason still exhausts its retries — the prose alone must never activate the guard. Documents both published reasons with their recovery in the user docs. Refs #3181
1 parent dd708f8 commit 8688bf9

3 files changed

Lines changed: 32 additions & 19 deletions

File tree

‎test/integration/ios-simulator-e2e-cleanup.test.ts‎

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import assert from 'node:assert/strict';
22
import test from 'node:test';
33

4+
import { PUBLISHED_ERROR_REASONS } from '@agent-device/kernel/errors';
45
import type { CliJsonResult } from './cli-json.ts';
56
import type { LiveContext } from './ios-simulator-e2e/live-harness.ts';
67
import { retryCleanupStep } from './ios-simulator-e2e/live-harness.ts';
@@ -16,8 +17,19 @@ const MIC_STEP = 'reset microphone permission';
1617
const OTHER_STEP = 'restore portrait orientation';
1718
const MIC_APPLESS_MESSAGE = 'permission setting requires an active app in session';
1819

19-
function invalidArgsResult(message: string): CliJsonResult {
20-
return { json: { error: { code: 'INVALID_ARGS', message } }, status: 1, stderr: '', stdout: '' };
20+
function invalidArgsResult(message: string, reason?: string): CliJsonResult {
21+
return {
22+
json: {
23+
error: {
24+
code: 'INVALID_ARGS',
25+
message,
26+
...(reason === undefined ? {} : { details: { reason, dispatched: 'no' } }),
27+
},
28+
},
29+
status: 1,
30+
stderr: '',
31+
stdout: '',
32+
};
2133
}
2234

2335
function sessionNotFoundResult(): CliJsonResult {
@@ -57,26 +69,27 @@ test('a dead session (SESSION_NOT_FOUND) skips cleanup without error, on any ste
5769
assert.equal(attempts, 1, 'should not retry once the session is confirmed gone');
5870
});
5971

60-
test('the known mic-permission appless response stops retrying immediately', async () => {
72+
test('the known mic-permission appless refusal stops retrying immediately', async () => {
6173
let attempts = 0;
6274
const failure = await retryCleanupStep(MIC_STEP, async () => {
6375
attempts += 1;
64-
return invalidArgsResult(MIC_APPLESS_MESSAGE);
76+
return invalidArgsResult(MIC_APPLESS_MESSAGE, PUBLISHED_ERROR_REASONS.sessionAppRequired);
6577
});
6678
assert.equal(failure, undefined);
67-
assert.equal(attempts, 1, 'should not retry the known appless response');
79+
assert.equal(attempts, 1, 'should not retry the known appless refusal');
6880
});
6981

7082
test('a different INVALID_ARGS still fails after exhausting retries', async (t) => {
71-
// Same message, wrong step: proves the guard is scoped to the mic-permission reset
72-
// and does not tolerate the identical string on another step.
83+
// Same refusal, wrong step: proves the guard is scoped to the mic-permission reset
84+
// and does not tolerate that reason on another step.
7385
t.mock.timers.enable({ apis: ['setTimeout'] });
7486
let attempts = 0;
7587
const failure = await drainRetry(
7688
t,
7789
retryCleanupStep(OTHER_STEP, async (attempt) => {
7890
attempts += 1;
79-
if (attempt < 3) return invalidArgsResult(MIC_APPLESS_MESSAGE);
91+
if (attempt < 3)
92+
return invalidArgsResult(MIC_APPLESS_MESSAGE, PUBLISHED_ERROR_REASONS.sessionAppRequired);
8093
// Mirrors runStep(..., { allowFailure: false }) on the final attempt: it throws
8194
// instead of returning a failed result.
8295
throw new Error(`cleanup: ${OTHER_STEP} (attempt 3) failed`);
@@ -86,18 +99,16 @@ test('a different INVALID_ARGS still fails after exhausting retries', async (t)
8699
assert.equal(attempts, 3, 'should exhaust all three attempts');
87100
});
88101

89-
test('a different INVALID_ARGS message on the mic-permission step still fails after retries', async (t) => {
90-
// Same step, a message sharing the "requires an active app in session" suffix with
91-
// the location-setting call site (app-settings.ts): proves the match is the exact
92-
// known string, not any INVALID_ARGS message that happens to overlap it.
102+
test('the appless message without its typed reason still fails after retries', async (t) => {
103+
// Same step, byte-identical message, no reason: the message alone must never activate the
104+
// skip, so a reworded refusal cannot be what this guard keys on.
93105
t.mock.timers.enable({ apis: ['setTimeout'] });
94106
let attempts = 0;
95107
const failure = await drainRetry(
96108
t,
97109
retryCleanupStep(MIC_STEP, async (attempt) => {
98110
attempts += 1;
99-
if (attempt < 3)
100-
return invalidArgsResult('location setting requires an active app in session');
111+
if (attempt < 3) return invalidArgsResult(MIC_APPLESS_MESSAGE);
101112
throw new Error(`cleanup: ${MIC_STEP} (attempt 3) failed`);
102113
}),
103114
);

‎test/integration/ios-simulator-e2e/live-harness.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import fs from 'node:fs';
33
import path from 'node:path';
44

55
import { resolveDaemonPaths } from '../../../src/daemon-resolution.ts';
6+
import { PUBLISHED_ERROR_REASONS } from '@agent-device/kernel/errors';
67
import type { CliJsonResult } from '../cli-json.ts';
78
import {
89
createLiveDeviceContext,
@@ -129,14 +130,14 @@ export async function retryCleanupStep(
129130
return undefined;
130131
}
131132

132-
// SESSION_NOT_FOUND: nothing left to reset, any step. INVALID_ARGS: only the
133-
// mic-permission reset needs an app bundle and app-settings.ts has no reason code for
134-
// it, so we match its exact message — scoped to this step so it can't hide another failure.
133+
// SESSION_NOT_FOUND: nothing left to reset, any step. INVALID_ARGS with the published
134+
// session-app reason: only the mic-permission reset needs an app bundle, and the refusal is
135+
// scoped to this step so it can't hide another failure.
135136
function sessionAlreadyClean(step: string, result: CliJsonResult): boolean {
136137
if (result.json?.error?.code === 'SESSION_NOT_FOUND') return true;
137138
return (
138139
step === MICROPHONE_PERMISSION_RESET_STEP &&
139140
result.json?.error?.code === 'INVALID_ARGS' &&
140-
result.json?.error?.message === 'permission setting requires an active app in session'
141+
result.json?.error?.details?.reason === PUBLISHED_ERROR_REASONS.sessionAppRequired
141142
);
142143
}

‎website/docs/docs/commands.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -506,6 +506,7 @@ A read-only command such as `get`, `snapshot`, or `wait` reports `no`: a retry r
506506
On Android, a command that first dismissed a blocking system dialog or an ANR prompt still reports as if that dismissal had not happened: a read stays `no`, and a mutation keeps its own verdict. The dismissal is not counted as a dispatched step.
507507
Once any step of a request reached the device, its failure is `unknown`, and `error.details.dispatchedSteps` counts those steps. A `batch` or a replay reports `no` only when none of its executed steps changed the app.
508508
A failure without `dispatched` gives no such guarantee. Treat it as `unknown`.
509+
Two refusals the daemon makes before it routes anywhere carry their reason alongside `dispatched: no`, so a driver can branch instead of matching the message: `error.details.reason: session_or_device_selector_required` means the command had neither an active session nor a device selector to resolve, so opening a session or passing `--platform` is the fix; `session_app_required` means a per-app setting was asked for while the request carried no app, so `open <app>` is the fix.
509510
On a WebDriver-backed device cloud, a request whose driver does not implement its route fails with `error.details.reason: webdriver_route_unsupported` and `dispatched: no`; the driver answered before it ran anything, so the failure is about the cloud's driver, not the device. A command with a sibling route (`orientation` tries two) consumes that refusal and tries the other; only when every route is refused does the command fail. After an ambiguous failure on that transport, only a request that reads and changes nothing is resent; a request that can change the app is sent once.
510511
`type` accepts text only. Do not pass `@ref` to `type`; use `fill @ref "text"` to target a field directly, or `press @ref` then `type "text"` to append in the focused field.
511512
If `type` reports `TEXT_INPUT_NOT_FOCUSED`, focus a visible text input and retry; when accessibility does not expose the input, use a coordinate focus command before typing.
@@ -779,7 +780,7 @@ agent-device settings permission reset screen-recording --platform macos
779780
- Android `settings airplane on|off` is applied by the connectivity service (`cmd connectivity airplane-mode`, Android 11+), which drives the radios rather than only writing the `airplane_mode_on` setting. The response reports the `airplaneMode` that service holds after the change, and Android builds without that command fail without changing device state. Connectivity takes a moment to settle after the switch, so poll the app under test rather than asserting offline behavior immediately.
780781
- Fingerprint simulation is supported on Android targets where `cmd fingerprint` or `adb emu finger` is available.
781782
On physical Android devices, only `cmd fingerprint` is attempted.
782-
- Permission actions are scoped to the active session app.
783+
- Permission actions are scoped to the active session app. With no app bound to the session and none named for the request, `settings permission` and an on/off `settings location` refuse with `INVALID_ARGS` and `error.details.reason: session_app_required` and `dispatched: no`, so nothing was changed on the device: `open <app>` and retry the same command.
783784
- iOS permission targets: `all`, `camera`, `microphone`, `photos` (`full` or `limited`), `contacts`, `contacts-limited`, `notifications`, `calendar`, `location`, `location-always`, `media-library`, `motion`, `reminders`, `siri`. `all` travels as one `simctl privacy … all` call.
784785
- On iOS, which of those services a runtime actually changes is `simctl privacy`'s own verdict, not its help text: Xcode 26 omits `camera` from the list while granting it. A service the runtime refuses fails with `UNSUPPORTED_OPERATION` naming the service; on current runtimes that is `notifications`, which a targeted change cannot reach and `all` leaves untouched.
785786
- Android permission targets: `all`, `calendar`, `camera`, `contacts`, `location`, `media-library`, `microphone`, `notifications`, `photos`. `contacts` fans out to `READ_CONTACTS`+`WRITE_CONTACTS`, `location` to `FINE`+`COARSE`, `calendar` to `READ`+`WRITE`; named multi-id targets intersect the package's declared permissions so a coarse-only or read-only app still succeeds, while a target declaring none of its ids fails loudly. `all` resolves against the package's declared permissions instead. Every response reports `permission` as the requested target and `permissions: string[]` as the ids actually mutated, in the order applied (`all` folds its applied ids into `permissions` the same way).

0 commit comments

Comments
 (0)