Preview and take a look at your app’s edge-to-edge UI | by Meghan Mehta | Android Builders | Sep, 2024

Right here’s how the UI of an app utilizing edge-to-edge can go mistaken due to a cutout:

Amongst different points, this app’s cutout overlaps the record content material.

That is why you will need to take a look at how your UI reacts to various kinds of cutouts by way of your Compose Preview.

Within the Preview picker, below the {Hardware} part, discover the Cutout dropdown and specify the cutout you wish to take a look at.

If you’re doing this by way of code, word that you’ll first must specify a tool spec both by way of a selected gadget or a selected width and top in pixels.

@Preview(showSystemUi = true, gadget = "spec:dad or mum=pixel_8")

@Preview(showSystemUi = true, gadget = "spec:width=1080px,top=2340px")

Then, inside the gadget spec, you too can add cutout and set it equal to the kind of cutout you need to take a look at.

@Preview(showSystemUi = true, gadget = 
“spec:width=1080px,top=2400px,cutout=punch_hole”)

Navigation bar

For edge-to-edge, there are completely different UI requirements for gesture navigation vs three button navigation.

Gesture navigation:

• Clear by default
• Backside offset is disabled, however you may apply insets
• setNavigationBarColor is disabled

Three button navigation:

• Opacity set to 80% by default
• Backside offset is disabled however you may apply insets
• Colour is the window background by default

The navigation bar in showSystemUi will present you the gesture navigation bar by default, however to check each forms of navigation bars in your Preview, you may specify navigation utilizing the Preview picker or by way of the gadget parameter.

To specify by way of the Preview picker, within the {Hardware} part, discover the Navigation dropdown and set your Preview’s navigation bar.

If you’re utilizing code to check the navigation bars, you will have to specify a dad or mum gadget.

@Preview(showSystemUi = true, gadget = "spec:dad or mum=pixel_8")

Then, you may add navigation and set it to buttons for 3 button navigation or gesture for gesture navigation.

@Preview(showSystemUi = true, gadget = 
"spec:dad or mum=pixel_8,navigation=buttons")

Now that you understand how to check your app’s UI edge-to-edge implementation by way of Compose Preview, let’s go over automated testing.

After getting manually examined that your display handles edge-to-edge as anticipated, it is best to contemplate including automated assessments to catch future regressions.

We suggest utilizing screenshot assessments to confirm your edge-to-edge implementation, as they confirm the position and dimension of your insets and the content material that is likely to be drawn behind.

You need to use instrumented assessments for the very best constancy on emulators or bodily units. A single foldable emulator can cowl most circumstances, and you should use Espresso Gadget to set the completely different display orientations and foldable state:

To change between navigation modes, you should use UI Automator to move adb instructions:

UiDevice.getInstance(InstrumentationRegistry.getInstrumentation()).apply {
executeShellCommand(
"cmd overlay enable-exclusive " +
"com.android.inner.systemui.navbar.gestural", // or .threebutton
)
}

The system bar accommodates a clock and icons that change each minute, breaking screenshot assessments. You may allow demo mode by way of adb instructions to indicate the identical system bar content material each time:

Notice that adb instructions will not be synchronized, so that you would possibly have to implement a mechanism to attend or retry till every take a look at passes. Alternatively, if you happen to use Compose, there’s a new wrapper that may assist you to catch most regressions:

Compose 1.8.0-alpha01 ui-test features a new DeviceConfigurationOverride for testing window insets, known as DeviceConfigurationOverride.WindowInsets.

This permits for specifying an arbitrary WindowInsetsCompat to use to the composable below take a look at:

composeTestRule.setContent {
DeviceConfigurationOverride(
DeviceConfigurationOverride.WindowInsets(
WindowInsetsCompat.Builder()
.setInsets(
WindowInsetsCompat.Kind.statusBars(),
DpRect(
left = 0.dp,
high = 64.dp,
proper = 0.dp,
backside = 0.dp,
).toAndroidXInsets(),
)
.setInsets(
WindowInsetsCompat.Kind.navigationBars(),
DpRect(
left = 64.dp,
high = 0.dp,
proper = 64.dp,
backside = 64.dp,
).toInsets(),
)
.construct(),
),
)
) {
Field {
content material() // Your content material below take a look at
DebugVisibleWindowInsets(Modifier.fillMaxSize()) // Debug overlay (non-obligatory)
}
}
}

This may then be mixed with a debug overlay for displaying the place the insets are:

@Composable
enjoyable DebugVisibleWindowInsets(
modifier: Modifier = Modifier,
debugColor: Colour = Colour.Magenta.copy(alpha = 0.5f),
) {
Field(modifier = modifier.fillMaxSize()) {
Spacer(
modifier = Modifier
.align(Alignment.CenterStart)
.fillMaxHeight()
.windowInsetsStartWidth(WindowInsets.safeDrawing)
.windowInsetsPadding(WindowInsets.safeDrawing.solely(WindowInsetsSides.Vertical))
.background(debugColor),
)
Spacer(
modifier = Modifier
.align(Alignment.CenterEnd)
.fillMaxHeight()
.windowInsetsEndWidth(WindowInsets.safeDrawing)
.windowInsetsPadding(WindowInsets.safeDrawing.solely(WindowInsetsSides.Vertical))
.background(debugColor),
)
Spacer(
modifier = Modifier
.align(Alignment.TopCenter)
.fillMaxWidth()
.windowInsetsTopHeight(WindowInsets.safeDrawing)
.background(debugColor),
)
Spacer(
modifier = Modifier
.align(Alignment.BottomCenter)
.fillMaxWidth()
.windowInsetsBottomHeight(WindowInsets.safeDrawing)
.background(debugColor),
)
}
}

Placing each collectively, a screenshot take a look at can visually present the place the insets are, and reveal if there may be content material that might be obscured by the insets, just like the snackbar is under:

For an instance of this in motion, take a look at this Now in Android PR, which provides screenshot assessments with making use of insets: https://github.com/android/nowinandroid/pull/1498/

Your app would possibly determine to create a QA crew to check each display, or at the very least your most essential screens.

There are three approaches to help your QA crew in seeing the impacts of the edge-to-edge enforcement:

1. Distribute APKs which can be focusing on SDK 35 on Android 15 units or emulators.
2. OR, allow the ENFORCE_EDGE_TO_EDGE flag within the App Compatibility Change Developer Choice on an Android 15 gadget with out having to focus on SDK 35.
3. OR, name enableEdgeToEdge on every Exercise to simulate the Android 15 platform enforcement with out having to focus on SDK 35 and with no need an Android 15 gadget.

Apps focusing on API35 can be edge-to-edge by default with the intention to give your customers a extra satisfying and prime quality expertise. You may take a look at your UI, together with cutouts and navigation bars, utilizing Compose Preview within the Canary model of Android Studio Ladybug, and in automating testing with the brand new DeviceConfigurationOverride. Please make sure to go away us any suggestions utilizing these directions.