On 22 August I added a single PlayMode test to Scaling Laws whose only job was to draw one interface page into a texture and write it to disk as a PNG. It did not compare anything. It did not have a baseline. It saved a picture.
It found four faults in its first run. The suite that day was 683 tests and all of them were green, and had been green through every one of those four.
The four
I am listing them in full because the pattern matters more than any one of them. None of these is exotic. Every one had been shipped.
| What the picture showed | Why no test caught it |
|---|---|
| Every styled button drew its text at the top left of itself instead of centred. | The label had the right text, the right font size and the right click handler. Every property a test can name was correct. The fault was two missing alignment lines, and alignment has no observable value to assert. |
| Eleven trait tiles had no art. The cards were there, the text was there, the image area was empty. | The code named each image correctly and the names resolved. Nothing ever drew them. A test asking whether a card knows its art passes; asking whether the art is on screen is a question about pixels. |
| A difference bar drew a two point gain as full width on a reading where the underlying number was negative. | The bar scaled itself by its after value. With a negative after value the arithmetic produced a fill fraction above one, which clamps to full. The number printed under it was right. Only the bar lied. |
| Money printed as $20,00 rather than $20.00. | The format string was :N2, which follows the machine culture.
On my machine that is Polish. Every currency test compared against a string
produced by the same machine culture, so both sides were wrong together. |
The last one is the whole argument in miniature
A test that formats a number and compares it to a formatted number cannot find a formatting fault, because the mistake lives in the step both sides share. You can write a hundred of those and the build will still print the wrong currency to everybody whose regional settings differ from yours.
A picture shares no step with the code that drew it. That is the entire reason it works.
Why an assertion structurally cannot see this
It is worth being precise here, because write more tests is not the lesson.
An assertion names a value and compares it. A layout fault is not a value, it is a relationship. A card that overflows its page by twelve pixels has a correct width and sits in a correct container. The fault exists only in the arithmetic between them, and that arithmetic is performed by the layout engine after your code has finished running. By the time it is wrong there is nothing left for your code to assert about.
You can assert on the relationship, and in two specific cases below I do. But you have to know which relationship to suspect first, and the thing that tells you which one to suspect is looking at it.
Before this existed, the only way to look at a UI Toolkit screen in this project was to open the editor, load the scene, play into the right state and find the page. That is several minutes per screen and there are now more than eighty screens. In practice it meant the screens I had touched recently got looked at and the rest did not. The stylesheet for one whole area sat unreferenced for weeks with 170 tests green, and a single missing class collapsed the entire right hand half of the model creator, because nobody had a reason to open either one.
The rig, in about forty lines
This is the whole mechanism. It is not clever, and that is the point: anything harder than this does not get written.
Three details in there are load bearing, and all three cost me a run to learn.
Instantiate the PanelSettings. Using the project asset directly works, and then the asset is left pointing at a render texture that no longer exists, and the game opens with no interface at all. Copy it.
Wait longer than feels necessary. A dozen frames plus most of a second sounds absurd for a static page. It is not. UI Toolkit resolves layout over several frames, and anything with an entry transition or a scheduled reveal is still moving after the first one. My early frames were pictures of half drawn pages, and I lost an evening to a bar that turned out to be mid-animation.
Put the output in a tilde folder. ScreenProof~/ with the
trailing tilde is not decoration. Unity ignores tilde-suffixed folders entirely, so
eighty PNGs do not become eighty imported assets with eighty meta files in your diff.
The two things a picture cannot be trusted on
A saved frame that nobody opens is worth nothing, and nobody opens eighty of them every run. So the test asserts the two failures a human would miss while looking straight at the image.
One: that anything was drawn at all
This is the trap I would not have predicted. A render texture that nothing drew into comes back as a flat rectangle of the clear colour. The clear colour here is a very dark blue, because the game is dark. A picture of a screen that failed completely and a picture of a dark screen that worked are, at a glance, the same picture.
So the test measures spread: the distance between the lightest and darkest sample in the frame, taken over every thirty seventh pixel, and requires more than two per cent.
Sampling every thirty seventh pixel rather than all two million is not an optimisation I measured, it is just enough. A page that drew nothing has zero spread and a page that drew anything has plenty. There is no interesting middle to resolve.
Two: that nothing crossed the right hand edge
UI Toolkit overflows silently. An element wider than its parent does not clip, does not warn and does not log. It wraps, or it extends past the edge, and either one reads like something you meant.
Four trait cards in this project once measured 1352 pixels against a 1340 pixel page. The fourth wrapped onto its own line. For weeks I assumed that was a layout decision somebody had made, possibly me.
The two pixels of tolerance matter. Without them, sub-pixel layout rounding turns this into a test that fails occasionally for no reason, and a test that fails for no reason is a test everybody learns to ignore, which is worse than not having it at all.
One exception, and it is not optional
The walk has to skip elements the runtime theme built for itself, or the check fires
on Unity's own internals. The rule I settled on: an element counts as theme-internal
only if it has classes and every one of them starts with unity-. An
element with no classes at all is not theme-internal, it is an unstyled element the
project made, and those are precisely the ones worth catching.
The one that cost the most: 319 pixels of every tab
On 30 September a player wrote in to say the blue background of the tutorial covers every tab. Nothing was covering anything, and that report is the best illustration I have of why this technique earns its keep.
The tutorial strip sits along the bottom of the screen, so the page behind it needs
clearance. I had set that clearance as paddingBottom on the
ScrollView.
A ScrollView lays its viewport out inside its own padding box. So the reserve came out of the visible half of the page rather than the scrollable half. Measured at 1920 by 1080: a 943 pixel scroller kept a 624 pixel viewport, and the other 319 pixels of every tab were not drawn at all. The window's own colour showed through the hole, which is the blue the player described. And the page could not be scrolled down into it, because as far as the scroller was concerned there was nothing there to scroll to.
The same number on the content container is extra page underneath the last row, which is what a clearance is supposed to be. One word of difference in the property path, a third of the window either way.
There is now a fixture that loads the game scene, opens a long tab with the tutorial up and measures the viewport against the scroller. It fails if the distinction is ever lost again, which is the only kind of regression test worth writing: one that holds a specific mistake you have already made.
What this deliberately is not
It is not visual regression testing. There are no golden images and nothing is compared between runs, and I want to be straight about why, because the obvious next step is to add diffing and I decided against it.
Golden image diffing fails on any change, including every intentional one. I change the styling of this game weekly. On a one person project, where the same person changes the look and approves the new baseline, the approval step becomes a reflex inside about three weeks, and a baseline you approve without looking is a baseline that certifies whatever you just broke.
So the frames are saved and only structural facts are asserted. The pictures are for me, for the five minutes after a run when I flick through the new ones. The assertions are for the build. Those are two different jobs, and conflating them is what makes visual testing get abandoned three months in.
Where it stands
Eight weeks on, the project runs 1,619 EditMode tests and 88 that load a scene, and 82 of the scene tests write a frame. The folder holds pictures of the world map, the cabinet interior, the release planner, the pause menu, the save slots, the achievements page, the messenger, the address book, every stage of the model creator and the regulatory inspection banner.
The achievements page is the one I would point at. Forty seven rows in ten groups inside a 620 pixel card, drawn in the state a brand new player sees it in, where every row is locked. No assertion can tell me whether that reads as deliberate or as broken. A picture can, in one second, and before this existed nobody had ever opened it.
If you want to add this today
- One test, one page, no assertions. Render your busiest screen, write the PNG, open it. Do not build a framework. The value arrives on the first run.
- Add the flatness check immediately. It is five lines, and it is the difference between a suite that proves something and a folder of dark rectangles.
- Add the overflow check when you first get bitten. With a couple of pixels of slack, and with a skip rule for your UI framework's own elements.
- Build the interesting state by hand. A screenshot of a company with one release proves nothing about the layout that three releases needs. My fixture constructs a company with a model updated three times, badly once, because the comparison screen only has a job to do in that case.
- Tilde the output folder, and do not commit the frames.
The cost was one afternoon. The return was four shipped faults in the first run, and a player report I could diagnose in ten minutes instead of a weekend. I have not found a cheaper trade in this project.
Questions people ask about this
Why do passing tests miss UI layout bugs?
Because an assertion reads one value and a layout fault is a relationship between boxes. A button whose label sits in the corner still has the right text, size and click handler, so every property you can name is correct. The fault exists only in the arrangement, and the arrangement is a picture.
How do you render a UI Toolkit screen to a PNG in a test?
Create a RenderTexture, instantiate a copy of your own PanelSettings and point its
targetTexture at it, add a UIDocument with those settings, attach the
page, yield for about a dozen frames plus most of a second so layout and entry
animations finish, then ReadPixels into a Texture2D and write
EncodeToPNG to disk. Copy the settings rather than using the asset, or
the test leaves your real one pointing at a texture that is gone.
What should a screenshot test actually assert?
The two things a human looking at the image cannot be trusted on. That something was drawn at all, because an empty render texture is a flat rectangle of the clear colour and on a dark interface that looks like success. And that nothing crossed the right hand edge, because UI Toolkit overflows silently and a wrapped row reads as a decision.
Is this visual regression testing with golden images?
No, deliberately. Diffing against an approved baseline fails on every intentional change too, and when one person both changes the styling and approves the baseline, approval becomes a reflex within weeks. A baseline approved without looking certifies whatever you just broke. Saving frames and asserting structural facts only keeps the images useful without the ritual.
Why does padding on a ScrollView break the page?
A ScrollView lays its viewport out inside its own padding box, so padding on the
scroller shortens the window rather than lengthening the page. Here a 943 pixel
scroller kept a 624 pixel viewport and the remaining 319 pixels of every tab were
never drawn, and could not be scrolled into because the scroller believed there was
nothing there. The same value on contentContainer is extra page at the
bottom, which is what a clearance should be.
Every fault in this article is real and was found in Scaling Laws,
an AI company tycoon released as a free public build with the source open. The rig
lives in Tests/PlayMode/ScreenProofTests.cs.
The game page and the source · The eighteen systems you could not reach