auditing-compose-test-suite

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auditing a Compose Test Suite — Six-Phase Review, Then Route

审计 Compose 测试套件——六阶段审查,然后路由

This is an index-style skill. It orchestrates the rest of
compose-test-skills/
into a fixed-order audit pass over an existing test file or test suite. Each phase produces findings; each finding points at the sibling skill that owns the fix. The audit itself never mutates code — that is the job of the routed skills.
这是一个索引型 skill。它将
compose-test-skills/
中的其余 skill 组织起来,对现有测试文件或测试套件执行固定顺序的审计。每个阶段都会产出发现;每项发现都指向负责对应修复的同级 skill。审计本身绝不修改代码——这是被路由到的各个 skill 的职责。

When to use this skill

何时使用此 skill

  • The user pastes a
    *Test.kt
    (or several) and asks "what's wrong with this", "review this", "audit this".
  • The user reports systemic flakes, slow CI, or "the test passes locally but fails on CI".
  • The user is preparing a Compose feature for release and wants the test suite vetted.
  • The user is migrating from v1 (
    UnconfinedTestDispatcher
    ) to v2 (
    StandardTestDispatcher
    ) and wants a checklist of likely-broken tests.
  • The user inherited a test file from another team and is unsure what is correct vs accidentally working.
  • 用户粘贴一个或多个
    *Test.kt
    并询问“这里有什么问题”“请审查”“请审计”。
  • 用户反馈存在系统性 flaky(偶发失败)、CI 运行缓慢,或“测试在本地通过,但在 CI 上失败”。
  • 用户准备发布某项 Compose 功能,希望先对测试套件进行严格审查。
  • 用户正在从 v1(
    UnconfinedTestDispatcher
    )迁移到 v2(
    StandardTestDispatcher
    ),希望获得一份可能已损坏测试的检查清单。
  • 用户从其他团队继承了一个测试文件,不确定哪些行为是正确的,哪些只是碰巧可用。

When NOT to use this skill

何时不应使用此 skill

  • The user has a specific failing assertion and wants it fixed — jump directly to the relevant sibling (most often
    ../../debug/printing-the-semantics-tree/SKILL.md
    for missed matchers, or
    ../../synchronization/testing-animations-deterministically/SKILL.md
    for animation flakes).
  • The user is starting a brand-new test from scratch — start with
    ../../setup/configuring-test-dependencies/SKILL.md
    , then
    ../../setup/choosing-test-rule-vs-runtest/SKILL.md
    , then
    ../../setup/setting-up-host-vs-device-tests/SKILL.md
    .
  • The user wants performance review of production composables — that is
    compose-performance-skills
    , not this repo.
  • 用户有明确的失败断言并希望直接修复——直接转到相关的同级 skill(最常见的是
    ../../debug/printing-the-semantics-tree/SKILL.md
    ,用于处理遗漏的 matcher;或
    ../../synchronization/testing-animations-deterministically/SKILL.md
    ,用于处理动画引起的 flaky)。
  • 用户正在从零开始编写新测试——先从
    ../../setup/configuring-test-dependencies/SKILL.md
    开始,然后是
    ../../setup/choosing-test-rule-vs-runtest/SKILL.md
    ,最后是
    ../../setup/setting-up-host-vs-device-tests/SKILL.md
    。
  • 用户希望审查生产环境 composable 的性能——这应使用
    compose-performance-skills
    ,而不是当前仓库。

Prerequisites

前置条件

  • Read access to the full test file(s) under review. A single test method is too narrow to audit — patterns emerge across a class.
  • The module's
    build.gradle.kts
    (for Phase 1 dep checks) and any
    src/androidTest/AndroidManifest.xml
    if the test uses a custom Activity.
  • Familiarity with the skydoves hot takes encoded in
    ../docs/SPEC.md
    §5 (testTag from production, default
    useUnmergedTree = false
    ,
    mainClock.autoAdvance = false
    for animations,
    waitUntil
    is wall clock,
    runOnIdle
    for state mutations, prefer v2 entry points,
    Thread.sleep
    is a smell).
  • 需要能够读取待审查的完整测试文件。仅审查单个测试方法范围太窄——问题模式会在整个类中显现。
  • 需要模块的
    build.gradle.kts
    (用于阶段 1 的依赖检查);如果测试使用自定义 Activity,还需要
    src/androidTest/AndroidManifest.xml
    。
  • 需要熟悉
    ../docs/SPEC.md
    §5 中编码的 Skydoves 强烈观点(
    testTag
    应来自生产代码,默认使用
    useUnmergedTree = false
    ,动画使用
    mainClock.autoAdvance = false
    ,
    waitUntil
    使用墙上时钟,状态变更使用
    runOnIdle
    ,优先使用 v2 入口点,
    Thread.sleep
    是一种异味)。

Audit pipeline

审计流程

Run the six phases in order. Stop and route to the matching sibling skill the moment a phase produces a finding — fixes in earlier phases sometimes invalidate findings in later ones (e.g. switching from v1 to v2 in Phase 1 can change Phase 5 idle behavior).
按顺序运行六个阶段。一旦某个阶段产生发现,就应停止并路由到匹配的同级 skill——早期阶段的修复有时会使后期阶段的发现失效(例如,阶段 1 从 v1 切换到 v2 可能改变阶段 5 的空闲行为)。

Phase 1 — Setup correctness

阶段 1——配置正确性

What to check on the build/
@Rule
/source-set layer:
  • Gradle: is
    androidx.compose.ui:ui-test-manifest
    on
    debugImplementation
    (instrumentation) /
    testImplementation
    (host)? Is
    ui-test-junit4
    on the matching configuration as the test class?
  • Lint: is
    TestManifestGradleConfiguration
    (severity WARNING) being suppressed?
  • Rule choice:
    createComposeRule()
    vs
    createAndroidComposeRule<A>()
    vs
    createEmptyComposeRule()
    — does the rule match the host? Is the custom Activity declared in
    src/androidTest/AndroidManifest.xml
    ?
  • v1 vs v2 imports: any
    androidx.compose.ui.test.junit4.createComposeRule
    or
    androidx.compose.ui.test.runComposeUiTest
    (deprecated WARNING)?
  • Mixing surfaces: does the same test class declare both
    @get:Rule val rule = createComposeRule()
    AND a
    runComposeUiTest { }
    body?
  • Source set: is the file in
    src/test/
    (host) or
    src/androidTest/
    (device)? Does its capability set match (no
    captureToImage
    , no
    enableAccessibilityChecks
    , no ripple-dependent assertions in host)?
Failure modes route to:
  • Missing/misconfigured deps,
    ActivityNotFoundException
    , lint warning →
    ../../setup/configuring-test-dependencies/SKILL.md
    .
  • Wrong rule constructor, v1 imports, mixed surfaces, double
    setContent
    →
    ../../setup/choosing-test-rule-vs-runtest/SKILL.md
    .
  • Wrong source set, screenshot test on host, accessibility check on host →
    ../../setup/setting-up-host-vs-device-tests/SKILL.md
    .
在 build/
@Rule
/source set 层面检查:
  • Gradle:
    androidx.compose.ui:ui-test-manifest
    是否位于
    debugImplementation
    (instrumentation)/
    testImplementation
    (host)?
    ui-test-junit4
    是否位于与测试类匹配的 configuration?
  • Lint:是否抑制了
    TestManifestGradleConfiguration
    (严重级别为 WARNING)?
  • Rule 选择:
    createComposeRule()
    、
    createAndroidComposeRule<A>()
    与
    createEmptyComposeRule()
    ——所选 Rule 是否与宿主环境匹配?自定义 Activity 是否已在
    src/androidTest/AndroidManifest.xml
    中声明?
  • v1 与 v2 imports:是否存在任何
    androidx.compose.ui.test.junit4.createComposeRule
    或
    androidx.compose.ui.test.runComposeUiTest
    (已弃用,WARNING)?
  • 混用测试界面:同一个测试类是否同时声明了
    @get:Rule val rule = createComposeRule()
    和
    runComposeUiTest { }
    代码块?
  • Source set:文件位于
    src/test/
    (host)还是
    src/androidTest/
    (device)?其能力集是否匹配(host 中不能使用
    captureToImage
    、
    enableAccessibilityChecks
    或依赖 ripple 的断言)?
失败模式路由到:
  • 依赖缺失或配置错误、
    ActivityNotFoundException
    、lint warning →
    ../../setup/configuring-test-dependencies/SKILL.md
    。
  • Rule 构造函数错误、v1 imports、混用测试界面、重复调用
    setContent
    →
    ../../setup/choosing-test-rule-vs-runtest/SKILL.md
    。
  • Source set 错误、在 host 中执行截图测试、在 host 中执行 accessibility check →
    ../../setup/setting-up-host-vs-device-tests/SKILL.md
    。

Phase 2 — Finder discipline

阶段 2——查找器规范

What to check on each
onNode*
/
onAllNodes*
call:
  • Finder choice: count
    onNodeWithTag
    vs
    onNodeWithText
    vs
    onNodeWithContentDescription
    . Heavy
    onNodeWithText
    usage on non-i18n strings is a fragility signal. Skydoves hot take #1:
    Modifier.testTag("…")
    belongs in production under a constant; tests find by tag, not text.
  • Production tag presence: is the matched tag actually applied with
    Modifier.testTag(...)
    in the production composable? If absent, the finder will never match.
  • useUnmergedTree
    : defaults to
    false
    . Is the developer flipping it without a stated reason? Is the test relying on a tag inside a merged subtree (e.g. tag on the
    Text
    inside a
    Button
    ) and matching the wrong (parent) node?
  • Selector chains:
    onChild
    /
    onParent
    propagate
    useUnmergedTree
    . Any chain that flips the flag mid-traversal is suspicious.
  • onAllNodes(...).filter(...)
    vs custom
    SemanticsMatcher
    : is the test re-implementing a prebuilt matcher (
    hasText
    ,
    hasClickAction
    ,
    hasContentDescription
    )?
Failure modes route to:
  • Tag absent in production, text-finder fragility →
    ../../finders/finding-nodes-by-tag-text-content/SKILL.md
    .
  • Wrong merged/unmerged choice or fragile tree navigation →
    ../../finders/traversing-the-semantics-tree/SKILL.md
    .
  • Hand-rolled matcher when a prebuilt exists →
    ../../finders/composing-semantics-matchers/SKILL.md
    .
  • Finder produces zero matches in CI →
    ../../debug/printing-the-semantics-tree/SKILL.md
    .
检查每个
onNode*
/
onAllNodes*
调用:
  • Finder 选择:统计
    onNodeWithTag
    、
    onNodeWithText
    与
    onNodeWithContentDescription
    的使用情况。大量对非 i18n 字符串使用
    onNodeWithText
    是脆弱性的信号。Skydoves 强烈观点 #1:带常量的
    Modifier.testTag("…")
    应放在生产代码中;测试应通过 tag 查找,而不是通过文本查找。
  • 生产代码中的 tag:匹配到的 tag 是否确实通过
    Modifier.testTag(...)
    应用在生产 composable 上?如果没有,Finder 将永远无法匹配。
  • useUnmergedTree
    :默认值为
    false
    。开发者是否在未说明原因的情况下切换它?测试是否依赖合并子树中的 tag(例如
    Button
    内
    Text
    上的 tag),却匹配到了错误的父节点?
  • Selector chains:
    onChild
    /
    onParent
    会传递
    useUnmergedTree
    。任何在遍历过程中切换该标志的链都值得警惕。
  • onAllNodes(...).filter(...)
    与自定义
    SemanticsMatcher
    :测试是否重新实现了已有 matcher(
    hasText
    、
    hasClickAction
    、
    hasContentDescription
    )?
失败模式路由到:
  • 生产代码中缺少 tag、文本 Finder 过于脆弱 →
    ../../finders/finding-nodes-by-tag-text-content/SKILL.md
    。
  • merged/unmerged 选择错误、树遍历脆弱 →
    ../../finders/traversing-the-semantics-tree/SKILL.md
    。
  • 已有 matcher 可用却手写 matcher →
    ../../finders/composing-semantics-matchers/SKILL.md
    。
  • Finder 在 CI 中未找到任何节点 →
    ../../debug/printing-the-semantics-tree/SKILL.md
    。

Phase 3 — Assertion strength

阶段 3——断言强度

What to check on each
assert*
call:
  • assertExists()
    where the test author meant
    assertIsDisplayed()
    : existence in the semantics tree is weaker than on-screen visibility.
  • assertCountEquals(n)
    vs
    assertAny(matcher)
    : is the test brittle on collection size when it really means "at least one matches"?
  • Bounds vs state:
    assertWidthIsEqualTo
    /
    getUnclippedBoundsInRoot
    are state checks against layout. Mixing them with screenshot assertions duplicates work.
  • Text assertions:
    assertTextEquals("Save")
    on user-visible strings drifts across i18n;
    assertTextEquals(context.getString(R.string.save))
    is sturdier.
  • assertIsOn
    /
    assertIsOff
    /
    assertIsSelected
    : these query the toggle/selectable semantics state. Are they being skipped in favor of weaker
    assertExists
    ?
  • Dp.assertIsEqualTo
    tolerance: defaults to ½ dp. Is the test asserting exact pixel equality where a tolerance is more honest?
Failure modes route to:
  • assertExists
    overuse, brittle count vs intent, toggle/selectable state, text assertions →
    ../../assertions/asserting-node-state-and-text/SKILL.md
    .
  • Bounds checks →
    ../../assertions/asserting-bounds-and-dimensions/SKILL.md
    .
检查每个
assert*
调用:
  • 测试作者想表达
    assertIsDisplayed()
    ,却使用了较弱的
    assertExists()
    :仅存在于 semantics 树中,并不等于在屏幕上可见。
  • assertCountEquals(n)
    与
    assertAny(matcher)
    :当测试真正想表达“至少有一个匹配项”时,断言集合大小是否过于脆弱?
  • Bounds 与 state:
    assertWidthIsEqualTo
    /
    getUnclippedBoundsInRoot
    是针对布局的状态检查。将它们与截图断言混用会重复执行工作。
  • 文本断言:
    assertTextEquals("Save")
    断言用户可见字符串,容易随 i18n 变化而失效;
    assertTextEquals(context.getString(R.string.save))
    更稳健。
  • assertIsOn
    /
    assertIsOff
    /
    assertIsSelected
    :这些调用查询 toggle/selectable 的 semantics state。是否使用了较弱的
    assertExists
    ,从而跳过了这些状态断言?
  • Dp.assertIsEqualTo
    容差:默认值为 ½ dp。测试是否在要求精确的像素相等,而使用容差表达会更加合理?
失败模式路由到:
  • 过度使用
    assertExists
    、集合数量断言与测试意图不符、遗漏 toggle/selectable state、文本断言 →
    ../../assertions/asserting-node-state-and-text/SKILL.md
    。
  • Bounds 检查 →
    ../../assertions/asserting-bounds-and-dimensions/SKILL.md
    。

Phase 4 — Action correctness

阶段 4——操作正确性

What to check on each
perform*
call:
  • performGesture { }
    :
    @Deprecated
    everywhere — replace with
    performTouchInput { }
    . This is non-negotiable; the SPEC forbids recommending
    performGesture
    .
  • Coordinate system:
    performTouchInput { down(Offset(x, y)) }
    uses node-local coordinates. Tests that compute global coordinates and pass them to a node-relative DSL produce off-screen taps that silently miss.
  • Touch DSL extensions: is the test re-implementing
    click()
    /
    longClick()
    /
    swipeUp()
    /
    pinch(...)
    from primitive
    down
    /
    moveBy
    /
    up
    calls? Use the high-level extensions when available.
  • Text input:
    performTextInput("foo")
    appends;
    performTextReplacement("foo")
    replaces;
    performTextClearance()
    empties. Wrong choice produces "fooSave" instead of "foo".
  • IME action:
    performImeAction()
    triggers the action set by
    KeyboardOptions.imeAction
    . Is the test using
    Espresso.pressBack()
    or a key event when
    performImeAction()
    is correct?
  • Multi-modal: any test mixing
    performTouchInput
    and
    performMouseInput
    should consider
    performMultiModalInput { touch { … }; mouse { … } }
    for a single-pointer-event timeline.
  • Scroll:
    performScrollToNode
    ,
    performScrollToIndex
    ,
    performScrollToKey
    are LazyList-aware — is the test using a brute-force
    swipeUp
    instead?
Failure modes route to:
  • Deprecated
    performGesture
    , coordinate confusion, swipe primitives →
    ../../actions/injecting-touch-gestures/SKILL.md
    .
  • Text input/replacement/IME action →
    ../../actions/entering-text/SKILL.md
    .
  • Mouse, key, multi-modal →
    ../../actions/injecting-mouse-and-keyboard/SKILL.md
    .
  • Scroll containers (
    performScrollToIndex
    /
    Key
    /
    Node
    ),
    performClick
    →
    ../../actions/clicking-and-scrolling/SKILL.md
    .
  • Higher-level LazyList patterns (visibility,
    state.layoutInfo
    , animated item placement) →
    ../../patterns/testing-lazy-lists/SKILL.md
    .
检查每个
perform*
调用:
  • performGesture { }
    :在所有场景中均已弃用——应替换为
    performTouchInput { }
    。这是不可协商的要求;SPEC 禁止推荐
    performGesture
    。
  • 坐标系:
    performTouchInput { down(Offset(x, y)) }
    使用节点局部坐标。如果测试计算的是全局坐标,却将其传给相对节点的 DSL,便会产生静默落空屏幕之外的点击。
  • Touch DSL 扩展:测试是否使用基础的
    down
    /
    moveBy
    /
    up
    调用重新实现了
    click()
    /
    longClick()
    /
    swipeUp()
    /
    pinch(...)
    ?如果已有高层扩展,应优先使用。
  • 文本输入:
    performTextInput("foo")
    会追加文本;
    performTextReplacement("foo")
    会替换文本;
    performTextClearance()
    会清空文本。选择错误会得到“fooSave”而不是“foo”。
  • IME action:
    performImeAction()
    会触发
    KeyboardOptions.imeAction
    设置的操作。当
    performImeAction()
    合适时,测试是否仍在使用
    Espresso.pressBack()
    或按键事件?
  • 多模态:任何混用
    performTouchInput
    与
    performMouseInput
    的测试,都应考虑使用
    performMultiModalInput { touch { … }; mouse { … } }
    来维持单一指针事件时间线。
  • 滚动:
    performScrollToNode
    、
    performScrollToIndex
    、
    performScrollToKey
    支持 LazyList——测试是否使用了暴力式的
    swipeUp
    ?
失败模式路由到:
  • 已弃用的
    performGesture
    、坐标混淆、手写滑动原语 →
    ../../actions/injecting-touch-gestures/SKILL.md
    。
  • 文本输入/替换、IME action →
    ../../actions/entering-text/SKILL.md
    。
  • Mouse、按键、多模态 →
    ../../actions/injecting-mouse-and-keyboard/SKILL.md
    。
  • 滚动容器(
    performScrollToIndex
    /
    Key
    /
    Node
    )、
    performClick
    →
    ../../actions/clicking-and-scrolling/SKILL.md
    。
  • 更高级的 LazyList 模式(可见性、
    state.layoutInfo
    、动画项目放置)→
    ../../patterns/testing-lazy-lists/SKILL.md
    。

Phase 5 — Time and idle correctness

阶段 5——时间与空闲同步正确性

The flakiest phase. Check each test method end-to-end:
  • Thread.sleep(N)
    : forbidden anywhere except screenshot tests waiting on the RenderThread for ripple completion. Skydoves hot take #7. Anywhere else, replace with
    mainClock.advanceTimeBy(durationMs)
    (test clock) or
    rule.waitUntil(timeoutMillis) { … }
    (wall clock).
  • Animation tests: any test that triggers an animation MUST set
    mainClock.autoAdvance = false
    before
    setContent
    . Otherwise the installed
    InfiniteAnimationPolicy
    cancels infinite animations the moment they start with a
    CancellationException
    . Skydoves hot take #3.
  • Clock vs wall clock:
    mainClock.advanceTimeUntil { … }
    uses the test clock;
    rule.waitUntil(timeoutMillis) { … }
    uses wall clock. Mixing them in the same test produces flakes —
    waitUntil
    will time out while
    advanceTimeUntil
    waits for a clock tick that never comes. Skydoves hot take #4.
  • State mutations off-thread: any
    state.value = X
    from the test thread (not inside
    runOnIdle
    /
    runOnUiThread
    ) races with the recomposer. Skydoves hot take #5.
  • v2 queued work: after migrating to
    androidx.compose.ui.test.v2.*
    ,
    LaunchedEffect
    s are queued under
    StandardTestDispatcher
    . Tests that previously relied on
    UnconfinedTestDispatcher
    eager dispatch may need an explicit
    mainClock.advanceTimeBy(0)
    or
    runCurrent()
    to drain.
  • waitUntil
    timeout: defaults to 1000 ms — is the test using a longer timeout to mask a missing
    IdlingResource
    or to hide a wrong-clock issue?
Failure modes route to:
  • Thread.sleep
    , missing
    IdlingResource
    ,
    waitUntil
    confusion, off-thread state mutation, custom
    IdlingResource
    for external work →
    ../../synchronization/synchronizing-with-idle/SKILL.md
    .
  • Frame-rounding,
    advanceTimeBy
    granularity, v1/v2 dispatcher migration →
    ../../synchronization/controlling-the-test-clock/SKILL.md
    .
  • Animation flakes,
    autoAdvance
    missing,
    InfiniteAnimationPolicy
    CancellationException
    →
    ../../synchronization/testing-animations-deterministically/SKILL.md
    .
这是最容易产生 flaky 的阶段。端到端检查每个测试方法:
  • Thread.sleep(N)
    :除截图测试等待 RenderThread 完成 ripple 外,其他任何位置均禁止使用。Skydoves 强烈观点 #7。其他位置应改用
    mainClock.advanceTimeBy(durationMs)
    (测试时钟)或
    rule.waitUntil(timeoutMillis) { … }
    (墙上时钟)。
  • 动画测试:任何触发动画的测试都必须在
    setContent
    之前设置
    mainClock.autoAdvance = false
    。否则,已安装的
    InfiniteAnimationPolicy
    会在无限动画刚开始时通过
    CancellationException
    将其取消。Skydoves 强烈观点 #3。
  • 测试时钟与墙上时钟:
    mainClock.advanceTimeUntil { … }
    使用测试时钟;
    rule.waitUntil(timeoutMillis) { … }
    使用墙上时钟。在同一个测试中混用会造成 flaky——当
    advanceTimeUntil
    等待一个永远不会到来的时钟 tick 时,
    waitUntil
    就会超时。Skydoves 强烈观点 #4。
  • 跨线程状态变更:测试线程(而非
    runOnIdle
    /
    runOnUiThread
    内部)中的任何
    state.value = X
    都会与 Recomposer 产生竞态。Skydoves 强烈观点 #5。
  • v2 队列任务:迁移到
    androidx.compose.ui.test.v2.*
    后,
    LaunchedEffect
    会在
    StandardTestDispatcher
    下排队。此前依赖
    UnconfinedTestDispatcher
    急切调度的测试,可能需要显式调用
    mainClock.advanceTimeBy(0)
    或
    runCurrent()
    来清空队列。
  • waitUntil
    超时:默认值为 1000 ms——测试是否使用了更长的超时时间,以掩盖缺失的
    IdlingResource
    或错误的时钟问题?
失败模式路由到:
  • Thread.sleep
    、缺失
    IdlingResource
    、
    waitUntil
    混淆、跨线程状态变更、为外部工作创建自定义
    IdlingResource
    →
    ../../synchronization/synchronizing-with-idle/SKILL.md
    。
  • Frame 舍入、
    advanceTimeBy
    粒度、v1/v2 dispatcher 迁移 →
    ../../synchronization/controlling-the-test-clock/SKILL.md
    。
  • 动画引起的 flaky、缺少
    autoAdvance
    、
    InfiniteAnimationPolicy
    的
    CancellationException
    →
    ../../synchronization/testing-animations-deterministically/SKILL.md
    。

Phase 6 — Debug output

阶段 6——调试输出

Sanity-check what the test reveals when it fails:
  • printToLog
    /
    printToString
    : when a finder misses, does the test print the semantics tree to make the failure actionable, or does it just throw
    AssertionError: failed: assertExists
    ?
  • fetchSemanticsNode
    : any direct calls? They're an escape hatch — fine when used sparingly, but a sea of them indicates the test is bypassing the public matcher API.
  • Failure messages: are matcher assertions on collections using the default error (lists all matched/unmatched nodes) or are they swallowed by a custom
    try/catch
    ?
  • Test names: do failing test names tell the developer what was supposed to happen, or do they read like
    testButton1
    ?
Failure modes route to:
  • Non-actionable failures, missing tree dump on miss,
    fetchSemanticsNode
    overuse →
    ../../debug/printing-the-semantics-tree/SKILL.md
    .
  • Accessibility check coverage gap, Robolectric no-op surprise →
    ../../debug/enabling-accessibility-checks/SKILL.md
    .
检查测试失败时能够提供的信息:
  • printToLog
    /
    printToString
    :Finder 未匹配到节点时,测试是否会打印 semantics tree,使失败信息具有可操作性?还是只抛出
    AssertionError: failed: assertExists
    ?
  • fetchSemanticsNode
    :是否存在直接调用?这是应急出口——偶尔使用没有问题,但大量使用表明测试绕过了公开的 matcher API。
  • 失败信息:集合 matcher 断言是否使用默认错误信息(列出所有已匹配和未匹配的节点),还是被自定义
    try/catch
    吞掉了?
  • 测试名称:失败的测试名能否告诉开发者预期发生什么,还是类似
    testButton1
    ?
失败模式路由到:
  • 失败信息不可操作、Finder 未匹配时缺少 tree dump、过度使用
    fetchSemanticsNode
    →
    ../../debug/printing-the-semantics-tree/SKILL.md
    。
  • Accessibility check 覆盖缺口、Robolectric 无实际效果的问题 →
    ../../debug/enabling-accessibility-checks/SKILL.md
    。

Audit report template

审计报告模板

Produce the audit as a Markdown table the user can paste into a PR description. One row per finding. Phases run in order, but findings within a phase can be reordered by severity.
markdown
| # | Phase | File:line | Severity | Finding | Routed skill |
|---|---|---|---|---|---|
| 1 | 1 setup | build.gradle.kts:42 | WARN | ui-test-manifest on androidTestImplementation | ../../setup/configuring-test-dependencies/SKILL.md |
| 2 | 1 setup | FeedTest.kt:18 | WARN | v1 createComposeRule import (deprecated) | ../../setup/choosing-test-rule-vs-runtest/SKILL.md |
| 3 | 2 finder | FeedTest.kt:34 | ERROR | onNodeWithText("Save") — no testTag in production | ../../finders/finding-nodes-by-tag-text-content/SKILL.md |
| 4 | 4 action | FeedTest.kt:51 | ERROR | performGesture { } — deprecated | ../../actions/injecting-touch-gestures/SKILL.md |
| 5 | 5 idle | FeedTest.kt:66 | ERROR | Thread.sleep(2000) before assertion | ../../synchronization/synchronizing-with-idle/SKILL.md |
| 6 | 5 idle | FeedTest.kt:88 | ERROR | autoAdvance not disabled before animation | ../../synchronization/testing-animations-deterministically/SKILL.md |
| 7 | 6 debug | FeedTest.kt:104 | NIT | assertExists with no printToLog on miss | ../../debug/printing-the-semantics-tree/SKILL.md |
Severities (use exactly these three):
  • ERROR — test is broken, flaky, or asserts the wrong thing. Fix before merge.
  • WARN — test runs but encodes a smell that will produce flakes/regressions. Fix this iteration if cheap.
  • NIT — style/maintainability. Fix when adjacent code is touched.
Do NOT autofix. Hand the report to the user; the user (or a follow-up skill invocation against the routed skill) applies the fix.
将审计结果生成为用户可以直接粘贴到 PR 描述中的 Markdown 表格。每个发现占一行。各阶段按顺序运行,但同一阶段内的发现可以按严重程度重新排序。
markdown
| # | Phase | File:line | Severity | Finding | Routed skill |
|---|---|---|---|---|---|
| 1 | 1 setup | build.gradle.kts:42 | WARN | ui-test-manifest on androidTestImplementation | ../../setup/configuring-test-dependencies/SKILL.md |
| 2 | 1 setup | FeedTest.kt:18 | WARN | v1 createComposeRule import (deprecated) | ../../setup/choosing-test-rule-vs-runtest/SKILL.md |
| 3 | 2 finder | FeedTest.kt:34 | ERROR | onNodeWithText("Save") — no testTag in production | ../../finders/finding-nodes-by-tag-text-content/SKILL.md |
| 4 | 4 action | FeedTest.kt:51 | ERROR | performGesture { } — deprecated | ../../actions/injecting-touch-gestures/SKILL.md |
| 5 | 5 idle | FeedTest.kt:66 | ERROR | Thread.sleep(2000) before assertion | ../../synchronization/synchronizing-with-idle/SKILL.md |
| 6 | 5 idle | FeedTest.kt:88 | ERROR | autoAdvance not disabled before animation | ../../synchronization/testing-animations-deterministically/SKILL.md |
| 7 | 6 debug | FeedTest.kt:104 | NIT | assertExists with no printToLog on miss | ../../debug/printing-the-semantics-tree/SKILL.md |
严重级别(必须且仅使用以下三种):
  • ERROR——测试已损坏、存在 flaky 情况或断言了错误内容。合并前必须修复。
  • WARN——测试可以运行,但编码了某种异味,最终会导致 flaky 或回归。如果修复成本较低,应在本次迭代中修复。
  • NIT——风格或可维护性问题。在修改相邻代码时一并修复。
不要自动修复。将报告交给用户;由用户或随后针对所路由 skill 的 skill 调用来应用修复。

Patterns

模式

Pattern: ranking findings by blast radius

模式:按影响范围排列发现

When the same
*Test.kt
produces several findings, prioritize:
  1. Phase 1 setup blockers first. A test on the wrong source set or with mixed surfaces produces undefined behavior; fixing Phase 5 idle issues on top of it wastes effort.
  2. Phase 5 idle issues before Phase 4 actions. A
    Thread.sleep
    masking a missing
    IdlingResource
    makes Phase 4 action issues invisible — once idle is correct, the action timing problems surface clearly.
  3. Phase 2 finder issues before Phase 3 assertions. A finder that targets the wrong node makes every assertion downstream meaningless.
  4. Phase 6 debug output is always the last fix. It improves diagnosis but does not change correctness.
当同一个
*Test.kt
产生多项发现时,按以下顺序确定优先级:
  1. 先处理阶段 1 的配置阻断问题。 测试位于错误的 source set 或混用了测试界面时,会产生未定义行为;在这些问题之上修复阶段 5 的空闲同步问题只会浪费精力。
  2. 阶段 5 的空闲同步问题优先于阶段 4 的操作问题。
    Thread.sleep
    可能掩盖缺失的
    IdlingResource
    ,使阶段 4 的操作问题不可见;空闲同步恢复正确后,操作时序问题才会清晰地显现出来。
  3. 阶段 2 的 Finder 问题优先于阶段 3 的断言问题。 如果 Finder 定位到了错误节点,那么后续所有断言都将失去意义。
  4. 阶段 6 的调试输出始终最后修复。 它可以改善问题诊断,但不会改变测试的正确性。

Pattern: high-signal smells to grep for first

模式:优先 grep 高信号异味

Before reading the test line by line, run these greps to surface the load-bearing smells:
bash
undefined
在逐行阅读测试之前,运行以下 grep 命令来暴露关键性异味:
bash
undefined

Phase 1 — v1 imports (deprecated)

Phase 1 — v1 imports (deprecated)

grep -RIn 'import androidx.compose.ui.test.junit4.createComposeRule' . grep -RIn 'import androidx.compose.ui.test.runComposeUiTest' .
grep -RIn 'import androidx.compose.ui.test.junit4.createComposeRule' . grep -RIn 'import androidx.compose.ui.test.runComposeUiTest' .

Phase 1 — manifest dep on the wrong configuration

Phase 1 — manifest dep on the wrong configuration

grep -RIn 'ui-test-manifest' build.gradle.kts settings.gradle.kts buildSrc/
grep -RIn 'ui-test-manifest' build.gradle.kts settings.gradle.kts buildSrc/

Phase 2 — finder usage ratio (skydoves hot take #1: tag-heavy is correct)

Phase 2 — finder usage ratio (skydoves hot take #1: tag-heavy is correct)

grep -RIcn 'onNodeWithTag|onNodeWithText|onNodeWithContentDescription' src/
grep -RIcn 'onNodeWithTag|onNodeWithText|onNodeWithContentDescription' src/

Phase 4 — deprecated gesture API

Phase 4 — deprecated gesture API

grep -RIn 'performGesture' src/
grep -RIn 'performGesture' src/

Phase 5 — Thread.sleep smell

Phase 5 — Thread.sleep smell

grep -RIn 'Thread.sleep' src/
grep -RIn 'Thread.sleep' src/

Phase 5 — animation tests missing autoAdvance = false

Phase 5 — animation tests missing autoAdvance = false

grep -RIn 'animateFloatAsState|animateDpAsState|animateColorAsState|rememberInfiniteTransition' src/test src/androidTest
grep -RIn 'animateFloatAsState|animateDpAsState|animateColorAsState|rememberInfiniteTransition' src/test src/androidTest

Phase 5 — off-thread mutation pattern (heuristic — review hits manually)

Phase 5 — off-thread mutation pattern (heuristic — review hits manually)

grep -RIn '.value = ' src/test src/androidTest | grep -v 'runOnIdle|runOnUiThread'

The output of these greps populates 60-80 percent of a typical audit report before the first careful read.
grep -RIn '.value = ' src/test src/androidTest | grep -v 'runOnIdle|runOnUiThread'

这些 grep 的输出通常可以在第一次仔细阅读之前填充 60% 至 80% 的典型审计报告。

Pattern: when to stop the audit and re-route

模式:何时停止审计并重新路由

If Phase 1 finds the test is in the wrong source set (e.g. a screenshot test in
src/test/
), STOP. Do not run Phases 2-6. The whole test will be rewritten when moved to
src/androidTest/
— auditing the current incarnation wastes effort. Hand off to
../../setup/setting-up-host-vs-device-tests/SKILL.md
and rerun the audit after the move.
Similarly, if Phase 1 finds a
runComposeUiTest { }
block sharing a class with a
@get:Rule createComposeRule()
, halt and route to
../../setup/choosing-test-rule-vs-runtest/SKILL.md
. The mixed environment makes every later finding ambiguous.
如果阶段 1 发现测试位于错误的 source set(例如在
src/test/
中执行截图测试),立即停止。不要运行阶段 2 至阶段 6。移动到
src/androidTest/
后,整个测试都将重写——审查当前版本只会浪费精力。将任务转交给
../../setup/setting-up-host-vs-device-tests/SKILL.md
,并在移动后重新运行审计。
同样,如果阶段 1 发现
runComposeUiTest { }
代码块与包含
@get:Rule createComposeRule()
的类共存,应立即停止,并路由到
../../setup/choosing-test-rule-vs-runtest/SKILL.md
。混合环境会使后续所有发现都变得含义不明确。

Pattern: presenting the audit to the user

模式:向用户呈现审计结果

End the audit with a short prose summary, then the table. The summary names the top three findings and the single sibling skill the user should run next. Example:
text
The FeedTest.kt suite has 7 findings. The two ERRORs that block correctness are
(1) a Thread.sleep(2000) before the search assertion (FeedTest.kt:66) and
(2) an animation test without mainClock.autoAdvance = false (FeedTest.kt:88).
Run ../../synchronization/testing-animations-deterministically/SKILL.md first;
the autoAdvance fix typically resolves the Thread.sleep finding by exposing
a mainClock.advanceTimeBy(durationMs) replacement.
最后以一段简短文字摘要结束审计,然后给出表格。摘要应点明前三项发现,以及用户接下来应运行的唯一同级 skill。例如:
text
The FeedTest.kt suite has 7 findings. The two ERRORs that block correctness are
(1) a Thread.sleep(2000) before the search assertion (FeedTest.kt:66) and
(2) an animation test without mainClock.autoAdvance = false (FeedTest.kt:88).
Run ../../synchronization/testing-animations-deterministically/SKILL.md first;
the autoAdvance fix typically resolves the Thread.sleep finding by exposing
a mainClock.advanceTimeBy(durationMs) replacement.

Mandatory rules

强制规则

  • MUST NOT mutate code during the audit. The audit produces findings; the routed sibling skill applies the fix.
  • MUST run the six phases in order. Earlier-phase fixes invalidate later-phase findings; the order minimizes wasted effort.
  • MUST route every finding to a single sibling skill. Findings without a routed skill are not actionable and should be omitted from the report.
  • MUST flag every
    Thread.sleep
    outside of a screenshot/RenderThread context as ERROR. Skydoves hot take #7.
  • MUST flag every animation test without
    mainClock.autoAdvance = false
    as ERROR. Skydoves hot take #3.
  • MUST flag every v1 entry point (
    androidx.compose.ui.test.junit4.createComposeRule
    ,
    androidx.compose.ui.test.runComposeUiTest
    ) as WARN. Skydoves hot take #6.
  • MUST flag every
    performGesture { }
    usage as ERROR. The API is
    @Deprecated
    ; the SPEC forbids recommending it.
  • MUST NOT invent findings. If a phase produces nothing, write "Phase N: no findings" — false-positive findings degrade the audit's signal.
  • MUST use the audit report table format (Phase, File:line, Severity, Finding, Routed skill) so subsequent skills can parse the output.
  • PREFERRED: when several findings cluster around one symptom (e.g. "test flakes on CI"), name the symptom in the prose summary and order the table so the routed sibling skill shows up first.
  • MUST NOT 在审计期间修改代码。审计只产出发现;由被路由到的同级 skill 应用修复。
  • MUST 按顺序运行六个阶段。早期阶段的修复会使后期阶段的发现失效;这一顺序可以减少浪费。
  • MUST 将每项发现路由到一个同级 skill。没有路由目标的发现不可执行,应从报告中省略。
  • MUST 将截图或 RenderThread 场景之外的每个
    Thread.sleep
    标记为 ERROR。Skydoves 强烈观点 #7。
  • MUST 将每个未设置
    mainClock.autoAdvance = false
    的动画测试标记为 ERROR。Skydoves 强烈观点 #3。
  • MUST 将每个 v1 入口点(
    androidx.compose.ui.test.junit4.createComposeRule
    、
    androidx.compose.ui.test.runComposeUiTest
    )标记为 WARN。Skydoves 强烈观点 #6。
  • MUST 将每次
    performGesture { }
    使用标记为 ERROR。该 API 已弃用;SPEC 禁止推荐它。
  • MUST NOT 虚构发现。如果某个阶段没有发现,应写明“Phase N: no findings”——误报会降低审计信号的可信度。
  • MUST 使用审计报告表格格式(Phase、File:line、Severity、Finding、Routed skill),以便后续 skill 解析输出。
  • PREFERRED:当多项发现集中在同一症状周围时(例如“测试在 CI 上出现 flaky”),在文字摘要中点明该症状,并调整表格顺序,使对应的同级 skill 排在前面。

Verification

验证

  • Every audit phase ran and produced either findings or "no findings".
  • Every finding has a Severity (ERROR | WARN | NIT) and a routed sibling skill path.
  • No code in the test files under review was mutated by the audit itself.
  • The Phase 1 grep set ran and its output is reflected in the table.
  • The audit report table compiles to valid Markdown (the user can paste it into a PR).
  • If a Phase 1 setup blocker fired (wrong source set, mixed surfaces), Phases 2-6 were skipped and the audit halted with a re-route note.
  • 每个审计阶段均已运行,并产出发现或“no findings”。
  • 每项发现都有 Severity(ERROR | WARN | NIT)和一个同级 skill 路径。
  • 审计本身没有修改待审查测试文件中的任何代码。
  • 阶段 1 的 grep 集合已运行,其结果已反映在表格中。
  • 审计报告表格可以编译为有效的 Markdown(用户可直接粘贴到 PR 中)。
  • 如果阶段 1 出现配置阻断问题(错误的 source set、混用测试界面),则已跳过阶段 2 至阶段 6,并附上重新路由说明。

References

参考资料