Skip to content

Commit ea4b179

Browse files
committed
feat: support standalone Maestro clearState command
Accept '- clearState' / '- clearState: <appId>' in Maestro YAML flows. Unlike launchApp.clearState (clear-then-open), the standalone form clears app state without relaunching, projecting to 'settings clear-app-state' on the daemon. Covers the Rocket.Chat login-with-deeplink helper, which previously failed with 'Maestro command "clearState" is not supported'.
1 parent caa3dc2 commit ea4b179

16 files changed

Lines changed: 201 additions & 20 deletions

‎packages/maestro/src/internal/__tests__/program-ir-parser.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -475,6 +475,27 @@ describe('parseMaestroProgram', () => {
475475
);
476476
});
477477

478+
test('parses standalone clearState with an explicit or config app id', () => {
479+
const program = parseMaestroProgram(
480+
`appId: example.app
481+
---
482+
- clearState: example.app
483+
- clearState
484+
`,
485+
{ sourcePath: '/flows/clear.yaml' },
486+
);
487+
488+
assert.deepEqual(program.commands[0], {
489+
kind: 'clearState',
490+
source: { path: '/flows/clear.yaml', line: 3 },
491+
appId: 'example.app',
492+
});
493+
assert.deepEqual(program.commands[1], {
494+
kind: 'clearState',
495+
source: { path: '/flows/clear.yaml', line: 4 },
496+
});
497+
});
498+
478499
test('preserves source paths for unsupported and malformed flows', () => {
479500
const sourcePath = '/flows/includes/child.yaml';
480501
assert.throws(

‎packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ export function makeOperations(
5959
resolveGestureViewport: async () => ({ x: 0, y: 0, width: 402, height: 874 }),
6060
launchApp: noOp,
6161
stopApp: noOp,
62+
clearState: noOp,
6263
openLink: noOp,
6364
tapOn: noOp,
6465
doubleTapOn: noOp,

‎packages/maestro/src/internal/__tests__/runtime-port.test.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,28 @@ describe('MaestroRuntimePort', () => {
122122
});
123123
});
124124

125+
test('dispatches standalone clearState with an explicit or config app id', async () => {
126+
const calls: RecordedCall[] = [];
127+
const operations = makeOperations({
128+
clearState: vi.fn(async (input, context) => record(calls, 'clearState', input, context)),
129+
});
130+
const program = parseMaestroProgram(
131+
[
132+
'appId: com.example.checkout',
133+
'---',
134+
'- clearState: com.example.checkout',
135+
'- clearState',
136+
].join('\n'),
137+
);
138+
139+
const result = await executeMaestroProgram(program, createMaestroRuntimePort(operations));
140+
141+
expect(result).toMatchObject({ executed: 2, skipped: 0 });
142+
expect(calls.map(({ kind }) => kind)).toEqual(['clearState', 'clearState']);
143+
expect(calls[0]).toMatchObject({ input: { appId: 'com.example.checkout' } });
144+
expect(calls[1]).toMatchObject({ input: { appId: 'com.example.checkout' } });
145+
});
146+
125147
test('preserves observation validity after visual waits and scripts', async () => {
126148
const waitInvalidation = vi.fn();
127149
const scriptInvalidation = vi.fn();

‎packages/maestro/src/internal/conformance-normalize.ts‎

Lines changed: 50 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ export type CanonicalCommand =
7777
| { kind: 'takeScreenshot' }
7878
| { kind: 'waitForAnimationToEnd'; timeout?: number | string }
7979
| { kind: 'stopApp' }
80+
| { kind: 'clearState'; appId?: string }
8081
| { kind: 'repeat'; times: string | number }
8182
| { kind: 'retry'; maxRetries?: string | number }
8283
| { kind: 'runFlow'; label?: string; source: 'file' | 'commands' }
@@ -92,22 +93,38 @@ const UPSTREAM_CONFIG_TYPES = new Set(['ApplyConfigurationCommand', 'DefineVaria
9293

9394
type UpstreamCommand = { type: string; fields: Record<string, unknown> };
9495

96+
function canonicalizeUpstreamLifecycleCommand(
97+
command: UpstreamCommand,
98+
): CanonicalCommand | undefined {
99+
const f = command.fields;
100+
switch (command.type) {
101+
case 'LaunchAppCommand':
102+
return dropUndefined({
103+
kind: 'launchApp' as const,
104+
appId: str(f.appId),
105+
clearState: bool(f.clearState),
106+
stopApp: bool(f.stopApp),
107+
});
108+
case 'StopAppCommand':
109+
return { kind: 'stopApp' };
110+
case 'ClearStateCommand':
111+
return dropUndefined({ kind: 'clearState' as const, appId: str(f.appId) });
112+
default:
113+
return undefined;
114+
}
115+
}
116+
95117
export function canonicalizeUpstreamFlow(commands: UpstreamCommand[]): CanonicalCommand[] {
96118
return commands
97119
.filter((command) => !UPSTREAM_CONFIG_TYPES.has(command.type))
98120
.map(canonicalizeUpstreamCommand);
99121
}
100122

101123
function canonicalizeUpstreamCommand(command: UpstreamCommand): CanonicalCommand {
124+
const lifecycle = canonicalizeUpstreamLifecycleCommand(command);
125+
if (lifecycle) return lifecycle;
102126
const f = command.fields;
103127
switch (command.type) {
104-
case 'LaunchAppCommand':
105-
return dropUndefined({
106-
kind: 'launchApp',
107-
appId: str(f.appId),
108-
clearState: bool(f.clearState),
109-
stopApp: bool(f.stopApp),
110-
});
111128
case 'TapOnElementCommand': {
112129
const repeat = asRecord(f.repeat);
113130
return canonicalTap({
@@ -196,8 +213,6 @@ function canonicalizeUpstreamCommand(command: UpstreamCommand): CanonicalCommand
196213
kind: 'waitForAnimationToEnd',
197214
timeout: numLike(f.timeout) ?? str(f.timeout),
198215
});
199-
case 'StopAppCommand':
200-
return { kind: 'stopApp' };
201216
case 'RepeatCommand':
202217
return { kind: 'repeat', times: numLike(f.times) ?? str(f.times) ?? '' };
203218
case 'RetryCommand':
@@ -302,8 +317,19 @@ export function canonicalizeAgentCommands(
302317
return program.commands.map((command) => canonicalizeAgentCommand(command, program.config));
303318
}
304319

305-
function canonicalizeAgentCommand(
306-
command: MaestroCommand,
320+
type AgentLifecycleCommand = Extract<
321+
MaestroCommand,
322+
{ kind: 'launchApp' | 'stopApp' | 'clearState' }
323+
>;
324+
325+
function isAgentLifecycleCommand(command: MaestroCommand): command is AgentLifecycleCommand {
326+
return (
327+
command.kind === 'launchApp' || command.kind === 'stopApp' || command.kind === 'clearState'
328+
);
329+
}
330+
331+
function canonicalizeAgentLifecycleCommand(
332+
command: AgentLifecycleCommand,
307333
config: MaestroProgram['config'],
308334
): CanonicalCommand {
309335
switch (command.kind) {
@@ -314,6 +340,19 @@ function canonicalizeAgentCommand(
314340
clearState: command.clearState,
315341
stopApp: command.stopApp,
316342
});
343+
case 'stopApp':
344+
return { kind: 'stopApp' };
345+
case 'clearState':
346+
return dropUndefined({ kind: 'clearState', appId: command.appId ?? config.appId });
347+
}
348+
}
349+
350+
function canonicalizeAgentCommand(
351+
command: MaestroCommand,
352+
config: MaestroProgram['config'],
353+
): CanonicalCommand {
354+
if (isAgentLifecycleCommand(command)) return canonicalizeAgentLifecycleCommand(command, config);
355+
switch (command.kind) {
317356
case 'tapOn': {
318357
const repeat = numLike(command.repeat) ?? 1;
319358
const repeatIsNumber = typeof repeat === 'number';
@@ -408,8 +447,6 @@ function canonicalizeAgentCommand(
408447
return { kind: 'takeScreenshot' };
409448
case 'waitForAnimationToEnd':
410449
return dropUndefined({ kind: 'waitForAnimationToEnd', timeout: numLike(command.timeout) });
411-
case 'stopApp':
412-
return { kind: 'stopApp' };
413450
case 'repeat':
414451
return { kind: 'repeat', times: numLike(command.times) ?? str(command.times) ?? '' };
415452
case 'retry':

‎packages/maestro/src/internal/program-ir-command-parser.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { stripUndefined } from './shared.ts';
33
import type {
44
MaestroAssertTrueCommand,
55
MaestroBackCommand,
6+
MaestroClearStateCommand,
67
MaestroCommand,
78
MaestroEraseTextCommand,
89
MaestroExtendedWaitUntilCommand,
@@ -122,6 +123,7 @@ const COMMAND_VALUE_PARSERS: Readonly<Record<string, CommandValueParser>> = {
122123
back: parseBack,
123124
waitForAnimationToEnd: parseWaitForAnimationToEnd,
124125
stopApp: parseStopApp,
126+
clearState: parseClearState,
125127
runScript: parseMaestroRunScriptCommand,
126128
runFlow: (value, node, context) =>
127129
parseMaestroRunFlowCommand(value, node, context, parseMaestroCommandList),
@@ -447,6 +449,16 @@ function parseStopApp(
447449
return { kind: 'stopApp', source, appId: readRequiredString(value, 'stopApp', context) };
448450
}
449451

452+
function parseClearState(
453+
value: Node | null,
454+
commandNode: Node,
455+
context: MaestroProgramParseContext,
456+
): MaestroClearStateCommand {
457+
const source = sourceAt(commandNode, context);
458+
if (isNullNode(value)) return { kind: 'clearState', source };
459+
return { kind: 'clearState', source, appId: readRequiredString(value, 'clearState', context) };
460+
}
461+
450462
function parseLaunchArguments(
451463
node: Node | null | undefined,
452464
name: string,

‎packages/maestro/src/internal/program-ir.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,12 @@ export type MaestroStopAppCommand = {
207207
appId?: string;
208208
};
209209

210+
export type MaestroClearStateCommand = {
211+
kind: 'clearState';
212+
source: MaestroSourceLocation;
213+
appId?: string;
214+
};
215+
210216
export type MaestroRunScriptCommand = {
211217
kind: 'runScript';
212218
source: MaestroSourceLocation;
@@ -265,6 +271,7 @@ export type MaestroCommand =
265271
| MaestroBackCommand
266272
| MaestroWaitForAnimationToEndCommand
267273
| MaestroStopAppCommand
274+
| MaestroClearStateCommand
268275
| MaestroRunScriptCommand
269276
| MaestroRunFlowCommand
270277
| MaestroRepeatCommand

‎packages/maestro/src/internal/runtime-port-commands.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,9 @@ type MaestroCommandOf<K extends MaestroRuntimeCommand['kind']> = Extract<
2929
{ kind: K }
3030
>;
3131

32-
type MaestroLifecycleCommand = MaestroCommandOf<'launchApp' | 'stopApp' | 'openLink'>;
32+
type MaestroLifecycleCommand = MaestroCommandOf<
33+
'launchApp' | 'stopApp' | 'clearState' | 'openLink'
34+
>;
3335
type MaestroTargetCommand = MaestroCommandOf<'tapOn' | 'doubleTapOn' | 'longPressOn'>;
3436
type MaestroTextCommand = MaestroCommandOf<'inputText' | 'eraseText'>;
3537
type MaestroNavigationCommand = MaestroCommandOf<
@@ -53,6 +55,7 @@ type MaestroRuntimeCommandHandlers = {
5355
const MAESTRO_RUNTIME_COMMAND_HANDLERS = {
5456
launchApp: executeLifecycleCommand,
5557
stopApp: executeLifecycleCommand,
58+
clearState: executeLifecycleCommand,
5659
openLink: executeLifecycleCommand,
5760
tapOn: executeTargetCommand,
5861
doubleTapOn: executeTargetCommand,
@@ -77,6 +80,7 @@ const MAESTRO_RUNTIME_COMMAND_HANDLERS = {
7780
const MAESTRO_COMMAND_REQUIRES_SETTLED_PREDECESSOR = {
7881
launchApp: true,
7982
stopApp: true,
83+
clearState: true,
8084
openLink: true,
8185
tapOn: true,
8286
doubleTapOn: true,
@@ -142,6 +146,13 @@ async function executeLifecycleCommand(
142146
context,
143147
'invalidate',
144148
);
149+
case 'clearState':
150+
return await invokeOperation(
151+
operations.clearState,
152+
{ appId: command.appId ?? request.appId },
153+
context,
154+
'invalidate',
155+
);
145156
case 'openLink':
146157
return await invokeOperation(
147158
operations.openLink,

‎packages/maestro/src/internal/runtime-port-types.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ export type MaestroRuntimeOperations = {
123123
readonly launchArguments?: MaestroLaunchArguments;
124124
}>;
125125
readonly stopApp: MaestroRuntimeOperation<{ readonly appId?: string }>;
126+
readonly clearState: MaestroRuntimeOperation<{ readonly appId?: string }>;
126127
readonly openLink: MaestroRuntimeOperation<{ readonly link: string }>;
127128

128129
readonly tapOn: MaestroRuntimeOperation<{

‎packages/maestro/src/internal/support-matrix.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
22
'Flows: launchApp; runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.',
33
'Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; selector targets poll until available and support recursive index, childOf, above, below, leftOf, rightOf, containsChild, containsDescendants, points, and optional; outer command labels are metadata, not target selectors.',
4-
'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, and stopApp.',
4+
'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, and stopApp.',
55
'Scripts: ordered runScript file/env scripts with http.post, json, and output variables.',
66
] as const;
77

88
export const MAESTRO_COMPAT_LIMITATIONS = [
9-
'Runtime: iOS and Android only; launchApp.clearState supports Android and iOS simulators, launch arguments are Apple-only, and standalone device utility/state commands are unsupported.',
9+
'Runtime: iOS and Android only; launchApp.clearState and standalone clearState support Android and iOS simulators, launch arguments are Apple-only, and other standalone device utility/state commands are unsupported.',
1010
'Expressions: when.true supports boolean literals and maestro.platform comparisons; assertTrue supports literal values and ${VAR} lookups only; repeat.while, evalScript, and broader JavaScript expressions are unsupported.',
1111
'Environment: flow env is the default, AD_VAR_* overrides it, and CLI -e KEY=VALUE wins over both.',
1212
'Failure diagnostics: resolved targets and runFlow paths are rendered, while inputText payloads remain hidden; do not place secrets in diagnostic identifiers.',

‎packages/maestro/test/conformance/expected-divergence.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,12 @@ export const LAYER2_REFERENCE_ONLY = new Set<string>([
137137

138138
// Supported commands that no corpus flow exercises and are therefore verified by
139139
// other means (or explicitly deferred). Listed so coverage stays honest.
140-
export const UNVERIFIED_COMMANDS = new Set<string>([]);
140+
export const UNVERIFIED_COMMANDS = new Set<string>([
141+
// Standalone clearState has no upstream corpus flow; unit tests cover parse,
142+
// canonical projection, runtime dispatch, and daemon projection instead.
143+
// Add an authored/clear-state.yaml flow at the next fixture regeneration.
144+
'clearState',
145+
]);
141146

142147
// Behavioral deviations that are decisions, not parser-level mismatches. These
143148
// are not tied to a single corpus flow; they are recorded so the support matrix

0 commit comments

Comments
 (0)