iron/docs/ui-playwright-standard.md

Iron UI Playwright Standard

Last updated: 2026-04-14

1. Purpose

All future Iron Web UI changes must be validated against a real running service, using Python Playwright flows and screenshot review.

This is the default UI modification standard for the project.

2. Required Workflow For Any UI Change

Before considering a UI change complete:

1. build the frontend assets
2. start the real local service
3. run the Python Playwright regression flow
4. generate screenshots into output/playwright/
5. review screenshots for layout, spacing, responsiveness, and interaction states
6. fix issues found in the screenshots or browser flow
7. rerun the Playwright flow after the fixes

Do not treat UI work as complete based only on code review or unit tests.

3. Required Validation Levels

Every meaningful UI change should validate:

• login flow
• files workspace render
• primary file operation flow affected by the change
• upload flow if the change touches file workflows
• screenshots of the affected page states

4. Tooling Standard

Use:

• Python Playwright code for repeatable regression checks
• a real locally running Iron service
• screenshot artifacts for visual inspection

Preferred command:

./.venv/bin/python scripts/ui_playwright_smoke.py

Pytest entrypoint for CI or full local regression:

./.venv/bin/python -m pytest tests/e2e/test_web_ui_playwright.py

Artifacts must be written to:

output/playwright/

5. Screenshot Review Checklist

Every screenshot review should check:

• overall balance of the layout
• spacing consistency
• text truncation or wrapping problems
• button grouping and hierarchy
• panel heights and overflow behavior
• empty-state clarity
• table/list readability
• dialog layout and action placement
• mobile or narrow-width resilience when the changed surface is responsive

6. Interaction Review Checklist

Every flow review should check:

• click targets are obvious
• primary actions are easy to find
• selection state is clear
• navigation state is preserved where expected
• success feedback is visible
• error feedback is actionable
• dialogs do not rely on browser-native prompts
• repetitive tasks do not require unnecessary clicks

7. Regression Scope For Iron

Current baseline regression should cover:

• login
• files page
• create folder
• upload from the files page
• authenticated file download
• authenticated inline image preview
• no failing /api browser requests during the flow
• files search/filter visibility
• uploads page render

As new UI capabilities are added, extend the Python Playwright script to cover them.

8. Expected Outputs

Each run should produce:

• pass/fail console output
• screenshots
• clear error exit code on failure

Recommended screenshot set:

• login.png
• files-empty-or-initial.png
• files-after-create-folder.png
• files-after-upload.png
• uploads-page.png

9. Standard For Future UI Optimization

For future layout or interaction polish:

• first reproduce the current state in Playwright
• capture before screenshots
• make a focused UI change
• capture after screenshots
• compare the changed states visually
• keep the regression script updated if the flow meaningfully changes

10. Non-Negotiable Rule

No future UI optimization should be merged or considered complete without:

• a real service run
• Python Playwright flow validation
• screenshot review