变量与 Include

Tapilot DSL 支持两类变量:

• 静态变量(vars 段)— parse 时替换,像模板
• 运行时变量(readText / forEach 写入)— execute 时动态替换

加上 include 机制,可以把共用脚本提成片段复用。

静态变量(vars)

id: login-test
platform: android
vars:
  USERNAME: admin
  PASSWORD: mobai2026
  HOST: example.com
steps:
  - input: "${USERNAME}@${HOST}"   # "admin@example.com"
  - input: "${PASSWORD}"

规则

• 在 YAML 被解析 之前 做字符串替换
• ${VAR} 可以出现在任意位置(字段值、嵌套对象、复杂结构)
• 未替换的 ${UNKNOWN} 原样保留(不会报错,方便和运行时变量共存)

运行时传入(覆盖 vars)

调用方可以传 runtimeVars 覆盖 YAML 里的 vars:

const script = parseScript(yaml, {
  runtimeVars: { USERNAME: "test-ci-bot", PASSWORD: "..." }
});

适合 CI 场景:把敏感值放环境变量,不硬编码到 YAML。

运行时变量

由 readText 或 forEach 在执行时写入,后续 step 用 ${VAR} 或 ${VAR.field} 引用。

readText 写入

- tap: 发送验证码
- wait: 3000
- readText:
    regex: "(\\d{6})"           # 或 label: "您的验证码是"
    into: CODE
- input: "${CODE}"              # 运行时展开成 6 位数字

forEach 迭代写入

- forEach:
    var: U
    from: ./users.csv           # CSV 两列:email,password
    steps:
      - webType: { selector: "#email", text: "${U.email}" }
      - webType: { selector: "#pass", text: "${U.password}" }
      - webClick: { text: 登录 }

当前迭代行是对象 → ${var.field} 取字段;是字符串 → ${var} 取整值。迭代结束该变量自动清除,不会影响后续 step。

include 子脚本

把共用 step 序列放进另一个 YAML:

# common/login.yaml
id: common-login
platform: android
steps:
  - launch: { package: com.example.app, force: true }
  - waitStable: { timeoutMs: 5000 }
  - input: "${USERNAME}"
  - tap: Next
  - input: "${PASSWORD}"
  - tap: Login

主脚本引用:

# main-flow.yaml
id: main-flow
platform: android
vars:
  USERNAME: admin
  PASSWORD: mobai2026
include:
  - ./common/login.yaml
steps:
  # include 的 steps 会插到前面,这里是登录成功后的后续
  - tap: Dashboard
  - assert: Welcome

规则

• include 里的 steps 会插到当前脚本 steps 之前
• vars 传递给 include 脚本(共享)
• 相对路径基于主 YAML 文件所在目录
• 可多层嵌套(A include B,B include C)

组合示例:数据驱动登录测试

# tests/dsl-examples/batch-login.yaml
id: batch-login
platform: web
vars:
  BASE_URL: https://example.com
steps:
  - openBrowser: "${BASE_URL}/login"
  - forEach:
      var: U
      from: ./users.csv       # email,password,expected_role
      steps:
        - webType: { selector: "#email", text: "${U.email}" }
        - webType: { selector: "#password", text: "${U.password}" }
        - webClick: { text: Sign in }
        - waitFor: Dashboard
        - readText: { label: 欢迎回来, into: DISPLAYED_NAME }
        - assertVisual: "右上角角色标签显示 ${U.expected_role}"
        - webClick: { text: Logout }
        - waitFor: Sign in

变量命名规则

• readText / forEach 的 into / var 必须是大写 + 下划线(正则:^[A-Z][A-Z0-9_]*$)
  • ✅ CODE / USER_ID / TOKEN_V2
  • ❌ code / userCode(校验会失败)
• 静态 vars 没这个限制,但强烈建议也用大写,避免和运行时变量混淆

相关

• 循环与条件 — repeat / forEach / ifExists
• 动作列表 — 完整 36 actions 参考