Asserting Bounds And Dimensions

Asserting Bounds and Dimensions — Layout Math in Dp, Not Pixels

Layout assertions belong in dp, run with a half-dp tolerance, and most of the interesting checks (padding, gap, alignment) are subtractions between two getUnclippedBoundsInRoot() rectangles. This skill picks the right size/position assertion, explains clipped vs unclipped, and shows the canonical "compute padding from two rects" pattern lifted directly from material3/ButtonTest.kt.

When to use this skill

• The developer wants to verify a Button is 48 dp tall, a Spacer is 16 dp wide, an Icon is at position (24.dp, 12.dp).
• The developer asks how to assert the padding between two composables.
• The developer asks about minimum touch target sizes (ChipDefaults.MinHeight + 1.dp).
• The developer is comparing layout values in pixels and wants the dp-typed equivalent.
• The developer mentions assertWidthIsEqualTo, getUnclippedBoundsInRoot, DpRect, getAlignmentLinePosition, getFirstLinkBounds.

When NOT to use this skill

• The check is about state (enabled, on, selected) — see ./asserting-node-state-and-text/SKILL.md.
• The check is "is the node on screen at all" — assertIsDisplayed() is enough; bounds math adds friction without value.
• The composable's bounds depend on an animation in flight — pause the clock first; see ../../synchronization/testing-animations-deterministically/SKILL.md.
• The bounds are relative to a screenshot — use a screenshot test instead.

Prerequisites

• A working ComposeTestRule / ComposeUiTest. See ../../setup/configuring-test-dependencies/SKILL.md.
• The target composable has finished measuring and placing. If it animates in, advance the test clock first — see ../../synchronization/controlling-the-test-clock/SKILL.md.
• For touch-target assertions, the target node has a click action so touchBoundsInRoot is meaningful.

Workflow

• 1. Pick the assertion by question type. All APIs live in commonMain/.../BoundsAssertions.kt.

  Question	API	File:line
  Is the layout exactly W dp wide?	assertWidthIsEqualTo(expectedWidth: Dp)	BoundsAssertions.kt:44-46
  Is the layout exactly H dp tall?	assertHeightIsEqualTo(expectedHeight: Dp)	BoundsAssertions.kt:53-55
  At least W wide?	assertWidthIsAtLeast(expectedMinWidth: Dp)	BoundsAssertions.kt:85-87
  At least H tall?	assertHeightIsAtLeast(expectedMinHeight: Dp)	BoundsAssertions.kt:95-99
  Touch-target width?	assertTouchWidthIsEqualTo(expectedWidth: Dp)	BoundsAssertions.kt:62-66
  Touch-target height?	assertTouchHeightIsEqualTo(expectedHeight: Dp)	BoundsAssertions.kt:73-77
  Exact position in root?	assertPositionInRootIsEqualTo(left: Dp, top: Dp)	BoundsAssertions.kt:109-117
  Top position only?	assertTopPositionInRootIsEqualTo(top: Dp)	BoundsAssertions.kt:126-130
  Left position only?	assertLeftPositionInRootIsEqualTo(left: Dp)	BoundsAssertions.kt:139-143
  Read full unclipped bounds	getUnclippedBoundsInRoot(): DpRect	BoundsAssertions.kt:148-152
  Read clipped bounds	getBoundsInRoot(): DpRect	BoundsAssertions.kt:158-165
  Alignment line in dp	getAlignmentLinePosition(line: AlignmentLine): Dp	BoundsAssertions.kt:171-180
  Bounds of a LinkAnnotation in a Text	getFirstLinkBounds(predicate)	BoundsAssertions.kt:196-248
  Compare any two Dp values	Dp.assertIsEqualTo(expected, subject, tolerance = Dp(.5f))	BoundsAssertions.kt:319-324

• 2. Use unclipped bounds for layout math; clipped bounds for "what the user sees". getUnclippedBoundsInRoot() returns the laid-out rectangle ignoring viewport clipping (BoundsAssertions.kt:148-152 → unclippedBoundsInRoot private, BoundsAssertions.kt:284-291). getBoundsInRoot() clips to the viewport (BoundsAssertions.kt:158-165). Padding/spacing math uses unclipped; partial-visibility checks use clipped.

• 3. Tolerance is half a dp by default. Dp.assertIsEqualTo(expected, subject, tolerance = Dp(.5f)) (BoundsAssertions.kt:319) accepts deviations up to 0.5 dp because layout rounding introduces sub-dp drift. Override only when stricter precision is justified by an explicit measurement contract.

• 4. Compute padding by subtracting two unclipped rects, then call Dp.assertIsEqualTo. This is the canonical material3 pattern (material3/.../ButtonTest.kt:213-225):

  val buttonBounds = rule.onNodeWithTag(ButtonTestTag).getUnclippedBoundsInRoot()
  val textBounds   = rule.onNodeWithTag(TextTestTag).getUnclippedBoundsInRoot()
  
  (textBounds.left - buttonBounds.left).assertIsEqualTo(
      24.dp,
      "padding between the start of the button and the start of the text.",
  )
  
  (buttonBounds.right - textBounds.right).assertIsEqualTo(
      24.dp,
      "padding between the end of the text and the end of the button.",
  )
  buttonBounds.height.assertIsEqualTo(ButtonDefaults.MinHeight, "height of button.")

  The subject string lands in the failure message: "Actual padding between the start of the button and the start of the text. is 22.dp, expected 24.dp (tolerance: .5.dp)".

• 5. For minimum-size contracts, use assertHeightIsAtLeast / assertWidthIsAtLeast. Useful when a composable should never be smaller than a constant, even at large font scale. Example from material/ChipTest.kt:226-233:

  rule.setMaterialContent { Chip(onClick = {}) { Text(text = "Test chip", fontSize = 50.sp) } }
  rule.onNode(hasClickAction()).assertHeightIsAtLeast(ChipDefaults.MinHeight + 1.dp)

• 6. Use touch bounds when verifying tap-target accessibility. assertTouchWidthIsEqualTo / assertTouchHeightIsEqualTo reads node.touchBoundsInRoot (BoundsAssertions.kt:270-282), which can extend past the visual bounds when the composable applies Modifier.minimumInteractiveComponentSize() or similar. Visual bounds use getUnclippedBoundsInRoot; touch bounds answer "where will a click land".