Photographing a page

osy shot <page> [--as <login>] [--seed <name>] [--width <px>] [--height <px>] [--out <file>] [--path <dir>] [--no-compile] [--json]

Takes one picture of one page of your app in a real browser — signed out or as one of its accounts, on your data or on a dev seed's world, at any width — and prints where the PNG is. No test to write.

Summary#

osy shot /books compiles your app, opens /books in a real browser and saves a picture of the whole page. Add --as <login> to see it as one of the app's accounts sees it, --seed <name> to see it on one of your dev seeds, and --width 390 to see it on a phone. The last line it prints is the PNG's path.

Signature#

osy shot <page> [--as <login>] [--seed <name>] [--width <px>] [--height <px>] [--out <file>] [--path <dir>] [--no-compile] [--json]

Description#

<page> is the page's address inside the app, starting with a slash: /, /books, /case/42. A page whose route has a parameter (/case/{id}) takes any value there. An address the app does not have is refused with the list of the ones it does, before anything starts.
--as <login> signs the browser in as one of the app's own accounts, with no password — this works only on the local platform. Without it the page is photographed signed out. An account the app does not hold is refused with the accounts it does.
--seed <name> loads a dev seed — a fixture marked [TestFixture, DevSeed("…")] — by its name or its label, and photographs the page on that world. The seed goes into an app of its own (your app's name with -shot after it) on the same local platform, so the data in the app you are clicking through is not touched. Without --seed the picture is of your app as it is. An unknown seed is refused with the seeds the tests declare. In the platform's own admin/ project there is no second app to use, so the seed goes into the platform's Admin itself, beside its registry (see Dev seeds: a fixture you can load into the running app).
--width is the browser's width, 1280 by default. 600 or narrower is a phone, with touch, so a page that lays itself out for touch shows that layout. The picture is always the whole page, however long; --height is only the screen it is scrolled in (844 for a phone, 900 otherwise), which decides what 100vh means.
The picture is the one osy test --pixels takes: animations finished, a fixed header or tab bar drawn once where it belongs, embedded frames below the fold painted.
It goes in osy-shots/, named after the page, the width, the account and the seed — so osy shots puts it on the contact sheet beside your tests' pictures. --out puts it somewhere else.
When the app sends the browser elsewhere — most often a sign-in page, for a page that needs someone signed in — it says so, names where it ended up, and exits 1: the picture is of that page, not the one you asked for.
--no-compile photographs what is already compiled. --json answers with one object: { ok, path, page, landed, width, height, signedInAs, seed, error }.

The browser#

A picture needs a real browser, which The browser for screenshots installs once for every project. When it is missing and you are at a terminal, osy shot lists what it would download and asks — Enter is yes. Run by a program, it asks nothing and downloads nothing: it says to run osy browser install, and exits 2.

Examples#

osy shot /                                   # the front page, signed out, 1280 wide
osy shot /desk --as [email protected]         # as one of the app's accounts
osy shot /desk --as [email protected] --seed AnEditorAndAMember --width 390
osy shot /books --json                       # { "ok": true, "path": "…/osy-shots/shot-books-1280.png", … }