auditing-compose-test-suite
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAuditing a Compose Test Suite — Six-Phase Review, Then Route
审计 Compose 测试套件——六阶段审查,然后路由
This is an index-style skill. It orchestrates the rest of 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.
compose-test-skills/这是一个索引型 skill。它将 中的其余 skill 组织起来,对现有测试文件或测试套件执行固定顺序的审计。每个阶段都会产出发现;每项发现都指向负责对应修复的同级 skill。审计本身绝不修改代码——这是被路由到的各个 skill 的职责。
compose-test-skills/When to use this skill
何时使用此 skill
- The user pastes a (or several) and asks "what's wrong with this", "review this", "audit this".
*Test.kt - 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 () to v2 (
UnconfinedTestDispatcher) and wants a checklist of likely-broken tests.StandardTestDispatcher - 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()迁移到 v2(
UnconfinedTestDispatcher),希望获得一份可能已损坏测试的检查清单。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 for missed matchers, or
../../debug/printing-the-semantics-tree/SKILL.mdfor animation flakes).../../synchronization/testing-animations-deterministically/SKILL.md - The user is starting a brand-new test from scratch — start with , then
../../setup/configuring-test-dependencies/SKILL.md, then../../setup/choosing-test-rule-vs-runtest/SKILL.md.../../setup/setting-up-host-vs-device-tests/SKILL.md - The user wants performance review of production composables — that is , not this repo.
compose-performance-skills
- 用户有明确的失败断言并希望直接修复——直接转到相关的同级 skill(最常见的是 ,用于处理遗漏的 matcher;或
../../debug/printing-the-semantics-tree/SKILL.md,用于处理动画引起的 flaky)。../../synchronization/testing-animations-deterministically/SKILL.md - 用户正在从零开始编写新测试——先从 开始,然后是
../../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 (for Phase 1 dep checks) and any
build.gradle.ktsif the test uses a custom Activity.src/androidTest/AndroidManifest.xml - Familiarity with the skydoves hot takes encoded in §5 (testTag from production, default
../docs/SPEC.md,useUnmergedTree = falsefor animations,mainClock.autoAdvance = falseis wall clock,waitUntilfor state mutations, prefer v2 entry points,runOnIdleis a smell).Thread.sleep
- 需要能够读取待审查的完整测试文件。仅审查单个测试方法范围太窄——问题模式会在整个类中显现。
- 需要模块的 (用于阶段 1 的依赖检查);如果测试使用自定义 Activity,还需要
build.gradle.kts。src/androidTest/AndroidManifest.xml - 需要熟悉 §5 中编码的 Skydoves 强烈观点(
../docs/SPEC.md应来自生产代码,默认使用testTag,动画使用useUnmergedTree = false,mainClock.autoAdvance = false使用墙上时钟,状态变更使用waitUntil,优先使用 v2 入口点,runOnIdle是一种异味)。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//source-set layer:
@Rule- Gradle: is on
androidx.compose.ui:ui-test-manifest(instrumentation) /debugImplementation(host)? IstestImplementationon the matching configuration as the test class?ui-test-junit4 - Lint: is (severity WARNING) being suppressed?
TestManifestGradleConfiguration - Rule choice: vs
createComposeRule()vscreateAndroidComposeRule<A>()— does the rule match the host? Is the custom Activity declared increateEmptyComposeRule()?src/androidTest/AndroidManifest.xml - v1 vs v2 imports: any or
androidx.compose.ui.test.junit4.createComposeRule(deprecated WARNING)?androidx.compose.ui.test.runComposeUiTest - Mixing surfaces: does the same test class declare both AND a
@get:Rule val rule = createComposeRule()body?runComposeUiTest { } - Source set: is the file in (host) or
src/test/(device)? Does its capability set match (nosrc/androidTest/, nocaptureToImage, no ripple-dependent assertions in host)?enableAccessibilityChecks
Failure modes route to:
- Missing/misconfigured deps, , lint warning →
ActivityNotFoundException.../../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//source set 层面检查:
@Rule- Gradle:是否位于
androidx.compose.ui:ui-test-manifest(instrumentation)/debugImplementation(host)?testImplementation是否位于与测试类匹配的 configuration?ui-test-junit4 - Lint:是否抑制了 (严重级别为 WARNING)?
TestManifestGradleConfiguration - Rule 选择:、
createComposeRule()与createAndroidComposeRule<A>()——所选 Rule 是否与宿主环境匹配?自定义 Activity 是否已在createEmptyComposeRule()中声明?src/androidTest/AndroidManifest.xml - v1 与 v2 imports:是否存在任何 或
androidx.compose.ui.test.junit4.createComposeRule(已弃用,WARNING)?androidx.compose.ui.test.runComposeUiTest - 混用测试界面:同一个测试类是否同时声明了 和
@get:Rule val rule = createComposeRule()代码块?runComposeUiTest { } - Source set:文件位于 (host)还是
src/test/(device)?其能力集是否匹配(host 中不能使用src/androidTest/、captureToImage或依赖 ripple 的断言)?enableAccessibilityChecks
失败模式路由到:
- 依赖缺失或配置错误、、lint warning →
ActivityNotFoundException。../../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 / call:
onNode*onAllNodes*- Finder choice: count vs
onNodeWithTagvsonNodeWithText. HeavyonNodeWithContentDescriptionusage on non-i18n strings is a fragility signal. Skydoves hot take #1:onNodeWithTextbelongs in production under a constant; tests find by tag, not text.Modifier.testTag("…") - Production tag presence: is the matched tag actually applied with in the production composable? If absent, the finder will never match.
Modifier.testTag(...) - : defaults to
useUnmergedTree. Is the developer flipping it without a stated reason? Is the test relying on a tag inside a merged subtree (e.g. tag on thefalseinside aText) and matching the wrong (parent) node?Button - Selector chains: /
onChildpropagateonParent. Any chain that flips the flag mid-traversal is suspicious.useUnmergedTree - vs custom
onAllNodes(...).filter(...): is the test re-implementing a prebuilt matcher (SemanticsMatcher,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的使用情况。大量对非 i18n 字符串使用onNodeWithContentDescription是脆弱性的信号。Skydoves 强烈观点 #1:带常量的onNodeWithText应放在生产代码中;测试应通过 tag 查找,而不是通过文本查找。Modifier.testTag("…") - 生产代码中的 tag:匹配到的 tag 是否确实通过 应用在生产 composable 上?如果没有,Finder 将永远无法匹配。
Modifier.testTag(...) - :默认值为
useUnmergedTree。开发者是否在未说明原因的情况下切换它?测试是否依赖合并子树中的 tag(例如false内Button上的 tag),却匹配到了错误的父节点?Text - Selector chains:/
onChild会传递onParent。任何在遍历过程中切换该标志的链都值得警惕。useUnmergedTree - 与自定义
onAllNodes(...).filter(...):测试是否重新实现了已有 matcher(SemanticsMatcher、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 call:
assert*- where the test author meant
assertExists(): existence in the semantics tree is weaker than on-screen visibility.assertIsDisplayed() - vs
assertCountEquals(n): is the test brittle on collection size when it really means "at least one matches"?assertAny(matcher) - Bounds vs state: /
assertWidthIsEqualToare state checks against layout. Mixing them with screenshot assertions duplicates work.getUnclippedBoundsInRoot - Text assertions: on user-visible strings drifts across i18n;
assertTextEquals("Save")is sturdier.assertTextEquals(context.getString(R.string.save)) - /
assertIsOn/assertIsOff: these query the toggle/selectable semantics state. Are they being skipped in favor of weakerassertIsSelected?assertExists - tolerance: defaults to ½ dp. Is the test asserting exact pixel equality where a tolerance is more honest?
Dp.assertIsEqualTo
Failure modes route to:
- overuse, brittle count vs intent, toggle/selectable state, text assertions →
assertExists.../../assertions/asserting-node-state-and-text/SKILL.md - Bounds checks → .
../../assertions/asserting-bounds-and-dimensions/SKILL.md
检查每个 调用:
assert*- 测试作者想表达 ,却使用了较弱的
assertIsDisplayed():仅存在于 semantics 树中,并不等于在屏幕上可见。assertExists() - 与
assertCountEquals(n):当测试真正想表达“至少有一个匹配项”时,断言集合大小是否过于脆弱?assertAny(matcher) - Bounds 与 state:/
assertWidthIsEqualTo是针对布局的状态检查。将它们与截图断言混用会重复执行工作。getUnclippedBoundsInRoot - 文本断言:断言用户可见字符串,容易随 i18n 变化而失效;
assertTextEquals("Save")更稳健。assertTextEquals(context.getString(R.string.save)) - /
assertIsOn/assertIsOff:这些调用查询 toggle/selectable 的 semantics state。是否使用了较弱的assertIsSelected,从而跳过了这些状态断言?assertExists - 容差:默认值为 ½ dp。测试是否在要求精确的像素相等,而使用容差表达会更加合理?
Dp.assertIsEqualTo
失败模式路由到:
- 过度使用 、集合数量断言与测试意图不符、遗漏 toggle/selectable state、文本断言 →
assertExists。../../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 call:
perform*- :
performGesture { }everywhere — replace with@Deprecated. This is non-negotiable; the SPEC forbids recommendingperformTouchInput { }.performGesture - Coordinate system: uses node-local coordinates. Tests that compute global coordinates and pass them to a node-relative DSL produce off-screen taps that silently miss.
performTouchInput { down(Offset(x, y)) } - Touch DSL extensions: is the test re-implementing /
click()/longClick()/swipeUp()from primitivepinch(...)/down/moveBycalls? Use the high-level extensions when available.up - Text input: appends;
performTextInput("foo")replaces;performTextReplacement("foo")empties. Wrong choice produces "fooSave" instead of "foo".performTextClearance() - IME action: triggers the action set by
performImeAction(). Is the test usingKeyboardOptions.imeActionor a key event whenEspresso.pressBack()is correct?performImeAction() - Multi-modal: any test mixing and
performTouchInputshould considerperformMouseInputfor a single-pointer-event timeline.performMultiModalInput { touch { … }; mouse { … } } - Scroll: ,
performScrollToNode,performScrollToIndexare LazyList-aware — is the test using a brute-forceperformScrollToKeyinstead?swipeUp
Failure modes route to:
- Deprecated , coordinate confusion, swipe primitives →
performGesture.../../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, , animated item placement) →
state.layoutInfo.../../patterns/testing-lazy-lists/SKILL.md
检查每个 调用:
perform*- :在所有场景中均已弃用——应替换为
performGesture { }。这是不可协商的要求;SPEC 禁止推荐performTouchInput { }。performGesture - 坐标系:使用节点局部坐标。如果测试计算的是全局坐标,却将其传给相对节点的 DSL,便会产生静默落空屏幕之外的点击。
performTouchInput { down(Offset(x, y)) } - Touch DSL 扩展:测试是否使用基础的 /
down/moveBy调用重新实现了up/click()/longClick()/swipeUp()?如果已有高层扩展,应优先使用。pinch(...) - 文本输入:会追加文本;
performTextInput("foo")会替换文本;performTextReplacement("foo")会清空文本。选择错误会得到“fooSave”而不是“foo”。performTextClearance() - IME action:会触发
performImeAction()设置的操作。当KeyboardOptions.imeAction合适时,测试是否仍在使用performImeAction()或按键事件?Espresso.pressBack() - 多模态:任何混用 与
performTouchInput的测试,都应考虑使用performMouseInput来维持单一指针事件时间线。performMultiModalInput { touch { … }; mouse { … } } - 滚动:、
performScrollToNode、performScrollToIndex支持 LazyList——测试是否使用了暴力式的performScrollToKey?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:
- : forbidden anywhere except screenshot tests waiting on the RenderThread for ripple completion. Skydoves hot take #7. Anywhere else, replace with
Thread.sleep(N)(test clock) ormainClock.advanceTimeBy(durationMs)(wall clock).rule.waitUntil(timeoutMillis) { … } - Animation tests: any test that triggers an animation MUST set before
mainClock.autoAdvance = false. Otherwise the installedsetContentcancels infinite animations the moment they start with aInfiniteAnimationPolicy. Skydoves hot take #3.CancellationException - Clock vs wall clock: uses the test clock;
mainClock.advanceTimeUntil { … }uses wall clock. Mixing them in the same test produces flakes —rule.waitUntil(timeoutMillis) { … }will time out whilewaitUntilwaits for a clock tick that never comes. Skydoves hot take #4.advanceTimeUntil - State mutations off-thread: any from the test thread (not inside
state.value = X/runOnIdle) races with the recomposer. Skydoves hot take #5.runOnUiThread - v2 queued work: after migrating to ,
androidx.compose.ui.test.v2.*s are queued underLaunchedEffect. Tests that previously relied onStandardTestDispatchereager dispatch may need an explicitUnconfinedTestDispatcherormainClock.advanceTimeBy(0)to drain.runCurrent() - timeout: defaults to 1000 ms — is the test using a longer timeout to mask a missing
waitUntilor to hide a wrong-clock issue?IdlingResource
Failure modes route to:
- , missing
Thread.sleep,IdlingResourceconfusion, off-thread state mutation, customwaitUntilfor external work →IdlingResource.../../synchronization/synchronizing-with-idle/SKILL.md - Frame-rounding, granularity, v1/v2 dispatcher migration →
advanceTimeBy.../../synchronization/controlling-the-test-clock/SKILL.md - Animation flakes, missing,
autoAdvanceInfiniteAnimationPolicy→CancellationException.../../synchronization/testing-animations-deterministically/SKILL.md
这是最容易产生 flaky 的阶段。端到端检查每个测试方法:
- :除截图测试等待 RenderThread 完成 ripple 外,其他任何位置均禁止使用。Skydoves 强烈观点 #7。其他位置应改用
Thread.sleep(N)(测试时钟)或mainClock.advanceTimeBy(durationMs)(墙上时钟)。rule.waitUntil(timeoutMillis) { … } - 动画测试:任何触发动画的测试都必须在 之前设置
setContent。否则,已安装的mainClock.autoAdvance = false会在无限动画刚开始时通过InfiniteAnimationPolicy将其取消。Skydoves 强烈观点 #3。CancellationException - 测试时钟与墙上时钟:使用测试时钟;
mainClock.advanceTimeUntil { … }使用墙上时钟。在同一个测试中混用会造成 flaky——当rule.waitUntil(timeoutMillis) { … }等待一个永远不会到来的时钟 tick 时,advanceTimeUntil就会超时。Skydoves 强烈观点 #4。waitUntil - 跨线程状态变更:测试线程(而非 /
runOnIdle内部)中的任何runOnUiThread都会与 Recomposer 产生竞态。Skydoves 强烈观点 #5。state.value = X - v2 队列任务:迁移到 后,
androidx.compose.ui.test.v2.*会在LaunchedEffect下排队。此前依赖StandardTestDispatcher急切调度的测试,可能需要显式调用UnconfinedTestDispatcher或mainClock.advanceTimeBy(0)来清空队列。runCurrent() - 超时:默认值为 1000 ms——测试是否使用了更长的超时时间,以掩盖缺失的
waitUntil或错误的时钟问题?IdlingResource
失败模式路由到:
- 、缺失
Thread.sleep、IdlingResource混淆、跨线程状态变更、为外部工作创建自定义waitUntil→IdlingResource。../../synchronization/synchronizing-with-idle/SKILL.md - Frame 舍入、粒度、v1/v2 dispatcher 迁移 →
advanceTimeBy。../../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: when a finder misses, does the test print the semantics tree to make the failure actionable, or does it just throwprintToString?AssertionError: failed: assertExists - : 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.
fetchSemanticsNode - 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, overuse →
fetchSemanticsNode.../../debug/printing-the-semantics-tree/SKILL.md - Accessibility check coverage gap, Robolectric no-op surprise → .
../../debug/enabling-accessibility-checks/SKILL.md
检查测试失败时能够提供的信息:
- /
printToLog:Finder 未匹配到节点时,测试是否会打印 semantics tree,使失败信息具有可操作性?还是只抛出printToString?AssertionError: failed: assertExists - :是否存在直接调用?这是应急出口——偶尔使用没有问题,但大量使用表明测试绕过了公开的 matcher API。
fetchSemanticsNode - 失败信息:集合 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 produces several findings, prioritize:
*Test.kt- 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.
- Phase 5 idle issues before Phase 4 actions. A masking a missing
Thread.sleepmakes Phase 4 action issues invisible — once idle is correct, the action timing problems surface clearly.IdlingResource - Phase 2 finder issues before Phase 3 assertions. A finder that targets the wrong node makes every assertion downstream meaningless.
- Phase 6 debug output is always the last fix. It improves diagnosis but does not change correctness.
当同一个 产生多项发现时,按以下顺序确定优先级:
*Test.kt- 先处理阶段 1 的配置阻断问题。 测试位于错误的 source set 或混用了测试界面时,会产生未定义行为;在这些问题之上修复阶段 5 的空闲同步问题只会浪费精力。
- 阶段 5 的空闲同步问题优先于阶段 4 的操作问题。 可能掩盖缺失的
Thread.sleep,使阶段 4 的操作问题不可见;空闲同步恢复正确后,操作时序问题才会清晰地显现出来。IdlingResource - 阶段 2 的 Finder 问题优先于阶段 3 的断言问题。 如果 Finder 定位到了错误节点,那么后续所有断言都将失去意义。
- 阶段 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
undefinedPhase 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 ), STOP. Do not run Phases 2-6. The whole test will be rewritten when moved to — auditing the current incarnation wastes effort. Hand off to and rerun the audit after the move.
src/test/src/androidTest/../../setup/setting-up-host-vs-device-tests/SKILL.mdSimilarly, if Phase 1 finds a block sharing a class with a , halt and route to . The mixed environment makes every later finding ambiguous.
runComposeUiTest { }@get:Rule createComposeRule()../../setup/choosing-test-rule-vs-runtest/SKILL.md如果阶段 1 发现测试位于错误的 source set(例如在 中执行截图测试),立即停止。不要运行阶段 2 至阶段 6。移动到 后,整个测试都将重写——审查当前版本只会浪费精力。将任务转交给 ,并在移动后重新运行审计。
src/test/src/androidTest/../../setup/setting-up-host-vs-device-tests/SKILL.md同样,如果阶段 1 发现 代码块与包含 的类共存,应立即停止,并路由到 。混合环境会使后续所有发现都变得含义不明确。
runComposeUiTest { }@get:Rule createComposeRule()../../setup/choosing-test-rule-vs-runtest/SKILL.mdPattern: 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 outside of a screenshot/RenderThread context as ERROR. Skydoves hot take #7.
Thread.sleep - MUST flag every animation test without as ERROR. Skydoves hot take #3.
mainClock.autoAdvance = false - MUST flag every v1 entry point (,
androidx.compose.ui.test.junit4.createComposeRule) as WARN. Skydoves hot take #6.androidx.compose.ui.test.runComposeUiTest - MUST flag every usage as ERROR. The API is
performGesture { }; the SPEC forbids recommending it.@Deprecated - 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 场景之外的每个 标记为 ERROR。Skydoves 强烈观点 #7。
Thread.sleep - MUST 将每个未设置 的动画测试标记为 ERROR。Skydoves 强烈观点 #3。
mainClock.autoAdvance = false - MUST 将每个 v1 入口点(、
androidx.compose.ui.test.junit4.createComposeRule)标记为 WARN。Skydoves 强烈观点 #6。androidx.compose.ui.test.runComposeUiTest - MUST 将每次 使用标记为 ERROR。该 API 已弃用;SPEC 禁止推荐它。
performGesture { } - 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
参考资料
- Compose testing overview (Android Developers): https://developer.android.com/develop/ui/compose/testing
- Compose testing cheat sheet: https://developer.android.com/develop/ui/compose/testing-cheatsheet
- Compose testing setup: https://developer.android.com/develop/ui/compose/testing#setup
- Testing animations: https://developer.android.com/develop/ui/compose/animation/testing
- Semantics in Compose: https://developer.android.com/develop/ui/compose/accessibility/semantics
- Compose UI release notes: https://developer.android.com/jetpack/androidx/releases/compose-ui
- Sibling setup skills: ,
../../setup/configuring-test-dependencies/SKILL.md,../../setup/choosing-test-rule-vs-runtest/SKILL.md.../../setup/setting-up-host-vs-device-tests/SKILL.md - Sibling finder skills: ,
../../finders/finding-nodes-by-tag-text-content/SKILL.md,../../finders/composing-semantics-matchers/SKILL.md.../../finders/traversing-the-semantics-tree/SKILL.md - Sibling assertion skills: ,
../../assertions/asserting-node-state-and-text/SKILL.md.../../assertions/asserting-bounds-and-dimensions/SKILL.md - Sibling action skills: ,
../../actions/clicking-and-scrolling/SKILL.md,../../actions/injecting-touch-gestures/SKILL.md,../../actions/injecting-mouse-and-keyboard/SKILL.md.../../actions/entering-text/SKILL.md - Sibling synchronization skills: ,
../../synchronization/controlling-the-test-clock/SKILL.md,../../synchronization/testing-animations-deterministically/SKILL.md.../../synchronization/synchronizing-with-idle/SKILL.md - Sibling pattern skills: ,
../../patterns/structuring-a-compose-test/SKILL.md,../../patterns/testing-lazy-lists/SKILL.md.../../patterns/testing-state-restoration/SKILL.md - Sibling interop skill: .
../../interop/testing-with-espresso-interop/SKILL.md - Sibling debug skills: ,
../../debug/printing-the-semantics-tree/SKILL.md.../../debug/enabling-accessibility-checks/SKILL.md - skydoves — compose-performance-skills (sibling repo for production-side audits): https://github.com/skydoves/compose-performance-skills.
- Compose 测试概览(Android Developers):https://developer.android.com/develop/ui/compose/testing
- Compose 测试速查表:https://developer.android.com/develop/ui/compose/testing-cheatsheet
- Compose 测试配置:https://developer.android.com/develop/ui/compose/testing#setup
- 测试动画:https://developer.android.com/develop/ui/compose/animation/testing
- Compose 中的 Semantics:https://developer.android.com/develop/ui/compose/accessibility/semantics
- Compose UI 发行说明:https://developer.android.com/jetpack/androidx/releases/compose-ui
- 同级 setup skills:、
../../setup/configuring-test-dependencies/SKILL.md、../../setup/choosing-test-rule-vs-runtest/SKILL.md。../../setup/setting-up-host-vs-device-tests/SKILL.md - 同级 finder skills:、
../../finders/finding-nodes-by-tag-text-content/SKILL.md、../../finders/composing-semantics-matchers/SKILL.md。../../finders/traversing-the-semantics-tree/SKILL.md - 同级 assertion skills:、
../../assertions/asserting-node-state-and-text/SKILL.md。../../assertions/asserting-bounds-and-dimensions/SKILL.md - 同级 action skills:、
../../actions/clicking-and-scrolling/SKILL.md、../../actions/injecting-touch-gestures/SKILL.md、../../actions/injecting-mouse-and-keyboard/SKILL.md。../../actions/entering-text/SKILL.md - 同级 synchronization skills:、
../../synchronization/controlling-the-test-clock/SKILL.md、../../synchronization/testing-animations-deterministically/SKILL.md。../../synchronization/synchronizing-with-idle/SKILL.md - 同级 pattern skills:、
../../patterns/structuring-a-compose-test/SKILL.md、../../patterns/testing-lazy-lists/SKILL.md。../../patterns/testing-state-restoration/SKILL.md - 同级 interop skill:。
../../interop/testing-with-espresso-interop/SKILL.md - 同级 debug skills:、
../../debug/printing-the-semantics-tree/SKILL.md。../../debug/enabling-accessibility-checks/SKILL.md - skydoves——compose-performance-skills(用于审查生产代码的同级仓库):https://github.com/skydoves/compose-performance-skills。