Inspecting a tree
.
A tree can tell you what is in it, where layout put each node, and what a point on the screen hits. Tests use that, and so do the devtools. This page goes through the questions you can ask.
Finding nodes
Silk
Copy
let
found = run
tree.find
("refresh"
)find
returns the nodes whose test id, label or text is the given string. Give the nodes you care about a test id, with tree.setTestId
, and tests can find them however the layout changes.Where things are
Silk
Copy
if
let
Option
.Some
{ value: box } = run
tree.bounds
(button) {
// box.xMin, box.yMin, box.xMax, box.yMax, in CSS pixels of the viewport
}bounds
is a node's border box after the last frame. A node that is not laid out, such as one that is detached, has none, so the answer is an Option
.tree.fragments(node)
gives one box per line for inline content that wraps.What a point hits
Silk
Copy
let
hit = tree.hitTest
(200.0
, 150.0
) // what pointer input there would target
let
seen = tree.pick
(200.0
, 150.0
) // what an element picker would select
hitTest
answers exactly as input does: text resolves to its box, and nodes with pointer-events: none
are skipped. pick
is for tools: it returns the topmost painted node, whatever it is.One node, in full
Silk
Copy
if
let
Option
.Some
{ value: view } = tree.view
(button) {
view.accessRole
() // Role.Button
view.testId
() // "refresh"
view.state
() // hovered, pressed, focused, focusVisible
view.listens
(EventKind
.Click
) // whether it listens
view.style
(StyleState
.Hover
) // the declarations set for a look
view.computed
() // the resolved style
}A
NodeView
is a read-only look at one node: its attributes, its state, the styles the client set for each look, and the computed style layout used. It is what the devtools' side panel shows.The whole tree as text
Silk
Copy
let
text = run
tree.describe
(DescribeOptions
.plain
())describe
writes the tree as indented text, one node per line, with its kind, id, role, test id, text and box. This is the card from Nodes and styles:Output
Copy
box #1 [0,0 400x240]
box #2 [39,45.5 322x149]
box #3 [60,66.5 280x27]
text #4 "Tide tables" [60,66.5 108.64x27]
box #5 [60,101.5 280x20]
text #6 "High water at " [60,101.5 99.29x20]
box #7 [159.29,101.5 38.6x20]
text #8 "06:42" [159.29,101.5 38.6x20]
text #9 ", low at 12:57." [197.88,101.5 96.34x20]
box #10 role=button testId="refresh" [60,137.5 280x36]
text #11 "Refresh" [173.12,145.5 53.76x20]
DescribeOptions.withStyles()
adds what each node looks like, and tree.describeNode(node, options)
writes one subtree:Output
Copy
box #10 role=button testId="refresh" [60,137.5 280x36] background=rgba(15,118,110,1) radius=8 color=rgba(255,255,255,1)
text #11 "Refresh" [173.12,145.5 53.76x20]
That text is a good thing to keep in a test. Save it, and compare it on every run: a layout that moves by a pixel shows up as one changed line you can read, which a picture that differs cannot give you.
Pictures
examples/src/tree/picture.silk
Copy
//! Pictures of a tree: a frame drawn on the CPU and encoded as a PNG. No window and no GPU,
//! so it runs anywhere, a test or a server included.
import
ui_tree.inspect { CpuSnapshot
, encodePng }
import
ui_tree.lib { Tree
, TreeError
, Viewport
}
import
codec.image { ImageError
}
import
vector.geometry_error { GeometryError
}
import
silk.collections.bytes { Bytes
}
import
silk.mem.allocator { Allocator
, OutOfMemoryError
}
/// Takes pictures of one tree. Keep it for as long as the tree: it holds the glyphs and
/// images earlier frames made, which later frames use again.
pub
struct
Camera
{
snapshot: CpuSnapshot
,
}
impl
Camera
{
pub
fn
make
() -> Camera
{
return
Camera
{ snapshot: CpuSnapshot
.make
() }
}
/// The tree as it looks in `viewport` at `time`, as the bytes of a PNG file.
pub
effect
fn
png
(self: &mut
Self
, tree: &mut
Tree
<'_>, viewport: Viewport
, time: f64) -> Bytes
! TreeError
| GeometryError
| ImageError
| OutOfMemoryError
? &mut
Allocator
{
// A frame styles, lays out and paints what changed, into a scene.
drop
run
tree.frame
(viewport, time)
// The snapshot copies the glyphs and images the frame made, then draws the scene.
run
self.snapshot.sync
(tree.engineMut
())
let
pixels = run
self.snapshot.render
(tree.engine
())
return
run
encodePng
(&pixels)
}
}Every picture in this guide was made with this
Camera
, by the docs build, from the example code on the page. Where the examples run in the page instead, the pictures are what a browser without WebGPU shows. It draws on the CPU, so it needs no window and gives the same pixels on every machine.Pictures and
describe
text together are how the tree's own tests work: each scene has a saved .txt
and a saved .png
, and a change to either fails the test.Testing a tree
tests/src/tree.silk
Copy
//! Tests for the UI tree examples: a tree is plain data in and plain data out, so a test
//! drives it exactly as a window does.
import
examples.tree.card as
card
import
examples.tree.clicker as
clicker
import
examples.tree.field as
field
import
examples.tree.remote as
remote
import
ui_fixtures.fixtures as
fixtures
import
ui_tree.lib {
DescribeOptions
,
Event
,
Input
,
NodeId
,
ProtocolError
,
Tree
,
TreeError
,
Viewport
}
import
silk.core.effect
{ Effect
}
import
silk.core.option { Option
}
import
silk.geometry.rect { Rect
}
import
silk.mem.allocator { Allocator
, OutOfMemoryError
}
import
silk.testing.testing { Testing
, AssertionError
}
import
silk.text.string { String
}
fn
viewport
() -> Viewport
{
return
Viewport
{ width: 400.0
, height: 240.0
, scale: 1.0
}
}
/// Clicks the middle of `node`.
effect
fn
click
(tree: &mut
Tree
<'_>, node: NodeId
) -> ()
! TreeError
| OutOfMemoryError
? &mut
Allocator
{
drop
run
tree.frame
(viewport
(), 0.0
)
if
let
Option
<Rect
<f32>>.Some
{ value } = run
tree.bounds
(node) {
let
x = (value.xMin + value.xMax) * 0.5
let
y = (value.yMin + value.yMax) * 0.5
run
tree.dispatch
(Input
.press
(x, y))
run
tree.dispatch
(Input
.release
(x, y))
}
}
effect
fn
treeBody
() -> ()
! AssertionError
<'static
> | TreeError
| ProtocolError
| OutOfMemoryError
? &mut
Allocator
{
let
fonts = run
fixtures.fonts
()
// Queries: find a node by its test id, and read where layout put it.
let
mut
tree = run
Tree
.make
(&fonts)
let
sans = run
tree.fontFamily
("Noto Sans, sans-serif"
)
let
built = run
card.build
(&mut
tree, sans)
drop
run
tree.frame
(viewport
(), 0.0
)
let
found = run
tree.find
("refresh"
)
run
Testing
.expect
(found.length
() == 1
&& found.get
(0
).is
(built.button), "find reads test ids"
)
let
text = run
tree.describe
(DescribeOptions
.plain
())
run
Testing
.expect
(String
.contains
(String
.view
(&text), "Tide tables"
), "describe writes the tree"
)
// Events: input in, records out, and the client changes the tree.
let
mut
second = run
Tree
.make
(&fonts)
let
family = run
second.fontFamily
("Noto Sans, sans-serif"
)
let
mut
counter = run
clicker.build
(&mut
second, family)
run
click
(&mut
second, counter.button.id
())
run
click
(&mut
second, counter.button.id
())
run
counter.pump
(&mut
second)
run
Testing
.expect
(counter.clicks == 2
, "two clicks were recorded"
)
let
after = run
second.find
("Clicked 2 times"
)
run
Testing
.expect
(after.length
() == 1
, "and the label says so"
)
// Text: the tree edits, the client hears the new value.
let
mut
third = run
Tree
.make
(&fonts)
let
face = run
third.fontFamily
("Noto Sans, sans-serif"
)
let
mut
greeting = run
field.build
(&mut
third, face)
run
third.focus
(greeting.name)
run
third.dispatch
(run
Input
.text
("Ada"
))
run
greeting.pump
(&mut
third)
run
Testing
.expect
((run
third.find
("Hello, Ada."
)).length
() == 1
, "typing reaches the greeting"
)
// The protocol: the client's own numbers come back in the records.
let
mut
fourth = run
Tree
.make
(&fonts)
run
fourth.apply
(run
remote.first
())
run
click
(&mut
fourth, NodeId
.of
(remote.BUTTON
))
let
records = run
fourth.events
()
run
Testing
.expect
(records.length
() == 1
, "one click"
)
run
Testing
.expect
(records.asSlice
()[0
].target.raw
() == remote.BUTTON
, "on the client's node 2"
)
if
let
Event
.Click
{ .. } = &records.asSlice
()[0
].event {
run
fourth.apply
(run
remote.sent
())
}
run
Testing
.expect
((run
fourth.find
("Sent"
)).length
() == 1
, "the answer is one mutation"
)
}
test effect
fn
aTreeIsDataInAndDataOut
() -> ()
! AssertionError
<'static
> | TreeError
| ProtocolError
| OutOfMemoryError
{
let
mut
allocator = Allocator
.systemAllocatorProvider
()
run
treeBody
() |> Effect
.provideMut<Allocator
>(&mut
allocator)
}A test drives a tree the way a window does: it dispatches input and reads records. There is nothing to mock, because nothing in a tree reaches outside.
Inspecting a running app
All of the above is also available from outside a running app, over a socket: the tree as text, a node's styles, screenshots, and real input. That is the inspector, and the devtools and the command line tool are built on it. Devtools covers it, and it works the same for a bare tree client as for a Silk UI app.