Technical Debt & Testing

This document tracks code quality, testing gaps, and maintenance items for the Voltimax Platform.

---

Code Quality & Testing

Item	Component	Priority	Description
OCPP Protocol Handler testing	Gateway	High	0% test coverage - critical protocol has no tests
E2E user journeys	Frontend	High	Playwright configured but unused - no E2E tests
Platform API endpoint tests	Platform	High	Minimal coverage (~3 test files) for 40+ endpoints
External integrations testing	Platform	Medium	PvGis, QuartzSolar, ENTSO-E untested
Frontend authentication tests	Frontend	Medium	No Keycloak integration tests
Improve gateway test coverage	Gateway	Medium	Integration tests for all protocol handlers
Frontend component library cleanup	Frontend	Medium	Remove unused components, standardize patterns

---

Infrastructure & Architecture

Item	Component	Priority	Description
Keycloak integration refinements	Platform	High	Token refresh edge cases, session management
Consolidate deprecated Mediator.SourceGenerator	Platform	Medium	Migrate to built-in Mediator package
Update Elasticsearch client patterns	Platform	Low	Migrate to new Elastic.Clients.Elasticsearch
Time-series query optimization	Platform	Medium	Query plan analysis, index tuning

---

Test Coverage Summary

Testing Infrastructure

Frameworks & Tools:

• ✅ C# Unit Testing: NUnit 4.3.1 with FluentAssertions for readable assertions
• ✅ C# Mocking: Moq 4.20.72 and NSubstitute 5.3.0 (mixed usage across projects)
• ✅ Behavior-Driven Testing: LightBDD with Xunit integration for readable specifications
• ✅ Integration Testing: Testcontainers.PostgreSql 4.1.0 for real database tests
• ✅ Frontend Unit/Component: Vitest 2.1.8 with @vue/test-utils 2.4.6
• ⚠️ E2E Testing: Playwright 1.49.1 configured but only template file exists

Test Project Structure:

Project	Type	Focus Area	Test Count
Voltimax.Iot.Metrics.Tests	Unit	Metrics queries, aggregations	~15 files
Voltimax.Iot.Metrics.Tests.Integration	Integration	Elasticsearch storage	~8 files
Voltimax.Iot.Metrics.Behavior.Tests	BDD	User-facing metrics scenarios	~5 files
Voltimax.Platform.Data.Tests	Integration	Repository, EF Core	~12 files
Voltimax.Edge.Battery.Simulation.Tests	Unit	Battery physics simulation	~12 files
Voltimax.EnergyAdvisor.Tests	BDD	Rules engine evaluation	~10 files
Voltimax.Edge.Gateway.Service.Tests	Unit	Command handlers	~3 files
Voltimax.Platform.Functions.Tests	Unit	Azure Functions	~3 files
Voltimax.Edge.Ocpp.Tests	None	CRITICAL GAP	0 files
Frontend __tests__/	Component	Vue components	15 files
Frontend E2E	E2E	CRITICAL GAP	1 template

Total Estimated Test Files: ~85+ (65+ C#, 15+ frontend, 1 E2E template)

---

Well-Tested Components (✓)

1. Metrics System (3 dedicated test projects)

• Unit Tests (Voltimax.Iot.Metrics.Tests):
  • Query handlers for asset summaries, health checks, rate calculations
  • Histogram/time-series bucket generation
  • Cross-asset aggregations
  • Metric coverage analysis
• Integration Tests (Voltimax.Iot.Metrics.Tests.Integration):
  • Elasticsearch ingestion pipeline
  • Real-time query performance
  • Index management and rollover
• BDD Tests (Voltimax.Iot.Metrics.Behavior.Tests):
  • LightBDD scenarios for user-facing queries
  • Metric freshness validation
  • Ingestion rate monitoring

2. Repository/Database Layer (12 test files with Testcontainers)

• Test Files in Voltimax.Platform.Data.Tests:
  • EF Core repository CRUD operations
  • Query optimization and pagination
  • Multi-tenant data isolation
  • Migration validation
• Testcontainers Integration:
  • PostgreSQL 16 container with TimescaleDB
  • Real database for integration tests (not in-memory)
  • Container lifecycle managed per test session

3. Battery Simulation (12 comprehensive test files)

• Test Coverage in Voltimax.Edge.Battery.Simulation.Tests:
  • State-of-charge calculations (charge/discharge curves)
  • Power flow physics (voltage, current, resistance)
  • Temperature modeling
  • Cycle life degradation
  • Efficiency losses
  • Battery chemistry variations (LFP, NMC)

4. Energy Advisor/Rules Engine (BDD with LightBDD)

• Scenario Tests in Voltimax.EnergyAdvisor.Tests:
  • Pricing-based optimization rules
  • Solar forecast integration
  • Battery strategy selection
  • Multi-factor decision making
  • Readable specifications (Given-When-Then format)

5. Frontend Components (15 component/page tests)

• Test Files in src/@voltimax/iot-frontend/__tests__/:
  • Component rendering tests
  • User interaction tests (click, input, form submission)
  • Props and event emission validation
  • Composition API lifecycle tests
  • Pinia store integration tests

---

Partially Tested Components (⚠️)

1. Edge Gateway Service (Minimal testing)

• Current Coverage:
  • RefreshConfigurationCommandHandlerTests.cs - Configuration polling
  • ApplyStrategyCommandHandlerTests.cs - Strategy execution (possibly)
  • SetBatterySetpointCommandHandlerTests.cs - Direct control (possibly)
• Missing:
  • Strategy factory tests
  • Command pipeline behavior tests
  • NCronJob scheduled job tests (ApplyStrategyJob, SendControlSignalsJob)
  • Service Bus publisher/receiver tests
  • Cache-based setpoint tracking tests

2. Platform Functions (3 test files only)

• Current Coverage:
  • DayAheadPricingFunctionTests.cs - ENTSO-E daily pricing ingestion
  • IntraDayPricingFunctionTests.cs - ENTSO-E hourly pricing ingestion
  • TelemetryFunctionTests.cs - Service Bus telemetry processing
• Missing:
  • Timer trigger testing (cron schedule validation)
  • Dead-letter queue handling
  • Function resilience (retry, circuit breaker)
  • Elasticsearch bulk ingestion error handling
  • Function observability/tracing validation

3. Frontend (~50% coverage estimate)

• Tested:
  • 15 Vue component/page tests
  • Basic rendering and interaction
• Missing:
  • Keycloak authentication flow tests
  • Protected route navigation tests
  • API integration tests (TypeScript SDK)
  • TanStack Query cache behavior tests
  • Pinia store complex state tests
  • Error boundary/fallback tests
  • WebSocket connection tests

---

Untested/Minimal Components (✗)

1. OCPP Protocol Handler (0% coverage - CRITICAL)

Risk Level: High - OCPP is mission-critical for EV charging integration

Current State:

• Voltimax.Edge.Ocpp.Tests project exists but contains only AssemblyCategory.cs (1 line)
• No actual test files
• OCPP 2.1 protocol implementation in production without test coverage

Required Tests:

• Message Handler Tests:
  • Boot notification (charge station registration)
  • Heartbeat (connection keep-alive)
  • StatusNotification (availability, faulted, charging states)
  • MeterValues (energy consumption, power readings)
  • Authorize (RFID tag validation)
  • StartTransaction/StopTransaction
  • RemoteStartTransaction/RemoteStopTransaction
• Protocol State Machine Tests:
  • Charge station lifecycle (Pending > Available > Charging > Finishing)
  • Transaction state transitions
  • Error recovery flows
• WebSocket Tests:
  • Connection establishment and authentication
  • Reconnection with exponential backoff
  • Ping/pong keep-alive
  • Connection drop handling
• Serialization Tests:
  • JSON schema validation (OCPP 2.1 spec compliance)
  • Message deserialization edge cases (null values, missing fields)
• Compliance Tests:
  • OCPP 2.1 conformance test suite (if available)
  • Interoperability with real charge stations (Peblar, Autel)

Recommended Approach:

• Use NUnit + Moq/NSubstitute for handler tests
• Mock WebSocket layer for protocol tests
• Testcontainers for integration tests with OCPP simulator
• Consider OCPP test tools (Steve, MobilityHouse)

Effort Estimate: 2-3 weeks for comprehensive coverage

---

2. E2E User Journeys (0% coverage - CRITICAL)

Risk Level: High - No protection against UI/integration regressions

Current State:

• Playwright 1.49.1 configured in package.json
• Only e2e-template.spec.ts exists (example file)
• No actual E2E test scenarios

Required Test Scenarios:

Critical Path (P0):

1. Authentication Flow:

   • Login with valid credentials > Dashboard
   • Login with invalid credentials > Error message
   • Token expiration > Auto-redirect to login
   • Logout > Session cleared

2. Asset Provisioning:

   • Navigate to Assets > Click "Create Asset"
   • Step 1: Select device class (Battery, Solar, Grid, Charger, Building)
   • Step 2: Enter name and location
   • Step 3: Configure protocol (Modbus TCP, HTTP, OCPP)
   • Step 4: Device-specific configuration
   • Step 5: Review and submit > Asset appears in list

3. Energy Dashboard:

   • Navigate to Overview > Power balance displayed
   • Real-time metrics update (grid, battery, solar, load)
   • Asset freshness indicators show recent data
   • Solar forecast card displays predictions

4. Battery Control:

   • Navigate to Asset Detail > Battery tab
   • View current state (SoC, power, voltage, temperature)
   • Change strategy (NetZero, Charge, Discharge)
   • Set manual setpoint > Command sent to gateway
   • Verify control signal in logs

Secondary Path (P1):

1. Gateway Configuration:

   • Navigate to Gateway Management > Gateway list
   • Click gateway > Detail view
   • Edit physical location (lat/lon) > Save
   • View connected devices and metrics
   • Check gateway logs with filtering

2. Workflow Management:

   • Navigate to Workflows > Workflow list
   • Create new workflow with triggers/actions
   • Enable/disable workflow > Status updates
   • View workflow execution history

3. Multi-Tenant Isolation:

   • Login as Tenant A > See only Tenant A assets
   • Login as Tenant B > See only Tenant B assets
   • Attempt cross-tenant API access > 403 Forbidden

Performance & Accessibility (P2):

1. Performance:

   • Dashboard load time < 2 seconds
   • Asset list with 100+ items renders smoothly
   • Metrics chart rendering < 500ms

2. Accessibility:

   • Keyboard navigation works for all forms
   • Screen reader compatibility (aria labels)
   • Color contrast meets WCAG 2.1 AA

Test Infrastructure Needs:

• Keycloak test realm with pre-seeded users (admin, tenant-a, tenant-b)
• PostgreSQL test database with seed data (locations, assets, gateways)
• Elasticsearch test instance with sample metrics
• Mock gateway service for bidirectional communication tests
• CI/CD integration (GitHub Actions with browser grid)

Recommended Approach:

• Page Object Model (POM) pattern for maintainability
• Playwright's test.step() for readable scenarios
• Screenshot/video on failure for debugging
• Parallel execution for fast feedback (<5 min total)

Effort Estimate: 3-4 weeks for critical path + secondary scenarios

---

3. Platform API Endpoints (Minimal coverage - ~3 test files for 40+ endpoints)

Risk Level: Medium-High - API contract violations can break frontend/gateway integration

Current State:

• 40+ REST endpoints in Voltimax.Platform.Api
• Only ~3 test files in Voltimax.Platform.Functions.Tests (Functions, not API)
• No dedicated API integration test project

Required Test Coverage:

API Test Categories:

1. Request Validation Tests:

   • Required field validation (400 Bad Request)
   • Type validation (string vs int, date formats)
   • Range validation (min/max values, string length)
   • FluentValidation rules enforcement
   • Custom validation logic (e.g., battery SoC 0-100%)

2. Authorization Tests:

   • Unauthenticated requests > 401 Unauthorized
   • Missing required role > 403 Forbidden
   • Multi-tenant isolation (Tenant A cannot access Tenant B data)
   • Admin-only endpoints enforced
   • Token expiration handling

3. Success Path Tests:

   • CRUD operations for all entities (Locations, Assets, Batteries, Solar, Grid, Chargers, Buildings)
   • Complex queries with filtering, sorting, pagination
   • Relationships (cascade deletes, foreign key constraints)
   • Bulk operations (batch create, update, delete)

4. Error Handling Tests:

   • 404 Not Found for invalid IDs
   • 409 Conflict for duplicate names/identifiers
   • 500 Internal Server Error with problem details
   • Database constraint violations
   • External API failures (ENTSO-E, PvGis) with fallback

5. Performance Tests:

   • Pagination works correctly for large datasets (1000+ items)
   • Query optimization (N+1 query detection)
   • Response time < 200ms for simple queries
   • Concurrent request handling (100 requests/sec)

Endpoint Groups to Test (40+ endpoints):

• /api/gateways/* - Gateway CRUD and hierarchy
• /api/assets/* - Asset management (6 device types)
• /api/batteries/*, /api/solar-panels/*, /api/grid-connections/*, /api/chargers/*, /api/buildings/*
• /api/pricing/day-ahead/*, /api/pricing/intraday/* - EPEX pricing queries
• /api/solar-forecast/* - Solar forecasting
• /api/workflows/* - Workflow automation
• /api/metrics/* - Metrics queries and aggregations
• /api/gateway-configuration/* - Gateway config sync

Recommended Approach:

• Create Voltimax.Platform.Api.Tests.Integration project
• Use WebApplicationFactory<Program> for in-process API testing
• Testcontainers.PostgreSql for real database
• Respawn for database cleanup between tests
• Test fixtures for common scenarios (multi-tenant seed data)

Effort Estimate: 4-6 weeks for comprehensive API test suite

---

4. External Integrations (Untested)

Risk Level: Medium - External API changes can break pricing/forecasting features

Current State:

• No tests for external API integrations
• Production code makes real HTTP calls to ENTSO-E, PvGis, Quartz Solar
• No mock/stub infrastructure for testing

Required Test Coverage:

ENTSO-E/EPEX Pricing (Voltimax.Entsoe):

• Unit Tests:
  • EpexQueryService request building (query parameters, headers)
  • EntsoeEpexDeserializer XML parsing (valid responses, malformed XML)
  • PriceRequestResponseFormatter protocol formatting
  • Error handling (API timeouts, rate limits, invalid bidding zones)
• Integration Tests:
  • Real ENTSO-E API call with sandbox/test credentials (if available)
  • Fallback behavior when API unavailable
  • Caching layer validation (avoid redundant API calls)

PvGis Solar Forecasting (Voltimax.PvGis):

• Unit Tests:
  • API client request building (lat/lon, panel specs, date ranges)
  • Response parsing (JSON/XML depending on API)
  • Geographic coordinate validation (lat -90 to 90, lon -180 to 180)
  • Error handling (invalid coordinates, API errors)
• Integration Tests:
  • Real PvGis API call (public API, no auth required)
  • Forecast data validation (non-negative values, correct timestamps)

Quartz Solar Forecasting (Voltimax.EnergyAdvisor):

• Unit Tests:
  • Quartz Solar API client configuration
  • Request/response serialization
  • Error handling (API downtime, invalid responses)
• Integration Tests:
  • Real Quartz Solar API call
  • Forecast accuracy validation (if historical data available)

Azure Service Bus (Voltimax.Platform.Functions, Voltimax.Edge.Gateway.Service):

• Unit Tests:
  • TelemetryFrameServiceBusPublisherHandler message serialization
  • ServiceBusReceiver message deserialization
  • Dead-letter queue handling
• Integration Tests:
  • Testcontainers.Azurite for local Service Bus emulation (if available)
  • Real Service Bus namespace with test topic/queue
  • Message delivery guarantees (at-least-once, ordering)
  • Retry logic validation

Recommended Approach:

• Use WireMock.Net or MockHttp for HTTP mocking in unit tests
• Real API calls in integration tests (CI/CD only, not local dev)
• Environment variables for API keys/credentials
• VCR pattern (record/replay HTTP interactions) for deterministic tests

Effort Estimate: 2-3 weeks for all external integrations

---

5. Frontend Authentication (No tests)

Risk Level: High - Authentication bugs can expose multi-tenant data or lock users out

Current State:

• Keycloak JWT token handling in production
• No tests for auth flows
• Token refresh logic untested
• Protected route guards untested

Required Test Coverage:

Authentication Flow Tests (Unit + Integration):

1. Token Handling:

   • JWT token parsing and validation
   • Token storage (localStorage, sessionStorage, cookies)
   • Token expiration detection
   • Token refresh before expiration (proactive refresh)
   • Token refresh on 401 response (reactive refresh)
   • Multiple concurrent requests with expired token (avoid refresh race)

2. Protected Routes:

   • Unauthenticated user redirected to /login
   • Authenticated user can access protected routes
   • Role-based route protection (admin-only pages)
   • Deep-link preservation after login (return to original URL)

3. Login/Logout:

   • Login with valid credentials > Token stored > Dashboard
   • Login with invalid credentials > Error message displayed
   • Logout > Token cleared > Redirect to login
   • Session timeout > Auto-logout with message

4. Multi-Tenant Isolation:

   • Tenant A user cannot access Tenant B data (API returns 403)
   • Frontend hides UI for inaccessible resources
   • Tenant ID included in all API requests (header or token claim)

5. OAuth2/OIDC Flows (if using authorization code flow):

   • Authorization code exchange
   • PKCE challenge/verifier (if enabled)
   • State parameter validation (CSRF protection)

Keycloak Integration Tests (E2E):

• Login via Keycloak hosted login page
• SSO across multiple tabs (login in tab 1, tab 2 auto-authenticated)
• Token refresh across tabs (refresh in tab 1, tab 2 updates)
• Logout from Keycloak (single sign-out)

Recommended Approach:

• Unit Tests (Vitest):
  • Mock Keycloak SDK (@keycloak/keycloak-js)
  • Test auth store (Pinia) state management
  • Test route guards in isolation
• Integration Tests (Vitest + MSW):
  • Mock Keycloak token endpoint with Mock Service Worker
  • Test API integration with auth headers
• E2E Tests (Playwright):
  • Real Keycloak test realm
  • Full authentication flow including redirects

Effort Estimate: 2-3 weeks for comprehensive auth testing

---

Test Coverage Statistics

Category	Count	Status	Notes
C# Test Projects	16	✓	Well-structured, clear separation of concerns
C# Test Files	~65+	✓	Good coverage in tested areas
Frontend Test Files	15	⚠️	Component tests exist, integration missing
E2E Test Files	1 (template)	✗	Playwright configured but unused
Components with Tests	~25	⚠️	Core business logic covered
Components without Tests	~20	✗	Protocols, integrations, E2E gaps
Lines of Test Code	~15,000+	⚠️	Estimate based on project sizes
Test Execution Time	Unknown	-	Not measured, likely <5 min for unit tests

---

Test Coverage Improvement Roadmap

Phase 1: Critical Gaps (4-6 weeks)

1. OCPP Protocol Handler tests (2-3 weeks)
2. Platform API endpoint tests (2-3 weeks)
3. Frontend authentication tests (1-2 weeks)

Phase 2: Integration & E2E (5-7 weeks)

1. E2E user journey tests (3-4 weeks)
2. External integration tests (2-3 weeks)

Phase 3: Expansion (4-6 weeks)

1. Gateway command handler tests (1-2 weeks)
2. Platform Functions resilience tests (1-2 weeks)
3. Frontend component coverage expansion (2 weeks)

Total Estimated Effort: 13-19 weeks (3-5 months) for comprehensive test coverage

Success Metrics:

• Code coverage: >80% for critical paths (OCPP, API, auth)
• E2E coverage: 100% of critical user journeys
• CI/CD: All tests pass in <10 minutes
• Flakiness: <1% test failure rate unrelated to actual bugs