Testing Guide

AI Admin Panel uses multiple testing layers: Go unit and integration tests, TypeScript type-checking, Playwright end-to-end tests, and template validation.

Go Tests

Running Tests

# Run all tests (24+ packages)
go test ./...

# Run with verbose output
go test -v ./...

# Run a specific package
go test ./internal/api/handler/...

# Run a specific test function
go test -run TestTemplateLoader ./internal/templates/...

# Run with race detector
go test -race ./...

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Test Structure

Tests follow Go conventions and live alongside the code they test:

internal/
  domain/service/
    service.go
    service_test.go
  api/handler/
    service_handler.go
    service_handler_test.go
  templates/
    loader.go
    loader_test.go

Key Test Suites

Package	Tests	What It Validates
internal/templates	Template loading	All 45 YAML specs parse correctly, compose generation produces valid output
internal/api/handler	HTTP handlers	Request/response handling, auth checks, error cases
internal/domain/service	Business logic	Service lifecycle, quota enforcement, plan validation
internal/domain/customer	Customer logic	CRUD operations, data isolation, GDPR operations
internal/worker	Async jobs	Deploy, backup, health check job execution
internal/repository	Database queries	sqlc-generated queries work against test database

Template Validation Tests

Template tests are critical — they ensure all 45 templates are valid:

go test ./internal/templates/...

These tests verify:

• Every YAML file in the catalog directory parses without errors
• Required fields are present (compose, variables, minResources, healthcheck, expose)
• Compose specs generate valid Docker Compose YAML
• Variable definitions have valid types and required fields
• Security profiles are valid values
• Health check configurations are well-formed

Deploy-All-Templates Test

A comprehensive integration test that deploys every template and verifies it starts:

go test -run TestDeployAllTemplates -timeout 1h ./internal/templates/...

This test:

1. Iterates through all 45 templates
2. Generates a compose file with default/test variables
3. Starts the containers
4. Waits for the health check to pass
5. Stops and cleans up the containers
6. Reports which templates succeeded and which failed

The test sorts templates by size (smallest first) and skips GPU-requiring templates. Each template gets a 4-minute timeout.

TypeScript Type Checking

cd frontend

# Type-check all TypeScript files (must produce zero errors)
npx tsc --noEmit

The TypeScript compiler is configured in strict mode. All type errors must be resolved before committing frontend changes.

Frontend Build

cd frontend

# Production build (must succeed without errors)
npm run build

The build process runs Vite with the production configuration. Build failures indicate code issues that must be resolved.

Playwright E2E Tests

End-to-end tests run a headless browser against the live panel.

Setup

cd frontend

# Install Playwright browsers (first time)
npx playwright install

Running Tests

cd frontend

# Run all E2E tests
npx playwright test

# Run with browser visible (headed mode)
npx playwright test --headed

# Run with UI mode (interactive)
npx playwright test --ui

# Run a specific test file
npx playwright test tests/login.spec.ts

# Run tests matching a pattern
npx playwright test -g "template catalog"

Test Configuration

Playwright is configured in frontend/playwright.config.ts:

export default defineConfig({
  testDir: './tests',
  baseURL: process.env.BASE_URL || 'https://panel.example.com',
  use: {
    ignoreHTTPSErrors: true,
  },
});

Set BASE_URL to point to your panel instance.

E2E Test Coverage

The 20 E2E tests cover these flows:

Test	What It Validates
Login via Keycloak OIDC	Authentication flow works end-to-end
Dashboard loads	Main page renders with service summary
Template catalog	All categories visible, logos load, featured section present
Template detail	Template info, variables form, deploy button
Deploy from template	Full deploy flow — configure, deploy, verify running
Service lifecycle	Start, stop, restart a deployed service
Service logs	Log streaming page loads and shows output
Customer list	Customer management page loads
Customer create	New customer form works
Settings pages	AI Provider, Notifications, Cloudflare DNS pages reachable
Deploy methods	All 4 deploy options visible (Template, Git, AI, Compose)
Git deploy form	Git deploy form loads with URL and branch fields
AI deploy form	AI deploy form loads with URL field
Compose deploy form	Compose editor loads with YAML input
Service delete	Delete a service and verify cleanup
Navigation	Sidebar links work, lazy routes load
Auth redirect	Unauthenticated requests redirect to login
Error handling	404 page displays correctly
Responsive layout	Critical flows work at mobile viewport
Dark theme	UI renders correctly in dark mode

Viewing Test Results

# Show HTML report after test run
npx playwright show-report

Failed tests include screenshots and traces for debugging.

Testing Checklist

Before submitting any change:

Change Type	Required Tests
Backend (Go)	go build ./... and go test ./...
Frontend (TypeScript)	cd frontend && npx tsc --noEmit && npm run build
Template changes	go test ./internal/templates/...
Pre-deploy	./scripts/build.sh --verify
Post-deploy	cd frontend && npx playwright test

CI/CD

Automated tests run on every push to dev branches:

1. Go tests — go test ./... with race detector
2. TypeScript — npx tsc --noEmit
3. Frontend build — npm run build
4. Template validation — template loader tests
5. Binary build — ./scripts/build.sh --verify