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 improper due to a cutout:

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

For this reason it is very important take a look at how your UI reacts to several types of cutouts by means of your Compose Preview.

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

In case you are doing this by means of code, be aware that you’ll first need to specify a tool spec both by means of a particular machine or a particular width and top in pixels.

@Preview(showSystemUi = true, machine = "spec:mother or father=pixel_8")

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

Then, throughout the machine spec, you may also add cutout and set it equal to the kind of cutout you need to take a look at.

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

Navigation bar

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

Gesture navigation:

• Clear by default
• Backside offset is disabled, however you’ll be able to apply insets
• setNavigationBarColor is disabled

Three button navigation:

• Opacity set to 80% by default
• Backside offset is disabled however you’ll be able to 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 kinds of navigation bars in your Preview, you’ll be able to specify navigation utilizing the Preview picker or by means of the machine parameter.

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

In case you are utilizing code to check the navigation bars, you’ll need to specify a mother or father machine.

@Preview(showSystemUi = true, machine = "spec:mother or father=pixel_8")

Then, you’ll be able to add navigation and set it to buttons for 3 button navigation or gesture for gesture navigation.

@Preview(showSystemUi = true, machine = 
"spec:mother or father=pixel_8,navigation=buttons")

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

After getting manually examined that your display handles edge-to-edge as anticipated, you need to think about including automated checks to catch future regressions.

We suggest utilizing screenshot checks to confirm your edge-to-edge implementation, as they confirm the location and dimension of your insets and the content material that could be drawn behind.

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

To modify between navigation modes, you need to 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 incorporates a clock and icons that change each minute, breaking screenshot checks. You may allow demo mode through adb instructions to indicate the identical system bar content material each time:

Observe that adb instructions will not be synchronized, so that you may have to implement a mechanism to attend or retry till every take a look at passes. Alternatively, when you 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 enables for specifying an arbitrary WindowInsetsCompat to use to the composable underneath 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 underneath take a look at
DebugVisibleWindowInsets(Modifier.fillMaxSize()) // Debug overlay (non-obligatory)
}
}
}

This will then be mixed with a debug overlay for exhibiting 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 beneath:

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

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

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

1. Distribute APKs which are 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 Possibility on an Android 15 machine 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 machine.

Apps focusing on API35 shall be edge-to-edge by default so as to give your customers a extra satisfying and top 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 remember to go away us any suggestions utilizing these directions.