docs/screenshots/README.md

Rama main · réplica de lectura del repositorio original.

# Dashboard Screenshots

This directory contains automatically generated screenshots of the Actual-sync dashboard for documentation purposes.

## Automated Screenshot Generation

Screenshots are generated by `scripts/generateDashboardScreenshots.js`, driven by the manifest at
`tests/e2e/screenshots.json` and the same fixture harness the browser e2e specs use (`tests/e2e/fixtures/`).
There is no service to start first: each manifest entry gets its own real `HealthCheckService` and
`SyncHistoryService`, seeded with deterministic data and viewed through a frozen clock, so the output does
not depend on wall-clock time or on anything actually syncing.

### Prerequisites

Just the dev dependencies:

```bash
npm install
```

### Generate Screenshots

```bash
npm run screenshots
```

This creates the 15 screenshots listed in `tests/e2e/screenshots.json`:

- `dashboard-overview-healthy.png` - Overview tab, three servers all syncing cleanly, 2-column layout
- `dashboard-overview-degraded.png` - Overview tab, degraded system with failing and partial servers
- `dashboard-overview-multi-server.png` - Overview tab, six servers with mixed encryption badges
- `dashboard-analytics.png` - Analytics tab, all-time statistics and charts for a healthy system
- `dashboard-analytics-degraded.png` - Analytics tab, two days of history with a visibly lower success rate
- `dashboard-history.png` - History tab, recent syncs table
- `dashboard-history-errors.png` - History tab, a longer run with a known number of failure rows
- `dashboard-settings.png` - Settings tab, scrolled to date format preferences
- `dashboard-settings-audit.png` - Settings tab, the Configuration changes list with three recorded changes
- `dashboard-settings-danger-zone.png` - Settings tab, Danger Zone reset controls and orphaned server cleanup
- `dashboard-hero.png` - Full dashboard hero shot, six servers, used for the README gallery
- `dashboard-accounts.png` - Accounts card, syncable, manual and closed accounts across three servers
- `dashboard-payments.png` - Payments tab, missing-payment alerts per server
- `dashboard-payments-empty.png` - Payments tab, a server with alerts not configured
- `dashboard-payments-muted.png` - Payments tab, an alert muted until a date with its reason beside the real state pill

### How It Works

For each manifest entry, the script:
1. Starts a fixture server for the entry's `state` (a module under `tests/e2e/fixtures/states/`)
2. Opens a page configured the same way the e2e specs are (fixed viewport, UTC, frozen clock, locked-down
   network - see `tests/e2e/fixtures/browser.js`)
3. Navigates to `/dashboard` and, if the entry names a `tab`, clicks it
4. If the entry has `scrollToText`, scrolls the `.card` containing that text into view; otherwise scrolls
   to the top
5. Takes a screenshot, full-page unless the entry sets `"fullPage": false`

Only the sync callback, server list, cron schedules and notification service are stubbed. Every screen is
rendered from the dashboard's real routes and real SQLite-backed history, not from mocked `fetch` or
`WebSocket` responses.

### Adding or Changing a Screenshot

Edit `tests/e2e/screenshots.json`, not the generator script:

```json
{
  "file": "dashboard-<new-scene>.png",
  "state": "healthy",
  "tab": "overview",
  "description": "What this shows and why"
}
```

`state` must be a module name under `tests/e2e/fixtures/states/` (add a new one if none of the existing
states fit). `scrollToText` requires `"fullPage": false` - a full-page screenshot resizes the viewport to
the entire content height, so a scroll position taken beforehand has no visible effect at all; the generator
fails fast if the two are combined by mistake.

After changing the manifest, update the list above, the README.md gallery, and any other doc that names the
new file (`src/__tests__/screenshotManifest.test.js` checks that every screenshot referenced from a doc is
in the manifest, and vice versa, so a mismatch fails `npm test`).

### Technical Details

- **Browser**: Puppeteer (headless Chrome), launched once and reused across entries
- **Viewport**: 1920x1080
- **Format**: PNG
- **Clock**: frozen at the fixture's `FIXTURE_NOW` (see `tests/e2e/fixtures/index.js`)
- **Network**: locked down to the fixture server plus a pinned local copy of Chart.js; nothing reaches the
  real network

### Troubleshooting

**A screenshot fails to render or looks empty:**
- Run the matching e2e spec instead (`npm run test:e2e`) - specs cover the same pages and fail with a
  console log and screenshot under `tests/e2e/artifacts/` instead of a silent blank capture.

**Screenshots look stale after a dashboard change:**
- Re-run `npm run screenshots`; there is nothing else to restart first.

## Maintenance

These screenshots are part of the documentation and should be regenerated whenever the dashboard UI
changes. Regenerating is deterministic (same fixture data and frozen clock every time), so a diff in a
regenerated screenshot reflects an actual UI change, not test flakiness.