|
| 1 | +# e2e-screenshots |
| 2 | + |
| 3 | +## Purpose |
| 4 | + |
| 5 | +Capture canonical screenshots of the mailbrus SPA for documentation and marketing purposes. Screenshots are generated on-demand via a dedicated Playwright project and committed to the repository as immutable assets. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## Requirements |
| 10 | + |
| 11 | +### Requirement: Dedicated screenshot scenario file |
| 12 | + |
| 13 | +The repository SHALL contain a dedicated Playwright spec file (`e2e/specs/screenshots.spec.ts`) whose sole responsibility is staging the SPA into canonical views and capturing screenshots. The file MUST NOT contain functional assertions unrelated to capture, and MUST NOT be imported or referenced from functional spec files. |
| 14 | + |
| 15 | +#### Scenario: Screenshot spec exists at the expected path |
| 16 | + |
| 17 | +- **WHEN** the repository is inspected |
| 18 | +- **THEN** `e2e/specs/screenshots.spec.ts` exists |
| 19 | +- **AND** its tests' final action for each captured view is `page.screenshot(...)` writing into `docs/screenshots/` |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +### Requirement: Canonical view set |
| 24 | + |
| 25 | +The screenshot scenario SHALL capture exactly the following five canonical views, each written to a fixed file name under `docs/screenshots/`: |
| 26 | + |
| 27 | +| File | View | |
| 28 | +| --- | --- | |
| 29 | +| `message-list.png` | Populated message list, no overlay | |
| 30 | +| `reader.png` | A representative message open in the reader | |
| 31 | +| `accounts.png` | Account list / picker | |
| 32 | +| `compose.png` | Compose view with realistic draft content | |
| 33 | +| `about-over-list.png` | About dialog overlaid on the message list | |
| 34 | + |
| 35 | +#### Scenario: All five PNGs are produced |
| 36 | + |
| 37 | +- **WHEN** `deno task screenshots` completes successfully |
| 38 | +- **THEN** all five files listed above exist under `docs/screenshots/` |
| 39 | +- **AND** no other PNG files are produced under `docs/screenshots/` by the task |
| 40 | + |
| 41 | +#### Scenario: About shot uses the real About dialog |
| 42 | + |
| 43 | +- **WHEN** `about-over-list.png` is captured |
| 44 | +- **THEN** the visible About surface is rendered by the real `About.svelte` component triggered via its production entry point (keyboard shortcut, command palette, or menu) |
| 45 | +- **AND** no test-only overlay or mock About panel is injected |
| 46 | + |
| 47 | +--- |
| 48 | + |
| 49 | +### Requirement: On-demand-only execution |
| 50 | + |
| 51 | +The screenshot scenario SHALL run only when explicitly requested via the dedicated task. It MUST NOT execute as part of the default `deno task test:e2e` / `deno task e2e:headless` run, MUST NOT execute in any CI workflow's default test step, and MUST NOT be added to a pre-commit or pre-push hook. |
| 52 | + |
| 53 | +#### Scenario: Default e2e run excludes screenshot scenario |
| 54 | + |
| 55 | +- **WHEN** `deno task test:e2e` is invoked |
| 56 | +- **THEN** `e2e/specs/screenshots.spec.ts` is not executed |
| 57 | +- **AND** no files under `docs/screenshots/` are written or modified by the run |
| 58 | + |
| 59 | +#### Scenario: CI does not run the screenshot scenario by default |
| 60 | + |
| 61 | +- **WHEN** the project's CI workflows are inspected |
| 62 | +- **THEN** no workflow step invokes the screenshot project, task, or spec file as part of its default execution path |
| 63 | +- **AND** if any workflow does invoke it, that invocation is gated behind an explicit opt-in (manual dispatch, dedicated workflow, or label-triggered job) |
| 64 | + |
| 65 | +#### Scenario: Screenshot task runs the scenario |
| 66 | + |
| 67 | +- **WHEN** `deno task screenshots` is invoked |
| 68 | +- **THEN** Playwright executes the dedicated `screenshots` project containing only `e2e/specs/screenshots.spec.ts` |
| 69 | +- **AND** the process exit code reflects success or failure of that scenario |
| 70 | + |
| 71 | +--- |
| 72 | + |
| 73 | +### Requirement: Deterministic capture environment |
| 74 | + |
| 75 | +The screenshot scenario SHALL fix the capture environment so re-runs against unchanged UI code produce stable output. Fixed parameters MUST include viewport dimensions, color scheme, locale, and device scale factor. Animations and caret blink SHALL be suppressed before capture. |
| 76 | + |
| 77 | +#### Scenario: Environment is pinned in config |
| 78 | + |
| 79 | +- **WHEN** the screenshot Playwright project's configuration is inspected |
| 80 | +- **THEN** it specifies an explicit viewport width and height, a fixed `colorScheme`, a fixed `locale`, and a fixed `deviceScaleFactor` |
| 81 | + |
| 82 | +#### Scenario: Animations are suppressed before capture |
| 83 | + |
| 84 | +- **WHEN** any of the five views is captured |
| 85 | +- **THEN** CSS transitions, animations, and caret blink are disabled on the page before `page.screenshot(...)` is called |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +### Requirement: Committed output under docs/screenshots/ |
| 90 | + |
| 91 | +The five PNGs SHALL be committed to the repository under `docs/screenshots/`. They MUST NOT be listed in `.gitignore`. The output directory MUST be `docs/screenshots/` (not `e2e/screenshots/`, not `e2e/test-results/`). |
| 92 | + |
| 93 | +#### Scenario: Output directory is tracked |
| 94 | + |
| 95 | +- **WHEN** the repository is inspected |
| 96 | +- **THEN** `docs/screenshots/` exists and contains the five canonical PNGs as tracked files |
| 97 | +- **AND** neither `docs/screenshots/` nor `docs/screenshots/*.png` appears in any `.gitignore` |
| 98 | + |
| 99 | +--- |
| 100 | + |
| 101 | +### Requirement: Reuse of existing E2E harness |
| 102 | + |
| 103 | +The screenshot scenario SHALL obtain its server, cloned maildir, and page objects through the existing harness fixture (`e2e/harness/fixtures.ts`). It MUST NOT clone fixtures, spawn `mailbrus-server`, or hard-code DOM selectors inline; selectors SHALL come from existing page objects (`AccountsPage`, `MailboxPage`, `MessagePage`) or new page-object additions where genuinely needed. |
| 104 | + |
| 105 | +#### Scenario: Scenario delegates to harness and page objects |
| 106 | + |
| 107 | +- **WHEN** `e2e/specs/screenshots.spec.ts` is inspected |
| 108 | +- **THEN** it imports its `test` fixture from the harness rather than `@playwright/test` directly |
| 109 | +- **AND** it interacts with the SPA via page objects, not raw `page.locator(...)` selectors duplicated from page objects |
| 110 | + |
| 111 | +--- |
| 112 | + |
| 113 | +### Requirement: Manifest-driven content for list and reader shots |
| 114 | + |
| 115 | +For the `message-list.png` and `reader.png` views, the content shown SHALL be sourced from the typed fixture manifest in `e2e/fixtures/manifest.ts` (specific account / folder / message references), so corpus changes propagate to the screenshots through the manifest rather than through scattered literals. |
| 116 | + |
| 117 | +#### Scenario: List and reader shots reference manifest entries |
| 118 | + |
| 119 | +- **WHEN** the screenshot scenario stages the message-list and reader views |
| 120 | +- **THEN** the account, folder, and message it navigates to are obtained from named exports of the manifest, not from inline string literals |
0 commit comments