Devin
174cbfde04
Closes the 'e2e tests only hit production; no local full-stack harness'
finding from the review. The existing e2e suite
(scripts/e2e-explorer-frontend.spec.ts) runs against explorer.d-bis.org
and so can't validate a PR before it merges -- it's a production canary,
not a pre-merge gate.
This PR adds a parallel harness that stands the entire stack up locally
(postgres + elasticsearch + redis via docker-compose, backend API, and
a production build of the frontend) and runs a Playwright smoke spec
against it. It is wired into Make and into a dedicated CI workflow.
Changes:
scripts/e2e-full.sh (new, chmod +x):
- docker compose -p explorer-e2e up -d postgres elasticsearch redis.
- Waits for postgres readiness (pg_isready loop).
- Runs database/migrations/migrate.go so schema + seeds including
the new 0016_jwt_revocations table from PR #8 are applied.
- Starts 'go run ./backend/api/rest' on :8080; waits for /healthz.
- Builds + starts 'npm run start' on :3000; waits for a 200.
- npx playwright install --with-deps chromium; runs the full-stack
spec; tears down docker and kills the backend+frontend processes
via an EXIT trap. E2E_KEEP_STACK=1 bypasses teardown for
interactive debugging.
- Generates an ephemeral JWT_SECRET per run so stale tokens don't
bleed across runs (and the fail-fast check from PR #3 passes).
- Provides a dev-safe CSP_HEADER default so PR #3's hardened
production CSP check doesn't reject localhost connections.
scripts/e2e-full-stack.spec.ts (new):
- Playwright spec that exercises public routes + a couple of
backend endpoints. Takes a full-page screenshot of each route
into test-results/screenshots/<route>.png so reviewers can
eyeball the render from CI artefacts.
- Covers: /healthz, /, /blocks, /transactions, /addresses, /tokens,
/pools, /search, /wallet, /routes, /api/v1/access/products (YAML
catalogue from PR #7), /api/v1/auth/nonce (SIWE kickoff).
- Sticks to Track-1 (no wallet auth needed) so it can run in CI
without provisioning a test wallet.
playwright.config.ts:
- Broadened testMatch from a single filename to /e2e-.*\.spec\.ts/
so the new spec is picked up alongside the existing production
canary spec. fullyParallel, worker, timeout, reporter, and
project configuration unchanged.
Makefile:
- New 'e2e-full' target -> ./scripts/e2e-full.sh. Listed in 'help'.
- test-e2e (production canary) left untouched.
.github/workflows/e2e-full.yml (new):
- Dedicated workflow, NOT on every push/PR (the full stack takes
minutes and requires docker). Triggers:
* workflow_dispatch (manual)
* PRs labelled run-e2e-full (opt-in for changes that touch
migrations, auth, or routing)
* nightly schedule (04:00 UTC)
- Uses Go 1.23.x and Node 20 to match PR #5's pinning.
- Uploads two artefacts on every run: e2e-screenshots
(test-results/screenshots/) and playwright-report.
docs/TESTING.md (new):
- Four-tier test pyramid: unit -> static analysis -> production
canary -> full-stack Playwright.
- Env var reference table for e2e-full.sh.
- How to trigger the CI workflow.
Verification:
bash -n scripts/e2e-full.sh clean
The spec imports compile cleanly against the existing @playwright
/test v1.40 declared in the root package.json; no new runtime
dependencies are added.
Existing scripts/e2e-explorer-frontend.spec.ts still matched by
the broadened testMatch regex.
Advances completion criterion 7 (end-to-end coverage): 'make e2e-full
boots the real stack, Playwright runs against it, CI uploads
screenshots, a nightly job catches regressions that only show up
when all services are live.'
SolaceScan Explorer - Tiered Architecture
🚀 Quick Start - Complete Deployment
Execute this single command to complete all deployment steps:
cd ~/projects/proxmox/explorer-monorepo
bash EXECUTE_DEPLOYMENT.sh
What This Does
- ✅ Tests database connection
- ✅ Runs migration (if needed)
- ✅ Stops existing server
- ✅ Starts server with database
- ✅ Tests all endpoints
- ✅ Provides status summary
Manual Execution
If the script doesn't work, see START_HERE.md for step-by-step manual commands.
Frontend
- Production (canonical target): the current Next.js standalone frontend in
frontend/src/, built fromfrontend/withnpm run buildand deployed to VMID 5000 as a Node service behind nginx. - Canonical deploy script:
./scripts/deploy-next-frontend-to-vmid5000.sh - Canonical nginx wiring: keep
/api,/api/config/*,/explorer-api/*,/token-aggregation/api/v1/*,/snap/, and/health; proxy/and/_next/to the frontend service usingdeployment/common/nginx-next-frontend-proxy.conf. - Legacy fallback only: the static SPA (
frontend/public/index.html+explorer-spa.js) remains in-repo for compatibility/reference, but it is not a supported primary deployment target. - Architecture command center:
frontend/public/chain138-command-center.html— tabbed Mermaid topology (Chain 138 hub, network, stack, flows, cross-chain, cW Mainnet, off-chain, integrations). Linked from the SPA More → Explore → Visual Command Center. - Legacy static deploy scripts:
./scripts/deploy-frontend-to-vmid5000.shand./scripts/deploy.shnow fail fast with a deprecation message and point to the canonical Next.js deploy path. - Frontend review & tasks: frontend/FRONTEND_REVIEW.md, frontend/FRONTEND_TASKS_AND_REVIEW.md
Documentation
docs/README.md— Documentation overview and indexdocs/EXPLORER_API_ACCESS.md— API access, 502 fix, CSP, frontend deploySTART_HERE.md— Quick start with all commandsCOMPLETE_DEPLOYMENT.md— Detailed deployment stepsDEPLOYMENT_COMPLETE_FINAL.md— Final status reportREADME_DEPLOYMENT.md— Deployment quick referencedeployment/DEPLOYMENT_GUIDE.md— Full LXC/Nginx/Cloudflare deployment guidedocs/INDEX.md— Bridge and operations doc index
Architecture
- Track 1 (Public): RPC Gateway - No authentication required
- Track 2 (Approved): Indexed Explorer - Requires authentication
- Track 3 (Analytics): Analytics Dashboard - Requires Track 3+
- Track 4 (Operator): Operator Tools - Requires Track 4 + IP whitelist
Configuration
- Database User:
explorer - Database Password:
***REDACTED-LEGACY-PW*** - RPC URL:
http://192.168.11.250:8545 - Chain ID:
138 - Port:
8080
Reusable libs (extraction)
Reusable components live under backend/libs/ and frontend/libs/ and may be split into separate repos and linked via git submodules. Clone with submodules:
git clone --recurse-submodules <repo-url>
# or after clone:
git submodule update --init --recursive
See docs/REUSABLE_COMPONENTS_EXTRACTION_PLAN.md for the full plan.
Testing
- All unit/lint:
make test— backendgo test ./...and frontendnpm test(lint + type-check). - Backend:
cd backend && go test ./...— API tests run without a real DB; health returns 200 or 503, DB-dependent endpoints return 503 when DB is nil. - Frontend:
cd frontend && npm run buildornpm test— Next.js build (includes lint) or lint + type-check only. - E2E:
make test-e2eornpm run e2efrom repo root — Playwright tests against https://blockscout.defi-oracle.io by default; useEXPLORER_URL=http://localhost:3000for local.
Status
✅ All implementation complete
✅ All scripts ready
✅ All documentation complete
✅ Frontend: C1–C4, M1–M4, H4, H5, L2, L4 done; H1/H2/H3 (escapeHtml/safe href) in place; optional L1, L3 remain
✅ CI: backend + frontend tests; lint job runs go vet, npm run lint, npm run type-check
✅ Tests: make test, make test-e2e, make build all pass
Ready for deployment!