The Guard That Watched the Page Instead of the Screen

A Fix That Passed Everything and Changed Nothing

The promotion rule shipped with a guard: if the head already has enough pictures, do nothing. Correct rule, correct constant, and it made no visible difference whatsoever.

The guard measured the head as the first limit rows — the number the client asked for. But the client asks for a page many times larger than a screen, because it wants scroll headroom. Across that many rows, enough carry pictures to clear any reasonable floor. So the guard concluded there was no problem and returned early, while the dozen cards a person sees without scrolling stayed exactly as empty as before.

Two Meanings of "Head" That Look Identical in Code

The bug is one expression. Slicing to the requested limit and slicing to the visible region are both a slice of the front of a list, they both read as "the top of the shelf", and only one of them is the thing the complaint was about. Nothing in the type system distinguishes them, and nothing in a review will either, because the wrong one looks exactly as reasonable as the right one.

The fix is to make the visible region an explicit named constant and to slice against the smaller of the two. The naming is the actual repair: once the code says screen rather than limit, a future reader can tell which of the two meanings is intended, and the next person adding a rule here has the right noun available.

The Simulation Confirmed It, and the Simulation Was Fiction

This is the part with the longest reach. Before shipping, the rule had been checked in a simulation, which reported it working. The simulation had hard-coded a head size and a candidate pool — both plausible, neither matching what the endpoint actually produces. It was measuring a shelf the code never renders.

A simulation cannot catch a bug in your model of the system, because the simulation is your model of the system. It will faithfully confirm whatever you believed when you wrote it, and the more carefully you build it, the more convincing that confirmation is. What found this was calling the real endpoint at the real limit and counting the pictures in the first twelve rows of the actual response.

Assert on What a Person Would See

The durable form of the lesson is about where an assertion points. A test that checks the function returned rows in the right order tests the function. A test that counts pictures in the first screen of a real response tests the claim the feature exists to make. Only the second one fails when the two definitions of head diverge.

A simulation confirms your model; only the real thing tests it. When a fix targets something a person perceives, the verification has to run through the same path they do — same endpoint, same parameters, same slice — because every shortcut you take is a place your assumption gets to substitute for the system.

Code

Page-size guard versus screen guard, and the assertion that distinguishes them·python

# BEFORE -- passed its tests, changed nothing a person could see.
def apply_image_floor(rows, limit):
    head = rows[:limit]              # limit is what the CLIENT asked for
    have = sum(1 for r in head if r.get("image_url"))
    if have >= IMAGE_FLOOR:
        return rows                  # ...and across a page this size,
    ...                              #    it always was


# AFTER -- the visible region is named, and it is the smaller of the two.
HEAD_CARDS = 12                      # what a person sees before scrolling

def apply_image_floor(rows, limit):
    screen = min(HEAD_CARDS, limit)  # the SCREEN, never the page
    head = rows[:screen]
    have = sum(1 for r in head if r.get("image_url"))
    if have >= IMAGE_FLOOR:
        return rows
    ...


# The test that would have caught it. Not 'did the function reorder
# correctly' -- that passed. This asserts the CLAIM the feature makes,
# through the real endpoint at the real limit.
def test_first_screen_carries_pictures(client, seeded_shelf):
    body = client.get("/api/shelf/1?limit=60").json()      # as the client asks
    first_screen = body["articles"][:HEAD_CARDS]           # as a person sees
    with_pictures = sum(1 for a in first_screen if a["image_url"])
    assert with_pictures >= IMAGE_FLOOR, (
        f"{with_pictures}/{HEAD_CARDS} on screen carry pictures"
    )

Exercise

Find a feature whose value is perceptual — layout, ordering, how much of something appears without interaction — and check what its tests assert. If they assert on a function's return value rather than on what the real endpoint produces at real parameters, write the second kind and run it. Note whether the two disagree.

Hint

The disagreement usually hides in a parameter the test supplies and the client does not, or the reverse. Page sizes, default limits, and feature flags are the usual suspects, because a test author picks a small convenient number and the real client picks whatever the design needed.

A Fix That Passed Everything and Changed Nothing

Two Meanings of "Head" That Look Identical in Code

The Simulation Confirmed It, and the Simulation Was Fiction

Assert on What a Person Would See

Code

External links

Exercise

Progress

Comments 0