pikasTech-unidesk/docs/reference/e2e.md

UniDesk E2E Reference

UniDesk delivery is not complete until the public frontend, public core API, PostgreSQL database, and local provider-gateway self-connection 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 core, frontend, database, and provider-gateway containers.

Automated E2E Scope

bun scripts/cli.ts e2e run validates the following through the public URLs derived from config.json:

• Core API: GET /api/overview reports dbReady: true and at least one online node.
• Provider self-connection: GET /api/nodes contains main-server with status: online.
• Database: the command writes an unidesk_e2e_markers row through docker exec unidesk-database psql, confirms provider state is stored in PostgreSQL, and probes the public PostgreSQL port with pg_isready.
• Frontend: Playwright opens the public frontend URL, waits for 核心在线, asserts that main-server and Main Server Provider are visible, checks the metrics panel, and captures a screenshot under .state/e2e/.

Public Frontend Rule

The frontend must not inject 127.0.0.1 as the browser-facing core API URL for public deployments. If a loopback URL is accidentally injected and the page itself is opened from a non-loopback host, public/app.js rewrites the API host to window.location.hostname as a safety net; however the correct fix is still to set network.publicHost correctly in config.json and restart the stack.

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