Repository navigation
Commit 7a7d013
Retake the guide's automatic screenshots against the redesigned window (#620)
## Why
First part of #561. The redesign is on trunk
(#591) and the
guide's screenshots still show the old window. Twelve of the guide's
images are taken by the harness with nobody at the keyboard; this
retakes those, and fixes what made a retake depend on the day and on the
network.
## What changes
**Twelve screenshots retaken** (`npm run shots`, the fixture tier): the
empty window, the create-site dialog, a Core and a Gutenberg site, the
site's menu, the notice for old code, the apply card, the question a
link raises, the terminal, the logs and the mail in the tray, and an
incomplete update.
**The harness, so that a retake is the same picture whenever it is
taken:**
- **The fixture's dates are counted back from the day of the shots.**
They were written down as 16 September, which was fresh for a fortnight;
after that every site in every picture wore "This site's WordPress code
is 19 days old". The code's date is at midnight UTC, since the app
counts its age in whole days. The mail and the lines in debug.log are
dated the day before.
- **No automatic shot reaches the network or starts a process.** A
ticket's pull requests are answered by the fixture: left to GitHub, the
site's menu was photographed over a card still "Checking GitHub…". The
dev server and the script it runs first are answered for every shot; the
mail's shot used to start a real server in a folder that holds no
WordPress, and showed whatever port the mail server had picked.
- **Motion is reduced**, so a tab's underline is not caught half way to
its tab.
**Beside the images:** the alt text of three of them said what the old
pictures showed, and the few sentences next to the create-site dialog's
named the old button and labels.
`docs/public/screenshots/pr-applied.png`, which no page uses, is
removed.
**Not in this pull request:**
- The other sixteen images: nine that need a person at a real site, and
six nobody's script takes. They are being moved to the automatic tier,
in the pull requests that follow.
- The guide's prose, apart from the lines above. It follows the
screenshots, in four pull requests by topic.
## How to test this
Platforms: macOS to reproduce the committed images; the harness runs on
any. Nothing here ships in the app: the change is a documentation tool
and its output.
From the repository root, after `npm ci`:
```
npm run shots
git status --short docs/public/screenshots
```
1. The run prints twelve lines, each `✓ <name>.png`, and exits 0. It
opens the app's window four times and closes it; do not type while it
runs.
2. On the machine and the UTC day the committed images were taken, `git
status` shows nothing changed. On a later day it shows the images that
carry a date (below); on another machine it may show them all, since
fonts are drawn differently.
3. Open the twelve PNGs. Each shows a finished state: no spinner, no
menu half open, nothing cut by the edge of a crop. Every path is under
`/tmp/wpct-docs-fixture/`.
**What must not have happened:** a real server started, or anything
asked of GitHub or Trac, by a shot; a picture with a path under a home
folder, or with a notice that the code is old on a site that is meant to
be fresh.
**What cannot be promised:** the same bytes on another machine or
another day. The images are identical between two runs on one machine
within one UTC day, which I checked by taking them twice. A date is
drawn in the whole-window shots (when a site was made and its code's
date), in the site's menu shot (the pull requests' dates), in the mail
and in the logs; system fonts and the window's frame differ between
systems; and on Windows the fixture's folder is under the system's
temporary folder, so the path in the logs' shot differs.
## Risks and limitations
- Review: 2 passes, 7 findings fixed here, and 5 follow-ups all taken
here. Details below.
- **A run that crosses midnight UTC** can draw dates that do not agree
with each other: the fixture counts its days once, as the run starts.
- **The dev server never comes up in a shot.** Its start is accepted and
it gives no address, so a whole-window shot taken after pressing Start
would show it starting for ever. None of the twelve does that; the two
that press Start are crops of the tray. A shot of a running server needs
the address said to the window as well, which belongs with the shots
that follow.
- The guide's text now describes the old window beside new pictures,
until the text follows.
## Related
Part of #561, which is part of #542.
---
<details>
<summary>Design decisions and alternatives considered</summary>
- **Days counted back, not dates bumped.** The file's own comment said
to bump the dates "when that happens", expecting years; the notice
appears after fourteen days. Counted back, "126 days old" is the same on
every retake, where written down it changed every day.
- **One set of stand-ins for the whole tier**, installed once per
launch, and not a few lines in each shot that needs them. A shot that
forgets is then one that cannot start a server, where before it was one
that did.
- **The mail server is said to have started, on a port of the
fixture's.** Cropping its line out of the picture was the other way; the
line is part of what the tray shows.
</details>
<details>
<summary>Review outcome (required — see AGENTS.md)</summary>
**Pass 1: 4 [fix here] · 3 [follow-up]. Pass 2 (on the fix-up): 3 [fix
here] · 2 [follow-up]. All 7 fixed, and all 5 follow-ups taken here.**
- **Review:** completed — a separate agent context, read-only; head
`44cc5ff` / base `887afe1`; ESLint on the scripts run, the twelve images
opened and looked at one by one, the shots not run; 4 [fix here], 3
[follow-up].
- Fixed: the old site read "125 days old" before nine in the morning UTC
and "126" after, from the hour I had put on its date; the stand-in for a
ticket's pull requests left out two fields of the real answer; a comment
said when the card asks and was wrong; the alt text of three images.
- Follow-ups, taken here: the mail's shot started a real server; it
showed a port that is different every run; the mail was dated before its
site was made.
- **Review:** completed — a second separate agent context, read-only;
head `a9c285b` / base `887afe1`; every path through the two replaced
handlers traced for each shot, what loads the mail list and what can
write the port, the date arithmetic at every hour, the three alt texts
against their pictures; 3 [fix here], 2 [follow-up].
- Fixed: the stand-in's comment said the server is "up"; a comment in
the logs' shot contradicted itself; one alt text counted one line where
the picture has two.
- Follow-ups, taken here: the sentences beside that image still named
the old button and labels; the fixture's debug.log lines were dated
weeks before their site.
- Nothing found: no shot needs a real server or script; the mail's port
can only be the fixture's; nothing references the removed image.
- **Since review:** `a9c285b → 2ce5ad9` is the second pass's fixes, not
reviewed again: two comments, one alt text, five lines of prose, and the
dates in the fixture's log, with that one image retaken. `npm run lint`
and `npm test` pass; the twelve shots were taken again.
</details>
<details>
<summary>Implementation notes</summary>
- `scripts/screenshots/fixtures.cjs`: `daysAgo`, `FRESH`, `STALE`;
`standInForTheOutside` (replaces `git:list-ticket-patches`,
`npm:run-script` and `playground:start` in the main process);
`sayMailServerStarted`.
- `scripts/screenshots/capture.cjs`: reduced motion and the stand-ins,
once per launch of the fixture tier. The live tier gets neither.
- `scripts/screenshots/shots.cjs`: the site's menu waits for the pull
requests' answer; the logs' tray is made taller so the file's first line
is not cut; the mail waits for where the server is said to listen.
</details>
<details>
<summary>Screenshots or recording</summary>
The twelve images are the change: `docs/public/screenshots/` in the
diff, which GitHub shows before and after.
</details>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>1 parent 887afe1 commit 7a7d013
18 files changed
Lines changed: 138 additions & 45 deletions
File tree
- docs
- guide
- public/screenshots
- scripts/screenshots
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
6 | 6 | | |
7 | 7 | | |
8 | 8 | | |
9 | | - | |
| 9 | + | |
10 | 10 | | |
11 | 11 | | |
12 | 12 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
6 | 6 | | |
7 | 7 | | |
8 | 8 | | |
9 | | - | |
| 9 | + | |
10 | 10 | | |
11 | 11 | | |
12 | 12 | | |
13 | | - | |
| 13 | + | |
14 | 14 | | |
15 | | - | |
| 15 | + | |
16 | 16 | | |
17 | 17 | | |
18 | | - | |
19 | | - | |
| 18 | + | |
| 19 | + | |
20 | 20 | | |
21 | | - | |
| 21 | + | |
22 | 22 | | |
23 | 23 | | |
24 | 24 | | |
| |||
Loading
Loading
Loading
Loading
Loading
Loading
Loading
0 commit comments