test/viewport/README.md rewritten sentence by sentence

What the test does comes first, then the widths, the checks, the
canned network, what it cannot check, the files, and its relation to
the unit tests. The repo's history and issue references are gone;
every sentence is under about 30 words.

Model: fable-5-1

test/viewport/README.md

@@ -7,28 +7,27 @@ in a real browser:
 make frontend-viewport-test
 ```
 
-First it runs the unit tests. Then it builds the page into `dist/`. It serves
-`dist/` with the nginx image and the `configs/nginx.conf` that the Docker image
-ships. Before the browser starts, it fetches `/` and `/no-such-page`, which
-nginx answers with the page. Both must carry `Cache-Control: no-cache` and a
-`Content-Security-Policy` header. Then it starts a headless Chrome in a
-container and opens the page in it at each width. For each width it measures the
-layout inside the page and checks the measurements in Node. The checks decide
-pass or fail. Screenshots and a `results.json` land in `tmp/viewport/`, for a
-person to look at when a check fails.
+It runs the unit tests, builds the page into `dist/`, and serves it from the
+same nginx image, with the same `configs/nginx.conf`, as the Docker image.
+Before the browser starts, it checks that `/`, and a path nginx answers with the
+page, are served with `Cache-Control: no-cache` and a `Content-Security-Policy`
+header. Then it starts a headless Chrome in a container and opens the page in it
+at each width. For each width it measures the layout inside the page and checks
+the measurements in Node. The checks decide pass or fail. Screenshots and a
+`results.json` land in `tmp/viewport/`, for a person to look at when a check
+fails.
 
-The test is not part of `make check`: it takes minutes, and `make test` has to
-finish in under 60 seconds.
+The test is not part of `make check`: it needs Docker and takes minutes, and
+`make test` has to finish in under 60 seconds.
 
 ## The widths
 
-The breakpoints are read from the page's own files. `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.
+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.
 
 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
@@ -50,11 +49,9 @@ Four more widths are fixed, each for a stated reason:
   touch device
 - 1280 by 800 pixels: a desktop window
 
-Every width but 1280 by 800 is tested as a touch device.
-
 ## The checks
 
-A failed check does not stop the others.
+Every check runs at every width, and none stops the others.
 
 - `app-rendered`: at least 10 WAN host rows exist, and at least 5 rows show a
   number as their latency. Without this, the other checks could pass against a
@@ -63,11 +60,11 @@ A failed check does not stop the others.
   failure, the widest content is named.
 - `nothing-past-viewport-edge`: no visible element extends past the window's
   edge.
-- `no-clipped-text`: no element hides its text behind `overflow: hidden` or
-  `overflow: clip`. Text 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`,
+- `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`,
   `#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
@@ -80,10 +77,9 @@ 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. The narrow layout must not skip the checks.
+  width.
 - `gateway-detection-still-runs`: the `Local Gateway` row is present at this
-  width, so the gateway was looked for and found. The narrow layout must not
-  skip that search.
+  width, so the gateway was looked for and found.
 
 ### The tap-target size
 
@@ -101,10 +97,9 @@ from a fixed table of delays: 2, 45, 123, 456 and 780 milliseconds. Which delay
 a target gets depends on its URL, and about one target in seven fails outright.
 So the rows show one-, two- and three-digit latencies and some unreachable rows,
 and the layout is tested against that spread. The request to
-`http://192.168.1.1` is answered after 5 milliseconds, so the `Local Gateway`
-row appears.
+`http://192.168.1.1` is answered, so the `Local Gateway` row appears.
 
-At each width, the test sets the interval to 1 second and waits until at least 5
+On each page, the test sets the interval to 1 second and waits until at least 5
 rows show a latency before it measures. The page discards its first round, so
 this reaches a filled page without waiting out two rounds at 3 seconds.
 
@@ -118,8 +113,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
-  about as wide as on a real device, but not exactly. A layout that fits here by
-  a few pixels might not fit there.
+  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.
 - 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
@@ -138,9 +133,8 @@ this reaches a filled page without waiting out two rounds at 3 seconds.
 
 ## Relation to the unit tests
 
-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/`.
+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/`.