HarborForge.Test/README.md

HarborForge.Test

Integration / end-to-end test harness for the HarborForge platform. It spins up the full stack (MySQL, AbstractWizard, HarborForge.Backend, HarborForge.Frontend) in Docker and runs the backend and frontend test suites against it.

Part of the HarborForge platform.

Layout

HarborForge.Test/
├── run-test.sh                       # Quick frontend E2E run (no rebuild)
├── run-test-frontend.sh              # Full frontend E2E run (rebuild + optional port expose)
├── cleanup.sh                        # Tear down containers / wizard config volume
├── docker-compose-frontend.yml       # Internal-only test stack
├── docker-compose-frontend-expose.yml# Same stack with ports bound to 127.0.0.1
├── .env.TEST                         # Default service ports
├── HarborForge.Backend.Test/         # git submodule — backend pytest suite
└── HarborForge.Frontend.Test/        # git submodule — frontend Playwright suite

The two test suites are git submodules (see .gitmodules). After cloning, initialize them:

git submodule update --init --recursive

What It Tests

Backend — HarborForge.Backend.Test (pytest)

A standalone pytest suite that imports the backend code from ../HarborForge.Backend/ via tests/conftest.py and runs against an in-memory SQLite database for fast, isolated unit/integration tests. Configured by pyproject.toml (testpaths = ["tests"], verbose, short tracebacks).

Coverage spans auth/JWT, users, projects, milestones, tasks, comments, roles/permissions, the milestone and task state machines (test_milestone_actions.py, test_task_transitions.py), proposals (test_propose.py), the monitor endpoint, and miscellaneous endpoints (notifications, activity log, API keys, dashboard).

Run it standalone:

python3 -m venv venv
source venv/bin/activate
pip install -r HarborForge.Backend.Test/requirements.txt
cd HarborForge.Backend.Test && pytest          # or: pytest -v, pytest tests/test_auth.py

See HarborForge.Backend.Test/README.md for the full test breakdown.

Frontend — HarborForge.Frontend.Test (Playwright)

A Playwright (@playwright/test) end-to-end suite that drives the running frontend through a browser. Specs in tests/ cover the setup wizard, projects editor, milestones, tasks, role editor and proposals (wizard.spec.ts, project-editor.spec.ts, milestone.spec.ts, task.spec.ts, role-editor.spec.ts, propose.spec.ts, proposal-essential.spec.ts). Its Docker image runs a helper proxy (server/proxy.mjs) alongside npx playwright test.

Note: the frontend's own Vitest unit tests live in the HarborForge.Frontend repo; this harness exercises the frontend through Playwright against the full Docker stack.

Docker Test Stack

docker-compose-frontend.yml defines five services on a private test-network bridge — mysql (MySQL 8, tmpfs storage), wizard (AbstractWizard), backend (HarborForge.Backend), frontend (HarborForge.Frontend), and test (the Playwright runner image built from HarborForge.Frontend.Test/). Service ports default from .env.TEST (WIZARD_PORT=8080, MYSQL_PORT=3306, BACKEND_PORT=8000, FRONTEND_PORT=3000).

• docker-compose-frontend.yml — services are reachable only on the internal network (wizard alone is bound to 127.0.0.1).
• docker-compose-frontend-expose.yml — same stack, but mysql, wizard, backend and frontend ports are also bound to 127.0.0.1 for debugging.

Running the Tests

Quick run (no rebuild)

./run-test.sh

Brings the stack up from docker-compose-frontend.yml, waits (up to ~60s) for the frontend to answer HTTP 200, runs the test service once, then tears everything down with down -v.

Full run (rebuild, optional port exposure)

./run-test-frontend.sh                      # rebuild all images, run, auto-cleanup
./run-test-frontend.sh --expose-port on     # use the *-expose.yml file, keep services up
./run-test-frontend.sh --expose-port off    # default: cleanup after the run

It loads .env.TEST, rebuilds the frontend (with build arg VITE_API_BASE=http://backend:8000), backend and test-runner images with --no-cache, starts the stack, waits for the frontend, then runs the test service with WORKERS=1. With --expose-port on it uses docker-compose-frontend-expose.yml and leaves the stack running for inspection.

Cleanup

./cleanup.sh

Stops and removes containers/networks (keeps images) and drops the harborforgetest_wizard_config volume. The run scripts also call docker compose ... down -v themselves on completion (except when port exposure is on).

CI Notes

• Both run scripts use set -e and propagate the test container's exit code, so they are CI-friendly: a non-zero TEST_EXIT_CODE fails the job.
• run-test-frontend.sh suppresses build/startup output unless a step fails, in which case it prints the tail of that step's log.
• Builds use --no-cache and remove prior harborforge-test-*:dev images to guarantee a clean stack each run; MySQL uses tmpfs so no state persists between runs.
• Ensure submodules are initialized (git submodule update --init --recursive) before invoking the scripts in CI.