# Photographing a page

> 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.

<!-- id: local-photographing-a-page · area: local · stability: preview · html: https://osysharp.com/reference/local/photographing-a-page/ -->

## Summary        {#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      {#signature}

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

## Description    {#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](https://osysharp.com/reference/testing/dev-seeds/)).
- **`--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   {#browser}

A picture needs a real browser, which [The browser for screenshots](https://osysharp.com/reference/local/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       {#examples}

```console
osy shot /                                   # the front page, signed out, 1280 wide
osy shot /desk --as editor@auth.test         # as one of the app's accounts
osy shot /desk --as editor@auth.test --seed AnEditorAndAMember --width 390
osy shot /books --json                       # { "ok": true, "path": "…/osy-shots/shot-books-1280.png", … }
```

## See also       {#see-also}

[The browser for screenshots](https://osysharp.com/reference/local/the-browser-for-screenshots/) — the browser it draws with, installed once.

[Layout assertions — is it actually usable on screen?](https://osysharp.com/reference/testing/ui-layout/) — `osy test --pixels`: every page your tests visit, photographed, with layout assertions.

[Launching your app](https://osysharp.com/reference/local/launching-your-app/) — `osy launch --as <login>` opens the same page for you to click through.