🎨 Epic: Frontend Testing & Code Quality

Goal

Establish comprehensive testing, documentation, and code quality standards for the Admin UI frontend. This includes adding JavaScript unit testing, improving Playwright UI automation, documenting all frontend code, and refactoring the monolithic admin.js (31K lines) into maintainable modules.

Why Now?

The Admin UI has grown significantly with HTMX, Alpine.js, and custom visualizations (Gantt charts, flame graphs). Current gaps:

1. No JS Unit Tests: admin.js, gantt-chart.js, flame-graph.js have zero unit test coverage
2. Large Monolith: admin.js is 31,287 lines with 40+ logical sections—difficult to maintain and test
3. No JSDoc: Functions lack parameter/return type documentation
4. Playwright Gaps: UI automation tests need updates for new auth flow and broader CRUD coverage
5. No Type Safety: Plain JavaScript without TypeScript or tsc --checkJs validation
6. Performance Monitoring: No automated Lighthouse CI checks for regressions

📖 User Stories

Scenario: Run JavaScript unit tests
  Given Jest or Vitest is configured in package.json
  When I run "make test-js"
  Then all JavaScript unit tests should execute
  And test results should be displayed

Scenario: Test coverage reporting
  Given tests exist for utility functions
  When I run "make coverage-js"
  Then a coverage report should be generated in coverage/js/
  And coverage percentage should be displayed

Scenario: CI integration
  Given a PR is opened with JS changes
  When CI runs
  Then JavaScript tests should run alongside Python tests
  And CI should fail if tests fail

Scenario: Modules are importable
  Given admin.js is split into modules
  When I import a specific module (e.g., auth.js)
  Then only that module's code should be loaded
  And the module should export its public functions

Scenario: No functionality regression
  Given the refactored modular code
  When all Playwright tests run
  Then all tests should pass
  And UI behavior should be identical to before

Scenario: Maintainable file sizes
  Given the modular structure
  Then no single file should exceed 1000 lines
  And each file should have a single responsibility

Scenario: Playwright authenticates with new flow
  Given the new email/password login flow
  When Playwright tests run
  Then tests should authenticate using ADMIN_EMAIL/ADMIN_PASSWORD
  And login should succeed before test execution

Scenario: Session persistence
  Given a test that requires authentication
  When multiple tests run in sequence
  Then authentication should persist across tests
  And no re-login should be needed per test

Scenario: Server CRUD tests
  Given the Servers page in Admin UI
  Then tests should cover: create, edit, toggle, delete server

Scenario: Tool CRUD tests
  Given the Tools page in Admin UI
  Then tests should cover: create, edit, test tool, delete tool

Scenario: All entities covered
  Given all entity types (servers, tools, resources, prompts, gateways, agents)
  Then each should have CRUD Playwright tests
  And tests should run in CI pipeline

Scenario: Functions have JSDoc
  Given any exported function in the codebase
  Then it should have a JSDoc comment with @param and @returns
  And complex functions should have @example blocks

Scenario: ESLint enforces JSDoc
  Given the ESLint configuration
  When linting runs on a function without JSDoc
  Then a warning should be generated

Scenario: Type errors caught at build time
  Given a function with incorrect types
  When "make typecheck-js" runs
  Then type errors should be reported
  And CI should fail on type errors

Scenario: IDE type hints
  Given VSCode with TypeScript support
  When editing JavaScript files
  Then type hints should appear from JSDoc annotations

🏗 Architecture

Proposed Module Structure

mcpgateway/static/
├── admin.js              # Main entry point (imports modules)
├── modules/
│   ├── auth.js           # Authentication handling
│   ├── chart-registry.js # Chart.js instance management
│   ├── crud-operations.js# CRUD with validation
│   ├── metrics.js        # Metrics display and loading
│   ├── modals.js         # Modal functions
│   ├── form-validation.js# Form validation
│   ├── team-management.js# Team functions
│   ├── a2a-agents.js     # A2A agent functionality
│   ├── bulk-import.js    # Bulk import tools
│   ├── llm-settings.js   # LLM configuration
│   ├── htmx-handlers.js  # HTMX event handlers
│   └── utilities.js      # Shared utilities
├── gantt-chart.js        # Gantt chart component
└── flame-graph.js        # Flame graph component

Testing Architecture

flowchart TD
    A[JavaScript Source] --> B[Jest/Vitest]
    B --> C[Unit Tests]
    C --> D[Coverage Report]
    
    A --> E[Playwright]
    E --> F[E2E Tests]
    F --> G[Screenshots]
    
    A --> H[tsc --checkJs]
    H --> I[Type Errors]
    
    A --> J[ESLint + Biome]
    J --> K[Lint Errors]

📋 Implementation Tasks

Phase 1: Unit Testing Setup

• Add make test-js target
• Add make coverage-js target
• Write initial tests for utility functions
• Add CI workflow step for JS tests

Phase 2: Playwright Auth Fix

• Update Playwright auth to use ADMIN_EMAIL/ADMIN_PASSWORD
• Create auth fixture for test reuse
• Verify login flow tests pass
• Handle JWT cookie authentication

Phase 3: Playwright CRUD Coverage

• Add Server CRUD tests
• Add Tool CRUD tests
• Add Resource CRUD tests
• Add Prompt CRUD tests
• Add Gateway CRUD tests
• Add Agent CRUD tests

Phase 4: Module Split

• Extract chart-registry.js module
• Extract auth.js module
• Extract crud-operations.js module
• Extract metrics.js module
• Extract modals.js module
• Extract remaining modules
• Update admin.js to import modules
• Verify all Playwright tests pass

Phase 5: JSDoc Documentation

• Add JSDoc to utility functions
• Add JSDoc to all module exports
• Configure ESLint JSDoc rules
• Add @example blocks to complex functions

Phase 6: TypeScript Type Checking

• Create tsconfig.json with checkJs
• Add make typecheck-js target
• Add CI step for type checking
• Fix initial type errors

Phase 7: Additional Linting

• Configure Biome as additional linter
• Add make biome target
• Add Lighthouse CI configuration
• Add visual regression testing with Playwright screenshots

⚙️ Configuration Example

jest.config.js

module.exports = {
  testEnvironment: 'jsdom',
  testMatch: ['**/*.test.js', '**/*.spec.js'],
  collectCoverageFrom: ['mcpgateway/static/**/*.js'],
  coverageDirectory: 'coverage/js',
  coverageThreshold: {
    global: { branches: 50, functions: 50, lines: 50 }
  }
};

tsconfig.json

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "target": "ES2020",
    "moduleResolution": "node"
  },
  "include": ["mcpgateway/static/**/*.js"]
}

✅ Success Criteria

• Jest/Vitest configured and running
• make test-js runs JavaScript unit tests
• JS test coverage > 50% for utility functions
• Playwright tests pass with new auth flow
• CRUD tests exist for all entity types
• admin.js split into < 1000 line modules
• All exported functions have JSDoc
• tsc --checkJs reports no errors
• CI runs JS tests, type checking, and linting

🏁 Definition of Done

• Unit testing framework configured
• Initial unit tests written and passing
• Playwright auth updated and working
• CRUD Playwright tests for all entities
• admin.js modularized
• JSDoc added to all modules
• TypeScript type checking enabled
• CI updated with all JS quality checks
• Code passes make verify
• PR reviewed and approved

🔗 Related Issues

• Related to [EPIC][BUILD]: Frontend package management with npm #2271 (npm package management)
• Admin UI component documentation
• Playwright test infrastructure