Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
308 changes: 308 additions & 0 deletions packages/maestro/src/internal/export-flow.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,308 @@
import { parseAllDocuments } from 'yaml';
import { describe, expect, test } from 'vitest';
import { AppError } from '@agent-device/kernel/errors';
import {
exportReplayActionsToMaestro,
inspectMaestroFlow,
MAESTRO_SELECTOR_PROJECTION,
} from '../index.ts';
import { parseReplayScriptDetailed, readReplayScriptMetadata } from '@agent-device/ad-script';
import { projectSelectorExpression } from '@agent-device/selectors';

describe('exportReplayScriptToMaestro', () => {
test('exports app launch, selectors, input, keyboard, assertions, and screenshots', () => {
const result = exportReplayScriptToMaestro(`env USER="Ada"
context platform=ios target=mobile
open com.example.app --relaunch
click id="email"
fill id="email" "ada@example.com"
keyboard dismiss
find text "Continue" exists
screenshot "./artifacts/checkout"
`);

const docs = parseYamlDocs(result.yaml);
expect(() => inspectMaestroFlow(result.yaml, 'export.yaml')).not.toThrow();
expect(docs).toEqual([
{ appId: 'com.example.app', env: { USER: 'Ada' } },
[
{ launchApp: { appId: 'com.example.app', stopApp: true } },
{ tapOn: { id: 'email' } },
{ tapOn: { id: 'email' } },
{ inputText: 'ada@example.com' },
'hideKeyboard',
{ assertVisible: 'Continue' },
{ takeScreenshot: './artifacts/checkout' },
],
]);
expect(result.warnings).toEqual([
{
line: 5,
action: 'fill id="email" ada@example.com',
message:
'fill exports as tapOn + inputText; Maestro may append text instead of replacing existing field contents',
},
]);
});

test('exports each app target when a script switches apps and returns', () => {
const result = exportReplayScriptToMaestro(`open com.example.shop
open com.example.auth
open com.example.shop
`);

expect(() => inspectMaestroFlow(result.yaml, 'apps.yaml')).not.toThrow();
expect(parseYamlDocs(result.yaml)).toEqual([
{ appId: 'com.example.shop' },
[
{ launchApp: { appId: 'com.example.shop' } },
{ launchApp: { appId: 'com.example.auth' } },
{ launchApp: { appId: 'com.example.shop' } },
],
]);
expect(result.warnings).toEqual([]);
});

test('exports the empty-fill clear as eraseText, never a vacuous inputText', () => {
// `fill <target> ""` is the clear-field primitive (#2063); Maestro's `inputText: ""` types
// nothing, so the recorded clear must become its clear verb.
const result = exportReplayScriptToMaestro(`context platform=ios target=mobile
open com.example.app
fill id="email" ""
`);

const docs = parseYamlDocs(result.yaml);
expect(docs[1]).toEqual([
{ launchApp: { appId: 'com.example.app' } },
{ tapOn: { id: 'email' } },
'eraseText',
]);
expect(result.warnings).toEqual([
{
line: 3,
action: 'fill id="email"',
message:
'fill "" exports as tapOn + eraseText; Maestro erases at most its 50-character default',
},
]);
});

test('exports coordinate gestures and sleep waits with warnings', () => {
const result = exportReplayScriptToMaestro(`open com.example.app
click 120 240
swipe 200 700 200 200 --count 2
wait 500
`);

expect(parseYamlDocs(result.yaml)).toEqual([
{ appId: 'com.example.app' },
[
{ launchApp: { appId: 'com.example.app' } },
{ tapOn: { point: '120,240' } },
{ swipe: { start: '200,700', end: '200,200', duration: 100 } },
{ swipe: { start: '200,700', end: '200,200', duration: 100 } },
{ waitForAnimationToEnd: { timeout: 500 } },
],
]);
expect(result.warnings).toEqual([
{
line: 4,
action: 'wait 500',
message:
'wait <ms> exports as waitForAnimationToEnd and may return before the full duration',
},
]);
});

test('exports wait stable as waitForAnimationToEnd and text or selector waits with their timeouts', () => {
const result = exportReplayScriptToMaestro(`open com.example.app
wait stable
wait stable 500 3000
wait text "Ready" 2000
wait 'id="done"' 4000
wait id="save" enabled=true 25000
wait text Sign in 2000
`);

expect(parseYamlDocs(result.yaml)).toEqual([
{ appId: 'com.example.app' },
[
{ launchApp: { appId: 'com.example.app' } },
'waitForAnimationToEnd',
{ waitForAnimationToEnd: { timeout: 3000 } },
{ extendedWaitUntil: { visible: 'Ready', timeout: 2000 } },
{ extendedWaitUntil: { visible: { id: 'done' }, timeout: 4000 } },
{ extendedWaitUntil: { visible: { id: 'save', enabled: true }, timeout: 25000 } },
{ extendedWaitUntil: { visible: 'Sign in', timeout: 2000 } },
],
]);
const stableWarning =
'wait stable exports as waitForAnimationToEnd, which uses its own screen-stability threshold instead of the quiet window';
expect(result.warnings).toEqual([
{ line: 2, action: 'wait stable', message: stableWarning },
{ line: 3, action: 'wait stable 500 3000', message: stableWarning },
]);
});

test('rejects wait forms that have no on-screen text to wait for', () => {
const run = () =>
exportReplayScriptToMaestro(`open com.example.app
wait @e3
wait text
wait stable 500 junk
wait visible label="Save" 25000
`);
expect(run).toThrowError(AppError);
expect(run).toThrowError('line 2 (wait @e3): wait @ref names a session-local ref');
expect(run).toThrowError('line 3 (wait text): wait text requires the text to wait for');
expect(run).toThrowError(
'line 4 (wait stable 500 junk): wait stable takes at most a numeric quietMs and timeoutMs',
);
// The whole selector reaches the projection, which refuses `visible`; it never exports as text.
expect(run).toThrowError(
'line 5 (wait visible label="Save" 25000): wait selector is not Maestro-compatible',
);
});

// #3197: `scroll --until` became part of a scroll action, so the export names
// the stop condition it cannot carry instead of exporting a bare page scroll.
test('warns when scroll --until exports as a bare Maestro scroll', () => {
const result = exportReplayScriptToMaestro(`open com.example.app
scroll down --until 'id="far-button"'
`);

expect(parseYamlDocs(result.yaml)).toEqual([
{ appId: 'com.example.app' },
[{ launchApp: { appId: 'com.example.app' } }, 'scroll'],
]);
expect(result.warnings).toEqual([
{
line: 2,
// The action label names positionals only, so the flag shows in the message.
action: 'scroll down',
message: 'scroll --until id="far-button" is not represented by Maestro scroll',
},
]);
});

test('warns when explicit long-press durations export to Maestro defaults', () => {
const result = exportReplayScriptToMaestro(`open com.example.app
longpress "label=\\"Last message\\"" 800
click id="hold-button" --hold-ms 1200
press text="Retry" --hold-ms 1500
`);

expect(parseYamlDocs(result.yaml)).toEqual([
{ appId: 'com.example.app' },
[
{ launchApp: { appId: 'com.example.app' } },
{ longPressOn: { text: 'Last message' } },
{ longPressOn: { id: 'hold-button' } },
{ longPressOn: { text: 'Retry' } },
],
]);
expect(result.warnings).toEqual([
{
line: 2,
action: 'longpress label="Last message" 800',
message:
'label= selectors export as Maestro text; Maestro text matching is broader than agent-device label-only matching',
},
{
line: 2,
action: 'longpress label="Last message" 800',
message:
'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 800ms',
},
{
line: 3,
action: 'click id="hold-button"',
message:
'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1200ms',
},
{
line: 4,
action: 'press text="Retry"',
message:
'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1500ms',
},
]);
});

test('warns when double-tap and hold exports ignore repeated tap options', () => {
const result = exportReplayScriptToMaestro(`open com.example.app
click id="retry" --double-tap --count 2 --interval-ms 200
press text="Hold" --hold-ms 1000 --count 3 --interval-ms 150
`);

expect(parseYamlDocs(result.yaml)).toEqual([
{ appId: 'com.example.app' },
[
{ launchApp: { appId: 'com.example.app' } },
{ doubleTapOn: { id: 'retry' } },
{ longPressOn: { text: 'Hold' } },
],
]);
expect(result.warnings).toEqual([
{
line: 2,
action: 'click id="retry"',
message: 'tap --count 2 is not represented by Maestro doubleTapOn',
},
{
line: 2,
action: 'click id="retry"',
message: 'tap --interval-ms 200 is not represented by Maestro doubleTapOn',
},
{
line: 3,
action: 'press text="Hold"',
message:
'long-press duration exports as Maestro longPressOn; Maestro uses its default long-press duration instead of 1000ms',
},
{
line: 3,
action: 'press text="Hold"',
message: 'tap --count 3 is not represented by Maestro longPressOn',
},
{
line: 3,
action: 'press text="Hold"',
message: 'tap --interval-ms 150 is not represented by Maestro longPressOn',
},
]);
});

test('rejects native-only replay actions', () => {
expect(() =>
exportReplayScriptToMaestro(`open com.example.app
snapshot -i
get text id="status"
`),
).toThrowError(AppError);
try {
exportReplayScriptToMaestro(`open com.example.app
snapshot -i
get text id="status"
`);
} catch (error) {
expect(error).toBeInstanceOf(AppError);
expect((error as AppError).message).toContain('line 2 (snapshot)');
expect((error as AppError).message).toContain('line 3 (get text id="status")');
}
});
});

function exportReplayScriptToMaestro(script: string) {
const parsed = parseReplayScriptDetailed(script);
return exportReplayActionsToMaestro(parsed.actions, {
actionLines: parsed.actionLines,
metadata: readReplayScriptMetadata(script),
resolveSelector: (expression) =>
projectSelectorExpression(expression, MAESTRO_SELECTOR_PROJECTION),
});
}

function parseYamlDocs(script: string): unknown[] {
return parseAllDocuments(script).map((doc) => doc.toJSON());
}
46 changes: 46 additions & 0 deletions src/__tests__/cli-maestro-suite.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import { test } from 'vitest';
import assert from 'node:assert/strict';
import { promises as fs } from 'node:fs';
import path from 'node:path';
import { runCliCapture } from './cli-capture.ts';
import { mkdtempForTest } from '@agent-device/test-kit';

test('test --maestro forwards Maestro backend and platform for directory suites', async () => {
const tmpDir = await mkdtempForTest('agent-device-cli-maestro-suite-');
await fs.writeFile(
path.join(tmpDir, 'auth-flow.yml'),
['appId: demo.app', '---', '- launchApp', ''].join('\n'),
);

try {
const result = await runCliCapture(
['test', '--maestro', '--platform', 'android', tmpDir],
async () => ({
ok: true,
data: {
total: 1,
executed: 1,
passed: 1,
failed: 0,
skipped: 0,
notRun: 0,
durationMs: 5,
failures: [],
tests: [],
},
}),
{ cwd: tmpDir },
);

assert.equal(result.code, null);
assert.equal(result.calls.length, 1);
assert.equal(result.calls[0]?.command, 'test');
assert.deepEqual(result.calls[0]?.positionals, [tmpDir]);
assert.equal(result.calls[0]?.flags?.replayBackend, 'maestro');
assert.equal(result.calls[0]?.flags?.platform, 'android');
assert.equal(result.calls[0]?.meta?.requestProgress, 'replay-test');
assert.doesNotMatch(result.stderr, /Running replay suite\.\.\./);
} finally {
await fs.rm(tmpDir, { recursive: true, force: true });
}
});
Loading
Loading