From ffd05e899328db66bfb57bbf195710e504b372f5 Mon Sep 17 00:00:00 2001
From: arsam <me@asabbagh.com>
Date: Fri, 18 Sep 2026 23:11:34 +0330
Subject: [PATCH] Import documentation: backend/tests/e2e/README.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
---
 backend/tests/e2e/README.md | 44 +++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 backend/tests/e2e/README.md

diff --git a/backend/tests/e2e/README.md b/backend/tests/e2e/README.md
new file mode 100644
index 0000000..ba87ddb
--- /dev/null
+++ b/backend/tests/e2e/README.md
@@ -0,0 +1,44 @@
+# CoaxysPanel REST API E2E Test Suite
+
+This directory contains the comprehensive, opaque-box E2E test suite for the CoaxysPanel REST API.
+
+The test suite validates:
+- **Tier 1 (Happy Paths)**: Basic CRUD on Auth, Websites, Domains, DNS, and general JSON API envelope compliance.
+- **Tier 2 (Boundaries & Negative States)**: Validation failures, conflicts (409), rate limiting, not found (404), method checks (405), server errors (500), and SQL injection safety.
+- **Tier 3 (Cross-Feature logic)**: Session expiration vs CRUD access, role-based scope comparison, and domain deletion mapping effects.
+- **Tier 4 (Real-World Workload)**: Complete lifecycle scenarios (login -> domain create -> website create -> configure -> clean up -> logout).
+
+## Configuration
+
+The test suite communicates with the backend via HTTP and is configured using environment variables.
+
+*   `API_URL`: The base URL of the CoaxysPanel REST API (defaults to `http://localhost:3001`).
+*   `DEBUG_E2E`: Set to `true` to enable verbose request and response logging for easier debugging.
+
+### Automatic Fallback Mock Server
+
+If no active server is detected at `API_URL`, or if the port is occupied by the Nova Telegram bot service, the global setup will **automatically start a local mock backend server** on port `3009` and override `API_URL` to point to it. This allows the E2E tests to be completely self-contained and runnable out of the box.
+
+## Commands
+
+### Typecheck Compilation
+
+Verify that the TypeScript test files compile cleanly:
+
+```bash
+npx tsc --noEmit
+```
+
+### Running the E2E Test Suite
+
+To run all E2E specs using Vitest:
+
+```bash
+npx vitest run --config backend/tests/e2e/vitest.config.ts
+```
+
+To run the E2E tests with debug request/response logging:
+
+```bash
+DEBUG_E2E=true npx vitest run --config backend/tests/e2e/vitest.config.ts
+```