企业官网建设流程全解析

• 移动开发
• 开发工具

Calabash-Android是一款基于 Cucumber 的 Android 自动化功能测试工具，而query()是它最核心的 API——通过一条字符串查询语法，就能精准定位应用中的任意 UI 元素并提取数据、执行断言。本文带你从零掌握 Calabash-Android query() 查询语法的完整用法。

query() 返回什么？元素信息的完整清单

调用query()后，Calabash-Android 会返回一个 Ruby 数组，每个匹配的元素被表示为一个 Hash，默认携带以下可用信息：

• id：元素的资源 ID
• text：元素上的文字
• contentDescription：内容描述
• class：原生控件类名
• enabled：是否可用
• rect：坐标与尺寸（center_x、center_y、width、height等）
• description：控件的完整调试描述

query("button index:1") # => [{"id"=>"save", "text"=>"Save", "class"=>"android.widget.Button", # "rect"=>{"center_y"=>724.0, "center_x"=>645.5, "width"=>71, "height"=>64, ...}}]

官方 querying.feature 场景文件完整定义了query()的验收标准：支持按 ID、文字、类名、类名继承、CSS（WebView）、可见性等多种方式匹配，测试步骤实现可参考 querying.rb。

7种基础定位方式：query() 查询语法速查表

💡小技巧：id:'xxx'、text:'xxx'、contentDescription:'xxx'三种写法都可以简写为marked:'xxx'，例如：

query("* marked:'Save'")

链式调用：查询后直接提取数据

query()支持在查询字符串之后追加方法名，对每个结果依次调用 Java getter——这是它区别于普通控件查找器的精髓：

query("button", "text") # => ["Save", "Cancel", "Login"] query("button", "text", "length") # => [4, 6, 5] 连续调用：先取文本再取长度

对带参数的方法，使用 Hash 传参：

query("edittext index:1", setText: "1234")

进阶用法：可见性、索引与 WebView 深层查询

1. 可见性过滤

Calabash-Android 默认只返回可见元素。想连不可见元素一起查，加前缀all：

query("* id:'twoButton'") # 查不到（元素不可见） query("all * id:'twoButton'") # 可以查到

2. 索引精确定位

query("button index:0") # 第一个按钮

3. 跨层级查询 WebView 内 iframe

在 webview.feature 集成测试中可以看到，多层css连写即可逐层深入：

query("webview css:'iframe' css:'#result'")

query() 与等待、断言的黄金组合

查询出元素后，通常会与等待和断言 API 搭配使用（定义见 wait_helpers.rb 与 ruby_api.md）：

# 等待元素出现（最多 5 秒），超时则用例失败 wait_for_element_exists("button marked:'Save'", timeout: 5) # 轮询等待，避免硬编码 sleep wait_for(timeout: 5) { query("button marked:'Save'").size > 0 } # 断言元素存在/不存在 check_element_exists("* id:'textViewHeader'") check_element_does_not_exist("* text:'Error'")

⚠️ 官方文档特别提醒：优先用wait_for轮询条件，而不是sleep硬等待——前者既快又稳。

上手三步：从骨架到你的第一个查询

1. 安装环境：按 installation.md 配置 Ruby、JDK 与 Android SDK，用 Bundler 安装calabash-android与cucumber。
2. 创建骨架项目：calabash-android init MyApp，骨架内置了 my_first.feature。
3. 编写第一个查询：在 feature 步骤中调用：

element = query("textView id:'textViewHeader'").first element['text'] # 提取文本做断言

更多真实用法可参考集成测试的步骤文件 sample.rb，其中演示了query('checkBox').first['checked']、query("webView css:'#inputButton'")等典型模式；API 全貌见 ruby_api.md。

常见坑与最佳实践清单

• ✅优先用id定位：文字会随多语言变化，ID 最稳定。
• ✅查询结果永远是数组：记得用.first取单个元素。
• ✅默认只查可见元素：查不到时先想想是不是元素还没渲染或被遮挡。
• ✅<VOID>返回值表示调用了 Java 中的void方法，属正常现象。
• ❌别硬 sleep：用wait_for_element_exists替代固定等待。
• ❌别忽略类名大小写：类名查询区分全限定名与简写，如ImageButton匹配android.widget.ImageButton。

掌握query()查询语法后，你就能用 Calabash-Android 对任意 UI 元素做到"查得到、取得出、断得了"，这是编写可靠 Android 功能自动化用例的基石。🎯

• 移动开发
• 开发工具