test/viewport/README.md: rework against the second review
check / check (push) Canceled after 0s

The unit-test sentence is split so its subject meets its verb: the
tests call the exported functions; make test runs them with Node's
test runner. The full pass also fixed two claims broader than the code
(every min-width condition; every interactive control), two sentences
whose subject was split from its verb (the ellipsis exception, the
font width), and put back three dropped reasons in one sentence each:
the ellipsis cut is a design choice, the narrow layout must not skip
the checks or the gateway search, and neither test replaces the other.

Model: fable-5-1
This commit is contained in:
clawbot
2026-10-26 04:34:09 +00:00
parent a2de3b2b94
commit b18ae0724b
+22 -19
View File
@@ -22,12 +22,13 @@ The test is not part of `make check`: it needs Docker and takes minutes, and
## The widths
The widths come from the page's own CSS. `viewports.js` reads every `min-width`
and `max-width` condition out of the `@media` blocks in `web/src/styles.css`. It
also looks in `web/src/main.js` and `web/index.html` for Tailwind's responsive
class prefixes, such as `md:`, and takes their breakpoints. Each breakpoint is
tested at one pixel below it, exactly on it, and one pixel above it. Today the
CSS has one breakpoint, `max-width: 768px`, and no responsive prefix is used.
The widths come from the page's own CSS. `viewports.js` reads the `min-width`
and `max-width` conditions out of the `@media` blocks in `web/src/styles.css`.
It also looks in `web/src/main.js` and `web/index.html` for Tailwind's
responsive class prefixes, such as `md:`, and takes their breakpoints. Each
breakpoint is tested at one pixel below it, exactly on it, and one pixel above
it. Today the CSS has one breakpoint, `max-width: 768px`, and no responsive
prefix is used.
A `max-width: 768px` block matches at 768 pixels. Testing both sides of each
breakpoint catches a layout that switches one pixel too early or too late. A
@@ -61,10 +62,10 @@ A failed check does not stop the others.
- `nothing-past-viewport-edge`: no visible element extends past the window's
edge.
- `no-clipped-text`: no element hides its text behind `overflow: hidden`. Text
cut with an ellipsis, as Tailwind's `truncate` does on host names and URLs, is
allowed.
- `tap-targets-44px`, on touch widths: every interactive control is at least 44
by 44 CSS pixels. The controls are `#pause-btn`, `#interval-select`,
cut with an ellipsis is allowed: that cut is a design choice, not a defect.
Tailwind's `truncate` cuts host names and URLs that way.
- `tap-targets-44px`, on touch widths: each measured control is at least 44 by
44 CSS pixels. The controls are `#pause-btn`, `#interval-select`,
`#debug-toggle` and the `.pin-btn` in each WAN host row. The check also
demands that each selector matches enough visible elements: one of each single
control, and one pin button per WAN host row. A renamed class would otherwise
@@ -77,9 +78,10 @@ A failed check does not stop the others.
is `row` and the graph sits to the right of the details. A row that only
shrank its fixed 420-pixel column fails.
- `probing-still-runs`: the page sent at least one check to a target at this
width.
width. The narrow layout must not skip the checks.
- `gateway-detection-still-runs`: the `Local Gateway` row is present at this
width, so the gateway was looked for and found.
width, so the gateway was looked for and found. The narrow layout must not
skip that search.
### The tap-target size
@@ -113,8 +115,8 @@ this reaches a filled page without waiting out two rounds at 3 seconds.
- Physical pixels. The device pixel ratio is set, but antialiasing, colour
rendering and legibility at a given physical size are not measured.
- Fonts. The container has DejaVu, not a phone's own monospace font. Text is
close to, but not the same width as, text on a real device. A layout that fits
here by a few pixels might not fit there.
about as wide as on a real device, but not exactly. A layout that fits here by
a few pixels might not fit there.
- Performance. The cost of redrawing the graphs, battery use and behaviour on a
slow connection are not measured.
- The browser's own frame. The address bar, safe-area insets and notch cutouts
@@ -133,8 +135,9 @@ this reaches a filled page without waiting out two rounds at 3 seconds.
## Relation to the unit tests
The unit tests in `test/unit/`, which `make test` runs with Node's built-in test
runner, call the functions `web/src/main.js` exports, with no browser. This test
runs the built page in a real browser engine and is the only test here that can
see a media query. Checks on computed styles and element geometry belong here;
checks on functions belong in `test/unit/`.
The unit tests in `test/unit/` call the functions that `web/src/main.js`
exports, with no browser. `make test` runs them with Node's built-in test
runner. This test runs the built page in a real browser engine and is the only
test here that can see a media query. Neither replaces the other. Checks on
computed styles and element geometry belong here; checks on functions belong in
`test/unit/`.