ACI MCP Server

# Testing Guide for ACI MCP Server This guide explains how to test the ACI MCP server using various approaches. ## Test Types Available ### 1. 🧩 Unit Tests - **Purpose**: Test individual components and functions - **Technology**: Jest with TypeScript - **Coverage**: API service, configuration management, utilities - **Speed**: Fast (< 5 seconds) ### 2. 🔗 Integration Tests - **Purpose**: Test complete workflows against APIC API - **Options**: Mock APIC server or real APIC controller - **Coverage**: All 35+ MCP tools, authentication, error handling - **Speed**: Medium (30-60 seconds) ### 3. 🎮 Manual Testing - **Purpose**: Interactive testing of individual tools - **Features**: Menu-driven interface, real-time results - **Use Cases**: Debugging, API exploration, demonstration - **Speed**: User-controlled ### 4. 📡 Mock Server - **Purpose**: Standalone APIC simulator for development - **Features**: Realistic responses, session management, CRUD operations - **Use Cases**: Development without real APIC access - **Speed**: Instant startup ## Quick Start ### Prerequisites ```bash cd aci-mcp-server npm install npm run build ``` ### Run All Tests (Recommended) ```bash ./test.sh all --mock ``` ### Test Individual Components #### Unit Tests ```bash ./test.sh unit ``` #### Integration Tests with Mock APIC ```bash ./test.sh integration --mock ``` #### Integration Tests with Real APIC ```bash # Set environment variables first export ACI_APIC_URL="https://your-apic.domain.com" export ACI_USERNAME="admin" export ACI_PASSWORD="your_password" ./test.sh integration --real ``` #### Manual Testing Tool ```bash ./test.sh manual --mock ``` #### Start Mock APIC Server ```bash ./test.sh mock ``` ## Detailed Testing Scenarios ### Testing with Mock Server The mock server provides realistic APIC responses without requiring actual hardware: ```bash # Start integration tests (automatically starts mock server) ./test.sh integration --mock # Or start mock server manually for development ./test.sh mock # Then in another terminal: curl -X POST http://localhost:8443/api/aaaLogin.json \ -H "Content-Type: application/json" \ -d '{"aaaUser":{"attributes":{"name":"admin","pwd":"admin"}}}' ``` **Mock Server Features:** - Realistic tenant, EPG, and fault data - Session management with cookies - Support for both password and certificate auth - CRUD operations for all object types - Configurable via environment variables ### Testing with Real APIC #### Environment Variable Configuration ```bash export ACI_APIC_URL="https://10.1.1.1" export ACI_USERNAME="mcp-user" export ACI_PASSWORD="SecurePass123" export ACI_VALIDATE_CERTS="false" # For lab environments export ACI_TIMEOUT="30000" ./test.sh integration --real ``` #### Configuration File Method Create `aci-config.json`: ```json { "apicUrl": "https://10.1.1.1", "username": "mcp-user", "password": "SecurePass123", "validateCerts": false, "timeout": 30000 } ``` Then run: ```bash ./test.sh integration --real ``` ### Manual Testing Workflow The manual testing tool provides an interactive menu for testing: ```bash ./test.sh manual --mock ``` **Available Tests:** 1. **auth** - Test authentication 2. **tenants** - List all tenants 3. **health** - Get fabric health 4. **faults** - List all faults 5. **critical-faults** - List critical faults only 6. **nodes** - List fabric nodes 7. **create-tenant** - Create and auto-delete test tenant 8. **apps** - List application profiles 9. **epgs** - List endpoint groups 10. **bridge-domains** - List bridge domains 11. **vrfs** - List VRFs 12. **contracts** - List contracts **Special Commands:** - `menu` - Show available tests - `clear` - Clear screen - `quit` / `exit` - Exit tool ### Coverage Testing Generate detailed test coverage reports: ```bash ./test.sh coverage ``` This creates: - Console coverage summary - HTML report in `coverage/` directory - LCOV report for CI/CD integration ## Test Configuration ### Environment Variables ```bash # APIC Connection ACI_APIC_URL=https://apic.example.com ACI_USERNAME=admin ACI_PASSWORD=password ACI_CERT_NAME=cert-name ACI_PRIVATE_KEY_PATH=/path/to/key.pem ACI_VALIDATE_CERTS=false ACI_TIMEOUT=30000 # Tool Configuration ACI_TOOL_MODE=core # or 'all' ACI_TENANT_FOCUS=production # optional # Test Configuration MOCK_APIC_PORT=8443 ``` ### Jest Configuration Tests are configured in `jest.config.js`: - TypeScript support via ts-jest - ES modules enabled - Coverage collection from `src/` directory - 30-second test timeout - Setup file for global test configuration ## Continuous Integration ### GitHub Actions Example ```yaml name: Test ACI MCP Server on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: '18' - run: npm install - run: npm run build - run: ./test.sh all --mock - name: Upload coverage uses: codecov/codecov-action@v3 with: file: ./coverage/lcov.info ``` ### Local CI Simulation ```bash # Clean environment test rm -rf node_modules build coverage npm install npm run build ./test.sh all --mock ``` ## Troubleshooting ### Common Issues #### Authentication Failures ```bash # Check APIC connectivity curl -k https://your-apic/api/class/topSystem.json # Verify credentials ./test.sh manual --real # Then run: auth ``` #### TypeScript Compilation Errors ```bash # Clean and rebuild npm run clean npm run build ``` #### Port Conflicts (Mock Server) ```bash # Use different port export MOCK_APIC_PORT=9443 ./test.sh mock ``` #### SSL/TLS Issues ```bash # Disable certificate validation export ACI_VALIDATE_CERTS=false ``` ### Debug Mode Enable verbose logging: ```bash export DEBUG=aci-mcp:* ./test.sh integration --mock ``` ### Memory Issues For large test suites: ```bash export NODE_OPTIONS="--max-old-space-size=4096" npm test ``` ## Test Data ### Mock Server Data The mock server includes realistic test data: - **3 Tenants**: common, production, development - **2 Application Profiles**: web-app, database-app - **3 EPGs**: web-epg, app-epg, db-epg - **2 Bridge Domains**: web-bd, app-bd - **2 VRFs**: prod-vrf, dev-vrf - **2 Contracts**: web-to-app, app-to-db - **3 Faults**: critical, warning, info severities - **3 Nodes**: 2 leaf switches, 1 spine switch ### Real APIC Requirements For testing against real APIC: - APIC version 4.0+ recommended - User with admin privileges or specific RBAC - Network connectivity to APIC management interface - Valid SSL certificate or disabled validation ## Performance Benchmarks Expected test execution times: | Test Type | Mock Server | Real APIC | |-----------|------------|-----------| | Unit Tests | 5s | 5s | | Integration Tests | 30s | 60s | | Coverage Tests | 45s | 75s | | Manual Testing | Interactive | Interactive | ## Security Considerations ### Test Environment - Never use production credentials in tests - Use dedicated test APIC or lab environment - Enable audit logging to track test operations - Use least-privilege RBAC for test users ### Credential Management - Store sensitive data in environment variables - Use `.env` files that are git-ignored - Consider using certificate-based authentication - Rotate test credentials regularly ## Contributing Tests When adding new features: 1. **Add Unit Tests** - Test individual functions 2. **Add Integration Tests** - Test complete workflows 3. **Update Mock Server** - Add mock responses for new APIs 4. **Update Documentation** - Document new test scenarios Example test structure: ```typescript describe('New Feature', () => { test('should handle success case', async () => { // Arrange // Act // Assert }); test('should handle error cases', async () => { // Test error scenarios }); }); ```