Playwright Frontend→Backend E2E Design

Date: 2026-05-10
Scope: True browser-driven end-to-end testing (frontend UI → backend API → DB side effects) for all 12 critical user journeys.

1) Goal

Establish a deterministic Playwright E2E suite that validates real user behavior through the frontend while asserting backend-observable outcomes for all 12 critical journeys.

Success means:

  • Browser-driven tests exercise actual pages/components, not direct API calls.
  • Backend side effects are verified where critical (auth session, RBAC deny/allow, organization isolation, telemetry persistence, automation executions).
  • All 12 journeys run locally against dedicated test infrastructure.
  • Suite is stable and non-order-dependent.

2) Non-goals (for this phase)

  • CI integration in phase 1 (local-first only).
  • Visual regression/screenshot baselining.
  • Mobile app E2E.
  • Replacing existing backend API E2E; this suite complements it.

3) Chosen approach

Selected approach: Single Playwright project, serial journey specs, shared setup.

Why:

  • Fastest path to full coverage with minimal configuration complexity.
  • Easier debugging and stabilization in first rollout.
  • Supports future split into multi-project parallel lanes if runtime becomes high.

Tradeoff accepted:

  • Longer runtime than domain-sharded projects.

4) Test environment architecture (local-first)

Runtime topology

  • Frontend: Vite dev server (local).
  • Backend: NestJS app (local) configured for test mode.
  • Database: dedicated local test database (not shared dev DB).
  • Optional local dependencies: Redis/MQTT/MinIO via existing docker compose profiles where required by journeys.

Environment isolation

  • Separate env file for E2E local runs (frontend + backend).
  • Backend points to dedicated DB schema/database (e.g., hmpiot_e2e_local).
  • No re-use of normal dev DB.

Deterministic reset strategy

  • Reset DB to known baseline before each spec file.
  • Seed only required fixtures for that journey group.
  • Use stable seed identifiers/namespaces to prevent cross-spec contamination.

5) Authentication/session strategy

Chosen strategy: stored authenticated state per role/org.

Flow

  1. Playwright globalSetup performs real UI login for each required persona.
  2. Save storage state files by persona (role + org context).
  3. Journey specs load matching storage state instead of logging in repeatedly.

Persona matrix (minimum)

  • Super/Admin role (org-level management).
  • Staff/Viewer role (restricted RBAC behavior).
  • Org A user.
  • Org B user.

Invalidation handling

  • If auth bootstrapping fails, fail early in setup with clear error.
  • Regenerate storageState on each run to avoid stale tokens.

6) Coverage model for 12 critical journeys

Each journey includes at least 1 happy path + 1 negative path.

  1. Auth basic: register → login → profile/me → refresh/session continuity → logout.
  2. RBAC enforcement: allowed role can perform action; restricted role gets deny UX + backend rejection.
  3. Multi-tenant isolation: org A cannot view/edit org B resources from UI flows.
  4. Error contract UX: UI behavior for 401/403/404/422 mapped to correct user-facing handling and backend status.
  5. Organization onboarding: create org + first user + default access view.
  6. Farm management: create/update/list area/pond with org-scoped filtering/pagination reflected in UI.
  7. Device lifecycle: register device → assign to area/pond → activate/deactivate transitions.
  8. Telemetry valid payload flow: ingest path reflected in latest/range UI views.
  9. Telemetry invalid payload flow: reject invalid input; verify no invalid record appears in UI history.
  10. Dashboard aggregation: aggregate cards/charts update correctly after telemetry setup.
  11. Automation rule flow: create rule, trigger threshold condition, verify action/execution evidence.
  12. Release smoke journey: minimal high-signal happy-path path across auth + core operations.

7) Test suite structure

Target structure:

  • frontend/e2e/
    • config/
      • playwright config and projects (single project now)
    • setup/
      • global setup (auth state generation)
      • DB reset/seed hooks
    • fixtures/
      • persona fixtures
      • test data builders (org/farm/device/telemetry/automation)
    • pages/
      • page object abstractions for stable selectors and reusable actions
    • journeys/
      • one spec per journey group (auth, rbac, tenant, farm, devices, telemetry, dashboard, automation, smoke)
    • utils/
      • wait/retry helpers only for eventual consistency boundaries

Selector strategy

  • Prefer data-testid for brittle UI actions.
  • Avoid selectors tied to style/classnames.
  • Add missing test IDs to frontend components where needed.

8) Data setup and verification boundaries

Setup source of truth

  • UI-driven setup for user-observable workflows.
  • Backend task hooks/seeding only for prerequisite bootstrapping where UI setup is too expensive/repetitive.

Verification levels

  • Primary: browser assertions (visible state, navigation, table/chart content, permission-driven visibility).
  • Secondary (critical flows only): backend-side verification via controlled helpers (e.g., record exists/does not exist) to confirm side effects where UI could mask issues.

Isolation assertions

  • Explicit org A vs org B checks in UI lists/details and forbidden operations.
  • Assertions ensure denied actions do not mutate state.

9) Reliability design

  • Retry only for known eventual-consistency zones (e.g., telemetry propagation), not blanket retries.
  • Time control strategy: bounded waits with explicit conditions, no arbitrary sleeps.
  • Tests must be order-independent.
  • Fail fast in setup if environment/preconditions are invalid.

10) Smoke vs full suite (local phase)

Smoke (fast local confidence)

Contains critical cross-cutting journeys:

  • Auth happy path
  • RBAC deny path
  • Tenant isolation deny path
  • Basic telemetry ingest + latest view
  • Minimal dashboard check

Target runtime: <= 7 minutes.

Full suite

  • All 12 journeys + happy/negative coverage.
  • Local run for release-hardening and deep regression checks.

11) Command contract (local)

Add frontend scripts for:

  • Install Playwright browsers/deps.
  • Run smoke E2E.
  • Run full E2E.
  • Open Playwright UI/debug mode.

The exact script names will be standardized during implementation, but they must support:

  • Single command smoke run.
  • Single command full run.
  • Headed debug run.

12) CI strategy (deferred but designed now)

Planned next phase after local stabilization:

  • PR: smoke suite.
  • Nightly or labeled critical PR: full suite.
  • Artifacts: traces/videos/screenshots on failure.
  • JUnit-compatible reporting for pipeline visibility.

This design keeps folder layout and command interface compatible with that later rollout.

13) Risks and mitigations

  1. Flaky telemetry/dashboard waits
    Mitigation: explicit polling on semantic conditions; minimal bounded retries only where asynchronous processing is expected.

  2. Auth state staleness
    Mitigation: regenerate storageState each run in global setup.

  3. DB contamination
    Mitigation: dedicated local test DB + deterministic reset before each spec file.

  4. Runtime growth from all 12 journeys
    Mitigation: maintain lean page objects/fixtures, avoid redundant setup, keep smoke subset strict.

  5. Selector fragility
    Mitigation: enforce data-testid for key interactive components.

14) Definition of done

  • All 12 journeys implemented with happy + negative tests.
  • Dedicated local test DB used exclusively for E2E runs.
  • Stored auth states generated per role/org in setup.
  • Smoke and full suites runnable via frontend scripts.
  • Smoke runtime <= 7 minutes locally.
  • Full suite stable in repeated local runs (at least 3 consecutive clean runs for smoke; at least 1 full clean run).
  • Failure diagnostics available (trace/screenshot/video as configured).

15) Implementation sequencing

  1. Scaffold Playwright and config in frontend/e2e.
  2. Build global auth setup + persona storageState.
  3. Implement DB reset/seed hooks for dedicated local DB.
  4. Add page objects + stable selectors (data-testid) for critical screens.
  5. Implement journeys 1–4 (security/isolation first).
  6. Implement journeys 5–9 (core business + telemetry).
  7. Implement journeys 10–12 (dashboard/automation/smoke).
  8. Add smoke/full scripts and local debug workflow.
  9. Stabilize and document run/debug steps.

16) Out-of-scope follow-up backlog

  • CI workflow integration and artifact publishing.
  • Parallel domain projects for runtime optimization.
  • Visual regression snapshots.
  • Cross-browser matrix expansion beyond primary browser.