Test Harness for Jetpack Compose

A library providing a test harness for UI components.

Background

Device configuration (locale, font size, screen size, folding features, etc.) are device-wide properties, which makes it hard to automate tests that wants to vary these properties. One current solution is to run tests across a range of emulators or devices with different properties, and potentially filter tests to only run when specific conditions are met. This has the downside of increasing the number of devices to manage, higher complexity of configuring those devices, and more complicated test suites.

With a Compose-only app, it is less common that the “physical” constraints of the device are directly used. Instead, state hoisting encourages isolating such constraints, and providing them to components via state that is observable via snapshots. The mechanism to do so is primarily via a set of composition locals, such as LocalConfiguration, LocalDensity, and others. The composition local mechanism provides a layer of indirection that permits overriding these constraints via those composition local hooks.

Test Harness

TestHarness is an @Composable function, which takes a single slot of @Composable content. This content is the @Composable UI under test, so standard usage would look like the following:

@Test
fun example() {
    composeTestRule.setContent {
        TestHarness(/* ... */) {
            MyComponent()
        }
    }

    // assertions
}

When no parameters of TestHarness are specified, TestHarness has no direct effect, and it would be equivalent to calling MyComponent directly.

Specifying parameters of TestHarness results in overriding the default configuration for the content under-test, and will affect MyComponent.

For example, specifying the fontScale parameter will change the effective font scale within the TestHarness:

@Test
fun example() {
    composeTestRule.setContent {
        TestHarness(fontScale = 1.5f) {
            Text("Configuration: ${LocalConfiguration.current.fontScale}")
            Text("Density: ${LocalDensity.current.fontScale}")
        }
    }

    composeTestRule.onNodeWithText("Configuration: 1.5").assertExists()
    composeTestRule.onNodeWithText("Density: 1.5").assertExists()
}

This allows testing UI for different font scales in a isolated way, without having to directly configure the device to use a different font scale.

TestHarness also takes a size: DpSize parameter, to test a Composable at a particular size.

@Test
fun example() {
    composeTestRule.setContent {
        TestHarness(size = DpSize(800.dp, 1000.dp)) {
            MyComponent() // will be rendered at 800dp by 1000dp, even if the window is smaller
        }
    }
}

See the full list of parameters and effects below.

Parameters

The full list of parameters and their effects:

Parameter	Default value	Effect
size: DpSize	DpSize.Unspecified	If specified, overrides LocalDensity if needed to give the DpSize amount of space to the composable under test
darkMode: Boolean	isSystemInDarkTheme()	Overrides LocalConfiguration.current.uiMode
fontScale: Float	LocalDensity.current.fontScale	Overrides LocalDensity.current.fontScale and LocalConfiguration.current.fontScale
fontWeightAdjustment: Int?	LocalConfiguration.current.fontWeightAdjustment on API 31 and above, otherwise null	Overrides LocalConfiguration.current.fontWeightAdjustment on API 31 and above and not-null
locales: LocaleListCompat	ConfigurationCompat.getLocales(LocalConfiguration.current)	Overrides LocalConfiguration.current.locales
layoutDirection: LayoutDirection?	null (which uses the resulting locale layout direction)	Overrides LocalLayoutDirection.current and LocalConfiguration.current.screenLayout

Implementation

TestHarness works by overriding a set of composition locals provided to the content under test.

The full list of composition locals that may be overridden by various parameters are:

• LocalConfiguration
• LocalContext
• LocalLayoutDirection
• LocalDensity
• LocalFontFamilyResolver

Any composable that depends on these composition locals should be testable via the test harness, because they will pull the overridden configuration information from them. This includes configuration-specific resources, because these are pulled from LocalContext.

Testing a composable at a smaller size than the real screen space available is straightforward, but testing a composable at a larger size than the real screen space available is not. This is because the library and the testing APIs are sensitive to whether or not a composable is actually rendered within the window of the application.

As a solution, TestHarness will override the LocalDensity to shrink the content as necessary for all of the specified size: DpSize to be displayed at once in the window space that is available. This results in the composable under test believing it has the specified space to work with, even if that is larger than the window of the application.

Limitations

The test harness is simulating alternate configurations and sizes, so it does not exactly represent what a user would see on a real device. For that reason, the platform edges where Composables interact with the system more is where the test harness may break down and have issues. An incomplete list includes: dialogs (due to different Window instances), insets, soft keyboard interactions, and interop with Views. The density overriding when specifying a specific size to test a composable at also means that UI might be rendered in atypical ways, especially at the extreme of rendering a very large desktop-size UI on a small portrait phone. The mechanism that the test harness uses is also not suitable for production code: in production, the default configuration as specified by the user and the system should be used.

The mechanism that the test harness uses to override the configuration (ContextThemeWrapper) is not fully supported by layoutlib. In particular, alternate resources are available just by using TestHarness.

Download

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.google.accompanist:accompanist-testharness:<version>"
}