pikasTech-unidesk/docs/reference/e2e.md

UniDesk E2E Reference

UniDesk delivery is not complete until the public frontend, public provider ingress, internal core API, PostgreSQL database, local provider-gateway self-connection, and frontend Playwright flow pass one end-to-end check. The canonical automated command is bun scripts/cli.ts e2e run.

Required Preconditions

• config.json network.publicHost must be the externally reachable host name or IP of the main server, not 127.0.0.1, when validating browser access from outside the server.
• bunx playwright install chromium and bunx playwright install-deps chromium must have been run on hosts that execute browser E2E tests.
• The Docker stack must be running through bun scripts/cli.ts server start, and bun scripts/cli.ts server status must report healthy frontend, provider ingress, internal core, database, and provider-gateway containers.

Automated E2E Scope

bun scripts/cli.ts e2e run validates the following URLs and internal checks derived from config.json:

• Public exposure: Docker port summary must show only frontend and provider ingress host mappings; public core and public database probes must fail.
• Core API: docker exec unidesk-backend-core calls internal GET /api/overview, which must report dbReady: true and at least one online node.
• Provider self-connection: internal GET /api/nodes must contain main-server with status: online; internal GET /api/nodes/system-status must contain CPU/memory/disk samples; internal GET /api/nodes/docker-status must contain a Docker snapshot for main-server; public provider ingress /health must return ok.
• Provider remote control: internal /api/dispatch must successfully complete a real provider.upgrade task in mode: "plan" so the upgrade path is validated without recreating the running gateway during E2E.
• Database: the command writes an unidesk_e2e_markers row through docker exec unidesk-database psql and confirms provider state is stored in PostgreSQL.
• Frontend: Playwright must open the public frontend URL derived from network.publicHost, not localhost or a Docker-internal URL; it logs in with the configured account, waits for 核心在线, asserts that main-server and Main Server Provider are visible, clicks 查看原始JSON to verify Provider data from the frontend, confirms no raw JSON is visible before that click, opens task history to verify duration and failure diagnostics, opens resource nodes 资源监控 to verify CPU/Memory/Disk curves and provider upgrade precheck dispatch, then opens Docker 状态 and verifies the Docker Desktop-style container view including the database named volume unidesk_pgdata_10gb.

Frontend JSON Rule

The frontend must render JSON data into React controls by default. Raw JSON is allowed only after an explicit 查看原始JSON user action, and E2E must fail if the initial page exposes raw JSON text or a raw JSON block.

Public Boundary Rule

The public frontend URL and provider ingress URL are the only public network interfaces. backend-core REST API and PostgreSQL database are Docker-internal only; E2E must prove the historical public core/database ports are not reachable.

Database Persistence Rule

The PostgreSQL data volume is the named Docker volume unidesk_pgdata_10gb. CLI server control commands must never use docker compose down -v, docker volume rm, or any equivalent data-volume removal. To validate persistence, insert a marker row into unidesk_e2e_markers, run bun scripts/cli.ts server start or a full stop/start cycle, and verify the marker row still exists.

Delivery Gate

Before claiming delivery, run these checks and keep their JSON output or screenshot path available for review:

1. bun scripts/cli.ts check
2. bun scripts/cli.ts server start, then bun scripts/cli.ts job status latest until succeeded
3. bun scripts/cli.ts server status
4. bun scripts/cli.ts e2e run
5. a database persistence marker check across at least one CLI-controlled restart