Tau.Acuvim/portal/TESTING.md

Tau Acuvim Portal — Testing

This file covers what's checked-in (backend unit tests) and what to do manually or add later (integration, frontend).

Backend unit tests

xUnit project under portal/tests/Tau.Acuvim.Portal.Tests, matching the console's test stack (xUnit 2.9.3, Microsoft.NET.Test.Sdk 17.14.1, EF Core InMemory 10.0.8, coverlet 6.0.4).

cd C:\AcuvimDev\Tau.Acuvim\portal\tests\Tau.Acuvim.Portal.Tests
dotnet test

What's covered:

Suite	What it locks down
CostCalculatorTests	Period selection by day-of-week + time, overlap-first-wins, default-rate fallback, VAT, fixed charges, includeFixedMonthlyCharge=false, timezone conversion (sample inside vs outside the local-time window), empty-samples edge case, null-tariff guard.
ConnectionStringResolverTests	All four precedence branches: explicit conn string wins; auto-provision in non-Production builds from TimescaleDb block; auto-provision in Production throws; no conn string + auto-provision off throws.
TariffValidatorTests	Tariff-level rules (name, effective dates, non-negative rates, VAT 0–100) and per-period rules (name, days, time order, midnight-wrap rejection, negative rate, bad time format).
DayOfWeekFlagTests	Each weekday maps correctly; Weekdays/Weekends/All compose.

What's not covered by code (deliberate)

Authorization smoke tests

A WebApplicationFactory<Program> test that signs in a fake user and hits an admin endpoint would catch role-attribute regressions. Building one cleanly means swapping the EF provider, neutering MigrateAsync / TimescaleBootstrapper / the NpgSql health check, and stubbing cookie sign-in. That's a fair amount of plumbing for "the policy attribute is wired."

Add it if you start seeing role bypass regressions. Skeleton:

public class AuthorizationSmokeTests : IClassFixture<WebApplicationFactory<Program>> { … }

— with WebApplicationFactoryConfigureWebHost swapping AppDbContext for InMemory, removing the hosted services that need Timescale, and configuring a test authentication scheme.

Frontend component tests

Recommend Vitest + React Testing Library + jsdom. Not scaffolded in this repo on purpose — a half-built test runner is worse than none.

When you want them:

cd portal/frontend
npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom @vitest/coverage-v8

Add to vite.config.ts:

test: { environment: 'jsdom', setupFiles: ['./src/test-setup.ts'], globals: true }

High-value first tests:

• RequireAuth — renders children when authed, redirects to /login when not.
• RequireRole — renders 403 panel when role missing, children when present.
• BrandingProvider — applies CSS variables and document.title after fetch resolves.
• PeriodEditor — toggling day-of-week buttons updates the bitmask correctly (this is the trickiest pure-logic spot in the UI).

Manual integration scenario

End-to-end smoke test. Run after any phase change.

0. Reset

cd C:\AcuvimDev\Tau.Acuvim\portal
docker compose down -v          # wipe DB + Grafana volumes
docker compose up -d

1. Migrate + seed

cd src/Tau.Acuvim.Portal
dotnet run

Expect in the log:

• Database connection resolved via …
• Applied migration '<name>' (one per pending)
• TimescaleDB hypertable for monitoring.PowerMeasurements is ready (chunk interval: 7 days)
• Seeded default admin admin@example.com

2. Frontend up

cd portal/frontend
npm install
npm run dev

3. Walk the surface

1. Browse http://localhost:5174/login → branded card from template defaults.
2. Sign in as admin@example.com / ChangeMe123!.
3. Settings → Branding → change primary colour + footer + upload a small PNG. Save → re-themes everywhere without reload.
4. Settings → Rates → create municipality "Cape Town" TZ Africa/Johannesburg → add tariff with three periods (peak/standard/off-peak per the README example).
5. Settings → Users → create user@example.com / Password1, not admin. Sign out, log in as user → only Dashboard and Dashboards in nav; /admin/sites shows 403. Sign back in as admin.
6. Sites → create "Warehouse A" linked to Cape Town → add device with external ID ABC0001-MAIN-01.
7. Ingest via Swagger (/swagger) or:

   POST /api/ingest/measurements
   [
     {"time":"2026-05-17T10:00:00Z","deviceExternalId":"ABC0001-MAIN-01","activePowerKw":12.5,"energyImportedKwh":1000},
     {"time":"2026-05-17T10:15:00Z","deviceExternalId":"ABC0001-MAIN-01","activePowerKw":13.1,"energyImportedKwh":1003.3}
   ]
   

   → {accepted:2, rejected:0}. Re-post → same result, no duplicates (ON CONFLICT).
8. GET /api/measurements?deviceId=<guid>&from=2026-05-17T00:00:00Z&to=2026-05-17T23:59:59Z&bucket=hour → one bucket with sampleCount: 2.
9. Dashboards → "Power Overview" iframe loads; device dropdown lists the device; chart renders the two samples.
10. Settings → App config → confirm DB host = timescaledb, port 5432, db power_monitoring, no password anywhere.

4. Edges to poke

Check	Expected
Wrong password 6 times	6th try locks the account for 15 min (Identity lockout).
dotnet run with ASPNETCORE_ENVIRONMENT=Production + default admin password	App refuses to start with explicit error.
Restart dotnet run against existing DB	"Seeded default admin" line absent (idempotent). Bootstrapper re-confirms Timescale hypertable without error.
Delete a site with devices+measurements	Cascade removes everything; UI updates.
Create a period with EndTime ≤ StartTime in Settings → Rates	Backend 400 with "no midnight wrap" message.
GET /api/admin/config-overview as non-admin	403.
Upload a 3 MB JPG to branding logo	400 "Logo must be <= 2 MB".

Local dev troubleshooting

• EF migration error on startup — usually a schema drift since the last migration. Run dotnet ef migrations add <Name> to capture the diff, commit, restart.
• TimescaleBootstrapper complains about hypertable — the table was already created by a previous run with different settings. Drop the table or recreate the DB volume.
• POST /api/ingest/measurements returns {accepted: 0, rejected: N} — the device's ExternalId doesn't match anything in the monitoring.Devices table. Create the device first under Sites.
• Dashboards page shows iframe but no chart — datasource UID mismatch. Confirm grafana/provisioning/datasources/timescaledb.yml sets uid: timescaledb and the dashboard JSON's panels reference the same.