.aea Task Script Specification
This reference defines the .aea task script format accepted by:
android-emu-agent task validateandroid-emu-agent task run
.aea scripts are compact, line-oriented files that compile into the JSON task harness shape:
metadata, ordered steps, optional step verifiers, and optional final verifiers.
For a hands-on guide, see Create and Run Task Scripts.
File Types
The CLI parses files with these suffixes as task scripts:
| Suffix | Meaning |
|---|---|
.aea |
Standard task script |
.aea-task |
Task script alias |
.aea-replay |
Task script alias for replay-style flows |
Other task files are parsed as JSON.
Processing Model
The parser reads the file one line at a time:
- Strip comments that begin with
#outside quoted strings. - Ignore blank lines.
- Tokenize the remaining line with shell-style quoting.
- Lowercase the first token and treat it as the command keyword.
- Convert the command into the JSON task spec shape.
- Validate the compiled task shape before execution.
A script is invalid when it contains no steps and no final verifiers.
Lexical Rules
| Rule | Behavior | Example |
|---|---|---|
| Comments | # starts a comment outside single or double quotes. |
tap text:"Pay #1" # comment |
| Quoting | Single or double quotes preserve spaces. | description "Open checkout and verify payment" |
| Options | Options start with an unquoted key= prefix. |
wait idle timeout_ms="5000" |
| Option keys | - normalizes to _. |
duration-ms=300 becomes duration_ms. |
| Booleans | true and false become booleans. |
wait_debugger=true |
| Numbers | Numeric coercion applies to timeout_ms, duration_ms, duration, and distance. |
distance=0.8 |
| Selectors | Selector-like tokens are values even when they contain =. |
text:"Save" enabled:true |
Option keys start with an ASCII letter or _, followed by ASCII letters, digits, _, or -. Quote
the whole token to use key=value as literal text: "timeout_ms=5000" is text, whereas
timeout_ms="5000" is an option. Escaping the = also makes a token literal (x\=y). Options can
appear before or after positional values. Query URLs and selector tokens are values because their
prefixes are not option keys. For URLs containing #, quote the URL to preserve its fragment.
deeplink "https://example.com/search?q=android&sort=date#results"
set-text id:com.example:id/search "x=y"
wait text "Total=5" timeout_ms=5000
expect text "timeout_ms=5000" timeout_ms=1000
Malformed numeric options on swipe, wait, verify, and expect lines report ERR_TASK_SCRIPT_INVALID
with the source file, line number, and option name. Millisecond options and duration require
integer syntax; distance requires a finite number (not nan, inf, or an overflowing exponent).
Validation and execution reject these scripts before any device action runs. Valid numeric
conversions and runtime range checks are unchanged.
Selector-like tokens are recognized when they start with one of these prefixes:
^text:id:desc:class:coords:
Metadata Commands
Metadata commands set top-level task fields.
| Command | Required | Compiled field | Notes |
|---|---|---|---|
name <text> |
No | name |
Defaults to unnamed script task when omitted. |
description <text> |
No | description |
Preserved as task metadata. |
session <session_id> |
No | session_id |
Used by task run when --session is omitted. |
Example:
name "checkout smoke"
description "Tap checkout and verify payment UI state."
session s-abc123
Step Commands
Step commands append entries to steps.
App Steps
| Script form | Compiled operation | Required values |
|---|---|---|
launch <package> |
{"app": "launch"} |
package |
force-stop <package> |
{"app": "force_stop"} |
package |
deeplink <uri> |
{"app": "deeplink"} |
uri |
Example:
launch com.example.app
force-stop com.example.app
deeplink https://example.com/checkout
Action Steps
| Script form | Compiled operation | Required values |
|---|---|---|
tap <selector> |
{"action": "tap"} |
ref containing a ref or selector string |
long-tap <selector> |
{"action": "long_tap"} |
ref containing a ref or selector string |
clear <selector> |
{"action": "clear"} |
ref containing a ref or selector string |
set-text <selector> <text> |
{"action": "set_text"} |
ref, text |
swipe <direction> |
{"action": "swipe"} |
direction |
back |
{"action": "back"} |
None |
home |
{"action": "home"} |
None |
recents |
{"action": "recents"} |
None |
Example:
tap text:"Checkout" || id:com.example:id/checkout
long-tap desc:"Item menu"
clear id:com.example:id/search
set-text id:com.example:id/email "agent@example.com"
swipe down distance=0.8 duration_ms=300
back
home
recents
Notes:
tap,long-tap, andclearjoin the remaining line into one selector string. This allows fallback and compound selectors.set-texttreats the first value token as the selector and the rest of the line as text. Use a single selector token such as^g1a2,id:com.example:id/email, ortext:"Email".swipesupports options such asdistance=0.8andduration_ms=300.
Wait Steps
| Script form | Compiled operation | Required values |
|---|---|---|
wait idle |
{"wait": "idle"} |
None |
wait activity <activity> |
{"wait": "activity"} |
activity |
wait text <text> |
{"wait": "text"} |
text |
wait exists <selector> |
{"wait": "exists"} |
ref selector string |
wait gone <selector> |
{"wait": "gone"} |
ref selector string |
Example:
wait idle timeout_ms=5000
wait activity HomeActivity timeout_ms=15000
wait text "Payment complete" timeout_ms=5000
wait exists text:"Payment" timeout_ms=5000
wait gone text:"Loading" timeout_ms=10000
exists and gone accept a snapshot ref or one element selector, including quoted values,
regex selectors, and compound boolean state filters such as text:"Payment" enabled:true.
The compiled ref string is normalized to a selector dictionary before dispatch unless it is a
snapshot ref. Coordinates and || fallback chains are action targets, not wait conditions;
using either in a wait or verifier fails task validation before any steps run.
UI Steps
| Script form | Compiled operation | Notes |
|---|---|---|
snapshot |
{"ui": "snapshot"} |
Uses compact mode by default. |
snapshot mode=compact |
{"ui": "snapshot", "mode": "compact"} |
Compact actionable snapshot. |
snapshot mode=full |
{"ui": "snapshot", "mode": "full"} |
Full UI hierarchy snapshot. |
snapshot mode=raw |
{"ui": "snapshot", "mode": "raw"} |
Raw XML hierarchy. |
Verifiers
Verifiers use the same operations as wait steps: idle, activity, text, exists, and gone.
| Command | Scope | Placement |
|---|---|---|
verify <operation> ... |
Previous step only | Must appear after a step. |
expect <operation> ... |
Final task verifier | Can appear anywhere after metadata. |
Example:
tap text:"Continue" || id:com.example:id/continue
verify exists text:"Welcome" timeout_ms=5000
expect activity HomeActivity
A verify line before any step is invalid.
Selector Values
Script selector expressions use the same parser as action targets. Actions support the forms
below; wait, verify, and expect conditions support the single-element forms and snapshot
refs, but not coordinates or || fallback chains. Snapshot refs use ^g<generation>a<element>;
copy the complete token from the latest snapshot. Common forms:
^g1a1
text:"Sign in"
text-contains:"Pay"
id:com.example:id/login
desc:"Open menu"
label:"Open menu"
class:android.widget.Button
coords:540,1200
text:"Sign in" || id:com.example:id/login
text:"Sign in" enabled:true clickable:true
Quotes around selector values are retained when the script is compiled. This keeps spaces,
apostrophes, colons, and literal || inside labels from becoming selector syntax:
tap text:"Sign in" enabled:true
tap desc:"Don't stop" || text:"Continue: next step"
tap text:"A || B"
set-text 'text:"Email address" enabled:true' "agent@example.com"
swipe up container='desc:"Message list" scrollable:true'
For set-text and container=, wrap a complete compound or fallback selector in single quotes to
keep it in one argument. Shell-style decoding still applies to data and backslash escapes;
set-text content and wait text values are ordinary text, not selector expressions.
Run this command when an automation planner needs to discover supported selector forms:
android-emu-agent device capabilities --session <session-id> --json
Literal Quotes in Selector Values
Selector values lose only their matching outer quote pair. For example, tap text:"James'" keeps
the trailing apostrophe, and tap text:"'Accept'" enabled:true selects the label 'Accept',
including both apostrophes. Use double quotes around literal apostrophes or single quotes around
literal double quotes. The same rule applies to action targets, swipe containers, and
wait/verify/expect element selectors. Empty quoted values are still invalid; this does not
introduce additional escape processing.
Compiled Shape
This script:
name "login smoke"
session s-abc123
launch com.example.app
wait exists text:"Sign in" timeout_ms=5000
tap text:"Sign in" || id:com.example:id/login
verify exists text:"Email"
set-text id:com.example:id/email "agent@example.com"
expect activity MainActivity
Compiles to this task shape:
{
"name": "login smoke",
"session_id": "s-abc123",
"steps": [
{ "app": "launch", "package": "com.example.app" },
{ "wait": "exists", "ref": "text:Sign in", "timeout_ms": 5000 },
{
"action": "tap",
"ref": "text:Sign in || id:com.example:id/login",
"verify": [{ "type": "exists", "ref": "text:Email" }]
},
{ "action": "set_text", "ref": "id:com.example:id/email", "text": "agent@example.com" }
],
"verifiers": [{ "type": "activity", "activity": "MainActivity" }]
}
Validation
Validate every script before running it:
android-emu-agent task validate examples/tasks/checkout-smoke.aea
Validation checks:
- Script syntax.
- Required command arguments.
- Supported task operations.
- Compiled task shape.
Validation does not contact a device and does not confirm that selectors exist on the target screen.
Error Codes
| Error code | Meaning | Recovery |
|---|---|---|
ERR_TASK_SCRIPT_INVALID |
The line-oriented parser rejected the script. | Fix the reported line and run task validate again. |
ERR_TASK_INVALID |
The compiled JSON task shape is invalid. | Fix required fields such as ref, text, package, or activity. |
ERR_TASK_UNSUPPORTED_STEP |
The task uses an unsupported action, wait, app, or UI operation. | Use the supported command forms in this specification. |
ERR_NOT_FOUND |
A selector did not match during execution. | Capture a fresh snapshot and update the selector. |
ERR_TIMEOUT |
A wait or verifier did not complete before timeout. | Check actual state or increase timeout_ms. |
ERR_EXPECTATION_FAILED |
A final expectation failed. | Inspect the failure payload and collect artifacts before retrying. |
Minimal Example
name "idle snapshot"
wait idle timeout_ms=5000
snapshot mode=compact
App Flow Example
name "login flow smoke"
launch com.example.app
wait idle timeout_ms=10000
tap text:"Sign in" || id:com.example:id/sign_in
verify exists text:"Email" timeout_ms=5000
set-text id:com.example:id/email "agent@example.com"
set-text id:com.example:id/password "test-password"
tap text:"Continue" || id:com.example:id/continue
expect activity HomeActivity