docs: update documentation and e2e tests
- Add configuration docs for database and rate limiting - Remove completed tasks from tracking list - Update testing requirements with new test patterns - Enhance web development docs with frontend guidelines - Expand page loading and ban records e2e test coverage
This commit is contained in:
135
Docs/Tasks.md
135
Docs/Tasks.md
@@ -1,136 +1,3 @@
|
||||
|
||||
## [E2E-1] Set up Robot Framework E2E test infrastructure
|
||||
|
||||
**Where found:**
|
||||
No E2E test suite exists in the repository. There are 87 backend pytest files and 78 frontend vitest files but zero integration/E2E tests that exercise the full running stack.
|
||||
|
||||
**Why this is needed:**
|
||||
Unit and component tests cannot catch regressions that span the full system: frontend → backend → fail2ban → database. A running-stack test suite is the only safety net for deployment-breaking changes.
|
||||
|
||||
**Goal:**
|
||||
Create the `e2e/` directory layout, install Robot Framework with the Browser library (Playwright-backed), configure shared keywords for startup/teardown and authentication, and add a `make e2e` target so the suite can be run with a single command.
|
||||
|
||||
**What to do:**
|
||||
1. Create `e2e/requirements.txt`:
|
||||
```
|
||||
robotframework>=7
|
||||
robotframework-browser>=18
|
||||
```
|
||||
2. Run `rfbrowser init` after install to download Playwright browsers.
|
||||
3. Create the directory layout:
|
||||
```
|
||||
e2e/
|
||||
├── requirements.txt
|
||||
├── resources/
|
||||
│ ├── common.resource # variables, shared setup/teardown
|
||||
│ └── auth.resource # Login As Admin keyword
|
||||
└── tests/
|
||||
├── 01_page_loading.robot
|
||||
├── 02_ban_records.robot
|
||||
├── 03_blocklist_import.robot
|
||||
└── 04_config_edit.robot
|
||||
```
|
||||
4. `common.resource` must define:
|
||||
- `${FRONTEND_URL}` = `http://localhost:5173`
|
||||
- `${BACKEND_URL}` = `http://localhost:8000`
|
||||
- Suite Setup: wait for `GET ${BACKEND_URL}/api/health` to return 200 before any test runs (poll with timeout 120 s).
|
||||
5. `auth.resource` must implement `Login As Admin`:
|
||||
- Check `GET /api/setup/status`; if setup is not done, complete the setup wizard first.
|
||||
- POST credentials to `/api/auth/login` or drive the login form at `/login`.
|
||||
- Store the resulting session for subsequent page navigations.
|
||||
6. Add to `Makefile`:
|
||||
```makefile
|
||||
e2e: up
|
||||
@echo "Waiting for stack to be healthy…"
|
||||
@sleep 60
|
||||
robot --outputdir e2e/results e2e/tests/
|
||||
```
|
||||
7. Add `e2e/results/` to `.gitignore`.
|
||||
|
||||
**Possible traps and issues:**
|
||||
- `BANGUI_SESSION_SECRET` env var is required; tests will fail with a startup error if it is not set. Document that `make e2e` requires the variable in the environment.
|
||||
- `make up` uses `podman-compose` or `podman compose` auto-detected at Makefile eval time. If neither is installed the `e2e` target silently fails.
|
||||
- The backend `start_period` in the healthcheck is 45 s; the frontend is 30 s on top of that. The 60 s sleep in the Makefile target may not be enough on a cold build — prefer polling `/api/health` until ready.
|
||||
- `rfbrowser init` must be re-run whenever the `robotframework-browser` version changes.
|
||||
- The Browser library uses Chromium headless by default. CI environments may need `--no-sandbox` flags passed via `New Browser chromium headless=true args=['--no-sandbox']`.
|
||||
|
||||
**Docs changes needed:**
|
||||
- Add an "E2E Testing" section to [Testing-Requirements.md](Testing-Requirements.md) describing how to run `make e2e`, required env vars, and how to view the HTML report in `e2e/results/`.
|
||||
- Add `e2e/results/` to the `.gitignore` list documented in [Backend-Development.md](Backend-Development.md).
|
||||
|
||||
**Doc references:**
|
||||
- [Testing-Requirements.md](Testing-Requirements.md)
|
||||
- [Backend-Development.md](Backend-Development.md)
|
||||
- [Deployment.md](Deployment.md) — for env var documentation
|
||||
- Robot Framework: https://robotframework.org/#getting-started
|
||||
- Browser library: https://robotframework-browser.org/
|
||||
|
||||
---
|
||||
|
||||
## [E2E-2] Page loading tests — all routes render without error
|
||||
|
||||
**Where found:**
|
||||
The frontend has eight distinct routes (`/setup`, `/login`, `/`, `/map`, `/jails`, `/jails/:name`, `/config`, `/history`, `/blocklists`). Each is wrapped in a `PageErrorBoundary`. There is no test that verifies all of them load successfully against a live stack.
|
||||
|
||||
**Why this is needed:**
|
||||
A broken import, a missing API field, or a bad runtime dependency can cause a page to show the error boundary fallback ("Something went wrong") instead of its content. Unit tests mock API responses, so they cannot catch this class of regression.
|
||||
|
||||
**Goal:**
|
||||
Every protected page loads, shows its primary content element, and does **not** show the `PageErrorBoundary` fallback when the stack is running correctly.
|
||||
|
||||
**What to do:**
|
||||
1. Create `e2e/tests/01_page_loading.robot`.
|
||||
2. Suite Setup: call `Login As Admin` from `auth.resource`.
|
||||
3. For each route, implement a test case with the pattern:
|
||||
```robot
|
||||
*** Test Cases ***
|
||||
Login Page Loads Without Error
|
||||
# Must run before Login As Admin — navigate while unauthenticated
|
||||
Go To ${FRONTEND_URL}/login
|
||||
Wait For Elements State css=form visible timeout=15s
|
||||
Get Text body not contains Something went wrong
|
||||
|
||||
Dashboard Loads Without Error
|
||||
Go To ${FRONTEND_URL}/
|
||||
Wait For Elements State css=main visible timeout=15s
|
||||
Get Text body not contains Something went wrong
|
||||
|
||||
Map Page Loads Without Error
|
||||
Go To ${FRONTEND_URL}/map
|
||||
Wait For Elements State css=canvas,svg visible timeout=15s
|
||||
Get Text body not contains Something went wrong
|
||||
```
|
||||
4. Cover all routes:
|
||||
- `/setup` — assert setup form OR redirect to `/login` (setup already done).
|
||||
- `/login` — assert login form visible.
|
||||
- `/` — assert dashboard stats/charts visible.
|
||||
- `/map` — assert SVG or canvas element visible.
|
||||
- `/jails` — assert a table or list visible.
|
||||
- `/jails/:name` — navigate to `/jails/manual-Jail`; assert jail detail heading visible.
|
||||
- `/config` — assert tab navigation visible.
|
||||
- `/history` — assert history table visible.
|
||||
- `/blocklists` — assert blocklists panel visible.
|
||||
5. Assert HTTP status for each page via `${response}= GET ${FRONTEND_URL}/<path>` and `Should Be Equal As Integers ${response.status} 200`.
|
||||
|
||||
**Possible traps and issues:**
|
||||
- The `/login` page test must run **before** `Login As Admin` is called, or the session cookie will cause an immediate redirect to `/`. Either make it the first test case with its own `[Setup] New Page` (no auth), or run it in a separate suite that has no Suite Setup.
|
||||
- The frontend is a SPA; `GET /map` at the Vite dev server always returns 200 with `index.html`. HTTP status checks here are not meaningful — focus on DOM assertions after client-side routing.
|
||||
- The `/jails/:name` test assumes `manual-Jail` exists. If fail2ban has not started or the jail is not active the page may render an empty or error state. Add a guard: check jail exists via `GET /api/jails` before navigating.
|
||||
- `PageErrorBoundary` renders per-page; the text "Something went wrong" must not be matched against the window title or other benign text. Scope the assertion to the `<main>` element.
|
||||
- Page elements have no `data-testid` attributes on the production components — only on test mocks. CSS selectors (`css=main`, `css=table`, `css=canvas`) are fragile. See [E2E-6] for the task to add `data-testid` attributes.
|
||||
- The Vite dev server takes ~30 s to compile on first load. The first navigation may time out; increase the default timeout to 30 s for the first test only.
|
||||
|
||||
**Docs changes needed:**
|
||||
- Document the expected selectors and page landmarks in [Web-Development.md](Web-Development.md) so frontend developers know which elements are load-tested.
|
||||
|
||||
**Doc references:**
|
||||
- [Web-Development.md](Web-Development.md)
|
||||
- [Web-Design.md](Web-Design.md)
|
||||
- [Testing-Requirements.md](Testing-Requirements.md)
|
||||
- `frontend/src/App.tsx` — canonical route definitions
|
||||
|
||||
---
|
||||
|
||||
## [E2E-3] Ban records appear in UI after simulated failed logins
|
||||
|
||||
**Where found:**
|
||||
@@ -360,4 +227,4 @@ Key interactive and landmark elements across all pages and the config form have
|
||||
- [Web-Development.md](Web-Development.md)
|
||||
- [Testing-Requirements.md](Testing-Requirements.md)
|
||||
- `frontend/src/components/ErrorBoundary.tsx`
|
||||
- `frontend/src/components/config/__tests__/AutoSaveIndicator.test.tsx`
|
||||
- `frontend/src/components/config/__tests__/AutoSaveIndicator.test.tsx`
|
||||
Reference in New Issue
Block a user