.aea Task Script Specification

This reference defines the .aea task script format accepted by:

  • android-emu-agent task validate
  • android-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:

  1. Strip comments that begin with # outside quoted strings.
  2. Ignore blank lines.
  3. Tokenize the remaining line with shell-style quoting.
  4. Lowercase the first token and treat it as the command keyword.
  5. Convert the command into the JSON task spec shape.
  6. 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, and clear join the remaining line into one selector string. This allows fallback and compound selectors.
  • set-text treats 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, or text:"Email".
  • swipe supports options such as distance=0.8 and duration_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