Radiography

Text-ray goggles for your Android UI.

DecorView { 1080×2160px }
├─LinearLayout { id:main, 1080×1962px }
│ ├─EditText { id:username, 580×124px, focused, text-length:0, ime-target }
│ ├─EditText { id:password, 580×124px, text-length:0 }
│ ╰─LinearLayout { 635×154px }
│   ├─Button { id:signin, 205×132px, text-length:7 }
│   ╰─Button { id:forgot_password, 430×132px, text-length:15 }
├─View { id:navigationBarBackground, 1080×132px }
╰─View { id:statusBarBackground, 1080×66px }

Usage
Result example
Jetpack Compose support
FAQ
License

Usage

Add the radiography dependency to your app's build.gradle file:

dependencies {
  implementation 'com.squareup.radiography:radiography:2.6'
}

Radiography.scan() returns a pretty string rendering of the view hierarchy of all windows managed by the current process.

// Render the view hierarchy for all windows.
val prettyHierarchy = Radiography.scan()

// Include the text content from TextView instances.
val prettyHierarchy = Radiography.scan(viewStateRenderers = DefaultsIncludingPii)

// Append custom attribute rendering
val prettyHierarchy = Radiography.scan(viewStateRenderers = DefaultsNoPii +
    androidViewStateRendererFor<LinearLayout> {
      append(if (it.orientation == LinearLayout.HORIZONTAL) "horizontal" else "vertical")
    })

You can print a subset of the view hierarchies by specifying a ScanScope. By default, Radiography will scan all the windows owned by your app.

// Extension function on View, renders starting from that view.
val prettyHierarchy = someView.scan()

// Render only the view hierarchy from the focused window, if any.
val prettyHierarchy = Radiography.scan(scanScope = FocusedWindowScope)

// Filter out views with specific ids.
val prettyHierarchy = Radiography.scan(viewFilter = skipIdsViewFilter(R.id.debug_drawer))

// Combine view filters.
val prettyHierarchy = Radiography.scan(
  viewFilter = skipIdsViewFilter(R.id.debug_drawer) and MyCustomViewFilter()
)

Result example

com.squareup.radiography.sample/com.squareup.radiography.sample.MainActivity:
window-focus:false
 DecorView { 1080×2160px }
 ├─LinearLayout { 1080×2028px }
 │ ├─ViewStub { id:action_mode_bar_stub, GONE, 0×0px }
 │ ╰─FrameLayout { id:content, 1080×1962px }
 │   ╰─LinearLayout { id:main, 1080×1962px }
 │     ├─ImageView { id:logo, 1080×352px }
 │     ├─EditText { id:username, 580×124px, text-length:0 }
 │     ├─EditText { id:password, 580×124px, text-length:0 }
 │     ├─CheckBox { id:remember_me, 343×88px, text-length:11 }
 │     ├─LinearLayout { 635×154px }
 │     │ ├─Button { id:signin, 205×132px, text-length:7 }
 │     │ ╰─Button { id:forgot_password, 430×132px, text-length:15 }
 │     ├─View { 1080×812px }
 │     ╰─Button { id:show_dialog, 601×132px, text-length:23 }
 ├─View { id:navigationBarBackground, 1080×132px }
 ╰─View { id:statusBarBackground, 1080×66px }

This sample app lives in this repo in the sample directory.

Custom Hierarchy Exploration

The Radiography.scan function provides a String representation of the view hierarchy, but you can also work with the raw hierarchy data directly if you want to programmatically explore it and integrate it into your own custom tools.

Use the ScanScopes object to identify the root of a hierarchy you want to explore. You can use the resulting ScannableView objects, and their ScannableView.children, to explore the hierarchy.

For example, to get the hierarchy starting with a specific Compose test tag in a given activity, you can do this:

@OptIn(ExperimentalRadiographyComposeApi::class)
fun Activity.findComposableRootWithTestTag(tag: String): ScannableView.ComposeView {
   val rootView = window.decorView.findViewById<ViewGroup>(R.id.content)

   return ScanScopes.composeTestTagScope(
      testTag = tag,
      inScope = ScanScopes.singleViewScope(rootView)
   ).findRoots()
      .firstOrNull()
      as? ScannableView.ComposeView
      ?: error("No composable found with test tag $tag")
}

The information provided by the ScannableView.ComposeView can be powerful. In particular, the semantic information can be used to validate certain expectations and programmatically test your application. For example:

val myComposableScreen = findComposableRootWithTestTag("My screen tag")

myComposableScreen.allDescendentsDepthFirst
  .filterIsInstance<ScannableView.ComposeView>()
  .onEach { composeView ->
    
    // Validate that all images have a content description set
    if (composeView.displayName == "Image") {
      check(composeView.semanticsConfigurations.any { it.contains(SemanticsProperties.ContentDescription) })
    }
    
    // Perform a click on all clickable elements to ensure none of them cause a crash
    composeView.semanticsConfigurations
      .map { it[SemanticsActions.OnClick] }
      .onEach { clickAction -> clickAction.action?.invoke() }
}

val ScannableView.allDescendentsDepthFirst: Sequence<ScannableView>
    get() = children.flatMap { sequenceOf(it) + it.allDescendentsDepthFirst }

Jetpack Compose support

Jetpack Compose is Google's new declarative UI toolkit. It is a completely new implementation, and does not use Android views itself (although it interoperates with them seamlessly).

Radiography will automatically render composables found in your view tree if the Compose Tooling library is on the classpath. If you are using Compose, you're probably already using this library (the @Preview annotation lives in the Tooling library). On the other hand, if you're not using Compose, Radiography won't bloat your app with transitive dependencies on any Compose artifacts.

Compose occasionally has internal implementation changes that affect Radiography. If you are using Radiography with an unsupported version of Compose, or you don't depend on the Tooling library, then Radiography will still try to detect compositions, but instead of rendering the actual hierarchy, it will just include a message asking you to upgrade Radiography or add the Tooling library.

Compose usage

The only thing required for Radiography to render composables is to include the tooling library as a dependency:

dependencies {
  implementation("androidx.compose.ui:ui-tooling:1.0.0-betaXY")
}

When the tooling library is present, Radiography will automatically render composables. However, Radiography's Compose support is experimental. To use any of the compose-specific APIs, you will need to opt-in using the @OptIn(ExperimentalRadiographyComposeApi::class) annotation.

Rendering composables

The DefaultsNoPii and DefaultsIncludingPii renderers include default Compose renderers – you don't need to do anything special. Additional Compose-specific renderers can be found in the ComposableRenderers object.

To create a custom renderer for Compose, implement a ViewStateRenderer to handle values of type ComposeView. However, since Radiography gets most of its information about composables from their semantics properties, in most cases you shouldn't need to define any custom rendering logic. ComposeView has a list of all the Modifiers that have been applied to the composable, including its semantics.

// Custom modifier that tells its parent if it's a favorite child or not.
data class IsFavoriteChildModifier(val isFavorite: Boolean) : ParentDataModifier {
  override fun Density.modifyParentData(parentData: Any?): Any? = this@IsFavoriteChildModifier
}

// Renderer for the above modifier.
@OptIn(ExperimentalRadiographyComposeApi::class)
val IsFavoriteChildRenderer = ViewStateRenderer { view ->
  val modifier = (view as? ComposeView)
      ?.modifiers
      ?.filterIsInstance<IsFavoriteChildModifier>()
      ?.singleOrNull()
      ?: return@ViewStateRenderer
  append(if (modifier.isFavorite) "FAVORITE" else "NOT FAVORITE")
}

Selecting which composables to render

Radiography lets you start scanning from a particular view by using the singleViewScope ScanScope or the View.scan() extension function. Compose doesn't have the concept a "view" as something that can be stored in a variable and passed around, but you can explicitly tag composables with strings using the testTag modifier, and then tell Radiography to only scan certain tags by passing a composeTestTagScope.

For example, say you have an app with some navigation controls at the top and bottom of the screen, but you only want to scan the main body of the screen in between them:

@Composable fun App() {
  Column {
    ActionBar()
    Body(Modifier.testTag("app-body"))
    BottomBar()
  }
}

To start scanning from Body:

@OptIn(ExperimentalRadiographyComposeApi::class)
val prettyHierarchy = Radiography.scan(scanScope = composeTestTagScope("app-body"))

You can also filter composables out using test tags. For example, say you have a screen that has a debug drawer:

@Composable fun App() {
  ModalDrawerLayout(drawerContent = {
    DebugDrawer(Modifier.testTag("debug-drawer"))
  }) {
    Scaffold(…) {
      …
    }
  }
}

To exclude the debug drawer and its children from the output, use skipComposeTestTagsFilter:

@OptIn(ExperimentalRadiographyComposeApi::class)
val prettyHierarchy = Radiography.scan(viewFilter = skipComposeTestTagsFilter("debug-drawer"))

To write a custom filter for Compose, implement a ViewFilter to handle values of type ComposeView. For example, a filter that excludes composables with a particular Modifier.layoutId might look something like this:

fun skipLayoutIdsFilter(skipLayoutId: (Any) -> Boolean) = ViewFilter { view ->
  (view as? ComposeView)
      ?.modifiers
      ?.asSequence()
      ?.filterIsInstance<LayoutIdParentData>()
      ?.none { layoutId -> skipLayoutId(layoutId.id) }
      // Include all views and composables that don't have any layoutId.
      ?: true
}

Subcomposition scanning

In Compose, the term "composition" is often used to refer to a single tree of composables that all share some core state (e.g. ambients) and use the same underlying slot table. A subcomposition is a distinct composition that has a reference to a particular point in another composition (its parent). Subcompositions share the parent's ambients, but can be created at any time and disposed independently of the parent composition.

Subcomposition is used for a number of things:

Compose children which have a data dependency on a property of the parent composition that is only available after the composition pass, e.g. WithConstraints (which can only compose its children during layout).
Lazy composition, where the "current" actual children of a composable depend on some runtime state, and old/uncreated children should be not be composed when not needed, to save resources. LazyColumn does this.
Linking compositions that need to be hosted in entirely separate windows together. Dialog uses this to make the dialog children act as children of the composable that invokes them, even though they're hosted in a separate window, with a Android view host.

Rendering subcomposition is tricky, because there's no explicit reference from the parent CompositionReference to where the subcompositions' composables actually appear. Fortunately, SubcomposeLayout is a helper composable which provides a convenient wrapper around subcomposition for common use cases such as 1 and 2 above – basically any time the subcomposition is actually a visual child of the parent composable, but can only be created during the layout pass. SubcomposeLayout shows up as a pattern in the slot tables' groups which Radiography detects and renders in a way that makes the subcomposition look like regular children of the parent composable.

Non-SubcomposeLayout subcompositions, like the one from Dialog, are rendered a bit more awkwardly. The subcomposition is shown as a child of the parent layout node. In the case of Dialog, this is fine, since there's no actual layout node in the parent composition which acts as a parent for the subcomposition. More complex use cases may be rendered differently, e.g. if there's a layout node which "hosts" the subcomposition, it will appear after the actual CompositionReference in the slot table, and thus the subcomposition and its subtree will appear before the layout node in the rendering.

Subcompositions have their own slot table that is not shared with their parent. For this reason, Radiography needs to do some extra work to scan subcompositions, since they won't be processed simply by reading the parent's slot table. Subcompositions are detected by looking for instances of CompositionReference in the parent slot table. CompositionReference is an abstract class, but the only concrete implementation currently in Compose contains references to all actual compositions that use it as a parent. Reflection is used to pull the actual subcompositions out of the parent reference, and then those compositions' slot tables are analyzed in turn, and its root composables are rendered as childrens of the node that owns the CompositionReference.

Call group collapsing

To simplify the hierarchy output of the Compose tree, only nodes that are "emitted" to the layout are included. This means that intermediate "call" nodes are collapsed together with the emitted node that they wrap. Each emitted node inherits the display name of the top level call node wrapping it.

For example, with this Compose code:

@Composable
fun Call3() {
  BasicText(text = "hello")
}

@Composable
fun Call2() {
  Call3()
}

@Composable
fun Call1() {
  Call2()
}

Column {
  Call1()
}

The hierarchy output will simply look like this: Column -> Call1.

The BasicText composable and its text are represented by the name Call1, because that is the composable function that wraps it. The Call3 and Call2 nodes are not shown because they don't emit a layout, and they are wrapped by Call1.

This approach helps to manage the many levels of nesting that can occur in a Compose tree. However, sometimes you may want to see the granular view of all the calls in the tree. To do this, you can use the ComposeView.callChain property to see the full call chain that led to the emitted node. In this case, the values of the property would look like this:

"Call1", "Call2", "Call3", "BasicText", "Layout", "ReusableComposeNode"

You can access this property if you implement a custom ViewStateRenderer or use Custom Hierarchy Exploration.

For more details on how Radiography works with Compose, see [How are compositions rendered?](#How are compositions rendered?)

Compose example output

com.squareup.radiography.sample.compose/com.squareup.radiography.sample.compose.MainActivity:
window-focus:false
 DecorView { 1080×2160px }
 ├─LinearLayout { 1080×2028px }
 │ ├─ViewStub { id:action_mode_bar_stub, GONE, 0×0px }
 │ ╰─FrameLayout { 1080×1962px }
 │   ╰─FitWindowsLinearLayout { id:action_bar_root, 1080×1962px }
 │     ├─ViewStubCompat { id:action_mode_bar_stub, GONE, 0×0px }
 │     ╰─ContentFrameLayout { id:content, 1080×1962px }
 │       ╰─AndroidComposeView { 1080×1962px, focused }
 │         ╰─Providers { 1080×1962px }
 │           ╰─ComposeSampleApp { 992×1874px }
 │             ├─Image { 240×352px }
 │             ├─TextField { 770×154px, test-tag:"text-field" }
 │             │ ├─Box { 200×59px, layout-id:"Label" }
 │             │ │ ╰─ProvideTextStyle { 200×59px, text-length:8 }
 │             │ ╰─ProvideTextStyle { 682×59px, layout-id:"TextField" }
 │             │   ╰─BaseTextField { 682×59px, text-length:0 }
 │             │     ╰─Layout { 682×59px }
 │             ├─TextField { 770×154px }
 │             │ ├─Box { 196×59px, layout-id:"Label" }
 │             │ │ ╰─ProvideTextStyle { 196×59px, text-length:8 }
 │             │ ╰─ProvideTextStyle { 682×59px, layout-id:"TextField" }
 │             │   ╰─BaseTextField { 682×59px, text-length:0 }
 │             │     ╰─Layout { 682×59px }
 │             ├─Row { 387×67px }
 │             │ ├─Checkbox { 55×55px, value:"Unchecked" }
 │             │ ├─Spacer { 22×0px }
 │             │ ╰─Text { 298×59px, text-length:11 }
 │             ├─Row { 685×99px }
 │             │ ├─TextButton { 199×99px }
 │             │ │ ╰─Providers { 155×55px }
 │             │ │   ╰─Text { 155×52px, text-length:7 }
 │             │ ╰─TextButton { 442×99px }
 │             │   ╰─Providers { 398×55px }
 │             │     ╰─Text { 398×52px, text-length:15 }
 │             ├─AndroidView {  }
 │             │ ╰─ViewBlockHolder { 919×53px }
 │             │   ╰─TextView { 919×53px, text-length:53 }
 │             ├─ScrollableRow { 1324×588px }
 │             │ ╰─ScrollableColumn { 1324×1026px }
 │             │   ╰─Text { 1324×1026px, test-tag:"live-hierarchy", text-length:2525 }
 │             ╰─TextButton { 737×99px }
 │               ╰─Providers { 693×55px }
 │                 ╰─Text { 693×52px, text-length:28 }
 ├─View { id:navigationBarBackground, 1080×132px }
 ╰─View { id:statusBarBackground, 1080×66px }

This sample can be found in the sample-compose directory.

FAQ

What is Radiography useful for?

Radiography is useful whenever you want to look at the view hierarchy and don't have the ability to connect the hierarchy viewer tool. You can add the view hierarchy string as metadata to crash reports, add a debug drawer button that will print it to Logcat, and use it to improve Espresso errors (here's an example).

Is Radiography production ready?

The code that retrieves the root views is based on Espresso's RootsOracle so it's unlikely to break in newer Android versions. We've been using Radiography for crash reports in production since 2015 without any issue.

Why use custom attribute string rendering instead of View.toString() ?

The output of View.toString() is useful but harder to read:

// View.toString():
Button { VFED..C.. ........ 0,135-652,261 #7f010001 app:id/show_dialog }
// Radiography:
Button { id:show_dialog, 652x126px, text-length:28 }

If you'd rather rely on View.toString(), you can provide a custom state renderer.

val prettyHierarchy = Radiography.scan(viewStateRenderers = listOf(androidViewStateRendererFor<View> {
  append(
      it.toString()
          .substringAfter(' ')
          .substringBeforeLast('}')
  )
}))

How are compositions rendered?

Disclaimer: Compose is changing frequently, so many of these details may change without warning, and none of this is required to use Radiography!

The API for configuring how composables are rendered is slightly different than for regular views, since composables simply are not Views. What might define a UI "component" or "widget" logically isn't made up of any single, nicely-encapsulated object. It is likely a few layers of convenience @Composable functions, with some Modifiers applied at various levels, and state is stored in the slot table via remember{}, not in instance fields.

Radiography uses the Compose Tooling library to parse a composition's slot table into a tree of objects which represent "groups" – each group can represent some data stored in the slot table, a function call, or an emitted layout node or Android view. Groups may include source locations in certain cases, and contain information about modifiers and function parameters. This is a really powerful API, but there's a lot of data there, and much of it is not helpful for a description that should be easy to read to get a general sense of the state of your UI.

Radiography filters this detailed tree of groups down to only contain the actual LayoutNodes and Android Views emitted by the composition. It identifies each such node by the name of the function call that is highest in the subtree below the parent emitted node. The node's modifiers are used to extract interesting data about the composable. Most of the interesting data is stored in a single modifier, the SemanticsModifier. This is the modifier used to store "semantics" information which includes accessibility descriptions, actions, and flags, and is also used for writing UI tests.

License

Copyright 2020 Square Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Name		Name	Last commit message	Last commit date
Latest commit History 313 Commits
.github		.github
assets		assets
buildSrc		buildSrc
compose-tests		compose-tests
compose-unsupported-tests		compose-unsupported-tests
gradle/wrapper		gradle/wrapper
radiography		radiography
sample-compose		sample-compose
sample		sample
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASING.md		RELEASING.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Radiography

Usage

Result example

Custom Hierarchy Exploration

Jetpack Compose support

Compose usage

Rendering composables

Selecting which composables to render

Subcomposition scanning

Call group collapsing

Compose example output

FAQ

What is Radiography useful for?

Is Radiography production ready?

Why use custom attribute string rendering instead of View.toString() ?

How are compositions rendered?

License

About

Releases

Packages

Languages

License

elihart/radiography

Folders and files

Latest commit

History

Repository files navigation

Radiography

Usage

Result example

Custom Hierarchy Exploration

Jetpack Compose support

Compose usage

Rendering composables

Selecting which composables to render

Subcomposition scanning

Call group collapsing

Compose example output

FAQ

What is Radiography useful for?

Is Radiography production ready?

Why use custom attribute string rendering instead of View.toString() ?

How are compositions rendered?

License

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages