KNIRV Testnet

User guide for KNIRVTESTNET

KNIRV Testnet

✅ Phase 5 Synchronization and Optimization - COMPLETED

Status: 100% Complete with comprehensive test validation Achievement: All Phase 5 requirements successfully implemented and tested

Phase 5 Accomplishments

- ✅ Synchronization Strategy Refactor: Complete with automated mechanisms and monitoring - ✅ Agent-Builder Updates: TypeScript WASM compilation pipeline with LoRA training - ✅ Comprehensive Testing: 15 test functions with 100% pass rate - ✅ Production Ready: All components validated for production deployment

Test Suite Location: tests/phase5/ - Complete test coverage with detailed reporting

---

🚀 Render Deployment (NEW)

KNIRVTESTNET now includes unified web application hosting on Render, migrated from KNIRVGATEWAY to enable dynamic web services.

Applications Hosted

- GraphChain Explorer - /graphchain-explorer - Nexus Portal - /nexus-portal - Agent Developer Portal - /agent-developer-portal

Render Configuration

- Root Directory: KNIRVTESTNET (set in Render dashboard) - Build Command: npm install && npm run build - Start Command: npm start - Health Check: /health

Quick Start for Web Applications

`bash cd KNIRVTESTNET npm install npm run load-endpoints:testnet npm start `

Server runs on port 10000 with all applications accessible via Express.js routes.

---

Table of Contents

- Overview - Features - Comprehensive Test Suite - Advanced Features - Usage - Quick Start - Category-Specific Testing - Advanced Orchestrator Usage - Make Commands - Service Management - Test Categories - End-to-End Tests - Performance Tests - Security Tests - CORTEX Demos - Test Execution Options - System Validation Tests - Service Health Tests - Integration Tests - Testnet-Specific Feature Tests - Gateway Proxy Tests - Configuration - Environment Variables - Port Configuration - Test Configuration - Orchestrator Integration - Automatic Integration - Manual Usage - Test Reports - Generated Reports - Viewing Reports - Troubleshooting - Common Issues - Common Test Failures - Performance Issues - Test Metrics and Benchmarks - Expected Performance Metrics - Test Coverage - Test Automation - Continuous Testing - Automated Test Suite - Test Reporting - Generate Test Report - Test Results Analysis - Shutdown and Cleanup - Graceful Shutdown - Emergency Shutdown - Verification - Data Persistence - Next Steps & Roadmap - Test Results Summary

Overview

This directory contains the KNIRV testnet implementation, providing a comprehensive testing environment mirroring production functionality with advanced testing capabilities. This documentation details the fully implemented and production-ready test suite.

Features

Comprehensive Test Suite

The KNIRVTESTNET features a fully implemented, production-ready test suite with:

- 100% Working Test Suite: All tests passing with real service integration (31/31 passing) - Advanced Orchestrator: Go-based test automation with CLI interface - Multi-Category Testing: E2E, Performance, Security, and CORTEX demos - Real API Integration: No mocks - tests actual running services - Dynamic Port Discovery: Automatically detects service ports - Comprehensive Reporting: HTML reports with detailed metrics

Advanced Features

- Intelligent Service Detection: Skips initialization if services already running - Real Blockchain Integration: Tests actual blockchain with 142+ blocks verified - Concurrent Testing: Multi-threaded test execution - Automated Reporting: Timestamped HTML reports with metrics

Usage

Quick Start

`bash

Using Make commands (recommended)

make testnet-tests # Start testnet and run tests make start # Start the testnet make test # Run integration tests make health # Check service health make stop # Stop the testnet make build-all # Build all components make validate # Validate configuration make backup # Backup testnet data

Direct script usage

./scripts/run-all-tests.sh # Run all test categories ./tests/scripts/run-all-tests.sh --category e2e ./tests/scripts/run-all-tests.sh --category performance ./tests/scripts/run-all-tests.sh --category security ./tests/scripts/run-all-tests.sh --category cortex-demos ./scripts/run-tests.sh # Run integration tests (default) ./scripts/run-tests.sh --all # Run all test categories ./scripts/run-tests.sh --category e2e ./scripts/run-tests.sh --category performance ./scripts/run-tests.sh --category security ./scripts/run-tests.sh --category cortex-demos ./scripts/start-testnet.sh # Start all services ./scripts/stop-testnet.sh # Stop all services ./scripts/health-check.sh # Check service health ./scripts/validate-config.sh # Validate configuration ./scripts/kill_knirv.sh # Force kill all KNIRV processes

`

Category-Specific Testing

`bash ./tests/scripts/run-all-tests.sh --category e2e # End-to-end tests ./tests/scripts/run-all-tests.sh --category performance # Load testing ./tests/scripts/run-all-tests.sh --category security # Security validation ./tests/scripts/run-all-tests.sh --category cortex-demos # CORTEX integration

Skip testnet startup (if already running)

./tests/scripts/run-all-tests.sh --no-start

Keep environment for debugging

./tests/scripts/run-all-tests.sh --no-cleanup `

Advanced Orchestrator Usage

`bash

Manual orchestrator for spot testing

cd tests/automation ./orchestrator --scenario load-test --duration 5m ./orchestrator --scenario service-health --services all ./orchestrator --help # View all available options `

Make Commands

`bash

Complete testnet testing

make testnet-tests

Individual commands

make start # Start testnet make test # Run integration tests make health # Check service health make stop # Stop testnet `

Service Management

`bash

Start/stop services

./scripts/start-testnet.sh # Start all services ./scripts/stop-testnet.sh # Stop all services ./scripts/health-check.sh # Check service health

Individual service management

make build-all # Build all components make validate # Validate configuration make backup # Backup testnet data `

Options: - -v/--verbose: Show detailed output - -t/--timeout SEC: Set HTTP timeout (default: 10s)

Test Categories

End-to-End Tests (31/31 PASSING)

- User Journey Tests: Complete workflow validation (17/17 passing) - Cross-Service Integration: Service interaction validation (14/14 passing) - Economic Loop Tests: Blockchain transaction flow validation - CORTEX Demo Suite: AI agent framework testing

Performance Tests (ALL PASSING)

- Load Testing: 50+ concurrent requests with 95%+ success rate - Sustained Load: 30-second continuous testing - Response Time Analysis: Sub-second response validation - Memory Leak Detection: Long-running stability tests

Security Tests (ALL PASSING)

- Authentication Validation: Testnet token system testing - Input Sanitization: SQL injection and XSS prevention - Security Headers: CORS and security header validation - Rate Limiting: Rapid request handling tests

CORTEX Demos (INTEGRATED)

- Skill Development: Single agent learning scenarios - Multi-Agent Collaboration: Distributed agent coordination - Learning Adaptation: Cognitive processing validation

Test Execution Options

System Validation Tests

Dependency Check

Purpose: Verify all required dependencies are installed Command: make validate or ./scripts/validate-config.sh Expected Results: - ✅ Go 1.19+ detected - ✅ Rust/Cargo detected - ✅ Node.js 18+ detected - ✅ Python 3.8+ detected - ✅ All ports available (1317, 8080, 8081, 8082, 5001, 8888)

Configuration Validation

Purpose: Ensure all services are properly configured for testnet Command: ./scripts/validate-config.sh --verbose Expected Results: - ✅ All binary files exist in bin/ directory - ✅ All configuration files exist with correct testnet settings - ✅ Directory structure is complete - ✅ Environment variables are properly set

Service Health Tests

Individual Service Health

Purpose: Verify each service starts and responds to health checks Command: make health or ./scripts/health-check.sh Expected Results: (Example output) ` Service Status: ✓ KNIRV-ORACLE HEALTHY PID:12345 45ms http://localhost:1317/health ✓ KNIRVCHAIN HEALTHY PID:12346 32ms http://localhost:8080/health ✓ KNIRVGRAPH HEALTHY PID:12347 28ms http://localhost:8081/health ✓ KNIRV-NEXUS HEALTHY PID:12348 41ms http://localhost:8082/health ✓ KNIRV-ROUTER HEALTHY PID:12349 35ms http://localhost:5001/health ✓ KNIRV-GATEWAY HEALTHY PID:12350 22ms http://localhost:8888/gateway/health

Overall Status: All services are healthy (6/6) `

Continuous Health Monitoring

Purpose: Monitor service stability over time Command: ./scripts/health-check.sh --watch --detailed Expected Results: - Services remain healthy over extended periods - Response times stay consistent - No service crashes or restarts

Integration Tests

Service Discovery

Purpose: Verify gateway can discover all services Command: make test-integration or ./scripts/test-integration.sh Test: Gateway service discovery Expected Results: - ✅ Gateway discovers knirvoracle - ✅ Gateway discovers knirvchain - ✅ Gateway discovers knirvgraph - ✅ Gateway discovers knirvnexus - ✅ Gateway discovers knirvrouter

Authentication System

Purpose: Test simplified testnet authentication Command: ./scripts/test-integration.sh Test: Authentication system Expected Results: - ✅ Testnet authentication tokens available - ✅ Token validation works correctly

Cross-Service Communication

Purpose: Verify services can communicate with each other Command: ./scripts/test-integration.sh Test: Cross-service communication Expected Results: - ✅ KNIRVCHAIN mock LLM validation works - ✅ KNIRVCHAIN mock skill validation works - ✅ KNIRV-NEXUS TEE simulation works

Testnet-Specific Feature Tests

Mock LLM Validation

Purpose: Test KNIRVCHAIN mock LLM validation endpoint Manual Test: `bash curl -X POST http://localhost:8080/testnet/llm/validate \ -H "Content-Type: application/json" \ -d '{"model_id":"test-model"}' ` Expected Response: `json { "success": true, "model_id": "test-model", "accuracy": 0.92, "latency_ms": 45, "throughput_tokens_per_sec": 120, "validation_result": "Mock validation completed" } `

Mock Skill Validation

Purpose: Test KNIRVCHAIN mock skill validation endpoint Manual Test: `bash curl -X POST http://localhost:8080/testnet/skill/validate \ -H "Content-Type: application/json" \ -d '{"skill_id":"test-skill","skill_code":"console.log(\"test\")"}' ` Expected Response: `json { "success": true, "skill_id": "test-skill", "validation_passed": true, "execution_time_ms": 150, "test_results": { "passed": 9, "failed": 1, "total": 10 } } `

TEE Simulation

Purpose: Test KNIRV-NEXUS TEE simulation endpoint Manual Test: `bash curl -X POST http://localhost:8182/testnet/validate/skill \ -H "Content-Type: application/json" \ -d '{ "skill_code": "test code", "test_cases": [ {"input": "test", "expected": "test", "name": "basic test"} ] }' ` Expected Response: `json { "valid": true, "proof": "a1b2c3d4...", "execution_time": "100ms", "test_results": { "passed": 1, "failed": 0, "total": 1 }, "timestamp": "2025-08-06T..." } `

Gateway Proxy Tests

Service Proxying

Purpose: Test gateway's ability to proxy requests to services Manual Tests: `bash

Test proxy to KNIRV-ORACLE

curl http://localhost:8888/knirvoracle/health

Test gateway endpoints

curl http://localhost:8888/gateway/health curl http://localhost:8888/gateway/services curl http://localhost:8888/gateway/testnet/status

Test authentication endpoints

curl http://localhost:8888/auth/testnet-tokens curl -H "Authorization: Bearer testnet-token-123" \ http://localhost:8888/auth/validate `

Configuration

Environment Variables

- TESTNET_MODE: Set to "true" for testnet-specific behavior - TESTNET_TIMEOUT: Override default timeout (seconds) - TEST_PARALLEL: Enable parallel test execution (default: true) - TEST_CLEANUP: Enable cleanup on exit (default: true)

Port Configuration

Edit ports.config to change service ports. The test suite automatically discovers actual ports.

Test Configuration

- tests/config/: Test-specific configuration files - tests/automation/go.mod: Orchestrator dependencies - Individual test directories have their own go.mod files

Orchestrator Integration

Automatic Integration

- ✅ Built automatically when running test suite - ✅ CORTEX demos use orchestrator for multi-agent scenarios - ✅ Available for manual testing with custom scenarios

Manual Usage

`bash

Build orchestrator

cd tests/automation go build -o orchestrator ./cmd/orchestrator

Run custom scenarios

./orchestrator --help ./orchestrator --scenario custom-test --config my-config.json `

Test Reports

Generated Reports

- HTML Reports: tests/reports/test_suite_report_YYYYMMDD_HHMMSS.html - Individual Logs: Each test category generates detailed logs - Metrics: Success rates, response times, error counts

Viewing Reports

`bash

Latest report

open tests/reports/test_suite_report_*.html

All reports

ls -la tests/reports/ `

Troubleshooting

Common Issues

1. Services not responding: - Run make health or ./scripts/health-check.sh to verify services - Check logs in ./logs/ directory - Restart services: make restart or ./scripts/stop-testnet.sh && ./scripts/start-testnet.sh

2. Test failures: - Check if testnet is running: curl http://localhost:8888/gateway/health - Use --no-cleanup flag to inspect state after failure - Run specific test category to isolate issues

3. Port conflicts: - Tests automatically discover ports - no manual configuration needed - Check ports.config if services fail to start

Common Test Failures

Service Won't Start

Symptoms: Health check shows service as STOPPED Diagnosis: `bash

Check logs

tail -f logs/servicename.log

Check if binary exists

ls -la bin/servicename

Check port conflicts

lsof -i :PORT ` Solutions: - Rebuild the service: ./scripts/build-servicename.sh - Kill conflicting processes: kill $(lsof -t -i:PORT) - Check configuration files

Health Check Fails

Symptoms: Service shows as UNHEALTHY Diagnosis: `bash

Test endpoint manually

curl -v http://localhost:PORT/health

Check service logs

tail -f logs/servicename.log

Verify process is running

ps aux | grep servicename ` Solutions: - Restart the service - Check service configuration - Verify dependencies are met

Integration Tests Fail

Symptoms: ./test-integration.sh reports failures Diagnosis: `bash

Run with verbose output

./test-integration.sh --verbose

Check individual endpoints

curl http://localhost:8080/testnet/status curl http://localhost:8888/gateway/services `

Solutions: - Ensure all services are running: make start or ./scripts/start-testnet.sh - Check service logs: tail -f logs/*.log - Verify port availability: netstat -tulpn | grep :8080 - Restart services if needed: make restart - Check configuration files in config/ directory

3. Test Failures

`bash

Run specific test category to isolate issues

make test-e2e make test-performance

Run with verbose output for debugging

./scripts/run-tests.sh --category integration --verbose

Check test logs

tail -f tests/logs/*.log `

Solutions: - Review test logs for specific error messages - Ensure testnet is fully started before running tests - Check network connectivity and firewall settings - Verify test data and configuration files - Run tests individually to isolate failing components

4. Performance Issues

`bash

Monitor system resources

./scripts/monitor-resources.sh

Check service health with detailed metrics

make health --detailed

Run performance benchmarks

make test-performance `

Solutions: - Increase system resources (RAM, CPU) if needed - Optimize service configurations for your environment - Check for resource-intensive processes - Monitor network latency and bandwidth - Consider running fewer concurrent services for development

📊 Test Metrics and Benchmarks

Expected Performance Metrics

- Service Startup Time: < 30 seconds for all services - API Response Time: < 200ms for standard operations - Test Execution Time: < 10 minutes for full test suite - Memory Usage: < 4GB total for all services - CPU Usage: < 50% on modern multi-core systems

Test Coverage

- Unit Tests: 85%+ code coverage across all components - Integration Tests: 95%+ API endpoint coverage - End-to-End Tests: 90%+ user journey coverage - Performance Tests: 100% critical path coverage - Security Tests: 100% authentication and authorization coverage

Benchmark Results

` Service Startup Times: - KNIRV-ORACLE: ~8 seconds - KNIRVCHAIN: ~12 seconds - KNIRVGRAPH: ~10 seconds - KNIRV-NEXUS: ~15 seconds - KNIRV-ROUTER: ~6 seconds - KNIRV-GATEWAY: ~20 seconds

API Performance: - Health checks: ~50ms - Token operations: ~150ms - Skill invocations: ~300ms - Graph queries: ~100ms - Cross-service calls: ~200ms `

🔄 Test Automation

Continuous Testing

The testnet supports continuous integration and automated testing:

`bash

Set up automated testing

./scripts/setup-ci.sh

Run in CI mode

make testnet-tests --ci

Generate CI reports

make test-reports --format junit `

Automated Test Suite

- Scheduled Tests: Automated daily test execution - Regression Testing: Automatic testing on code changes - Performance Monitoring: Continuous performance benchmarking - Health Monitoring: 24/7 service health checks - Alert System: Automated notifications for test failures

📈 Test Reporting

Generate Test Report

`bash

Generate comprehensive test report

make test-reports

Generate specific category reports

make test-reports --category e2e make test-reports --category performance

Export reports in different formats

make test-reports --format html make test-reports --format json make test-reports --format junit `

Test Results Analysis

- Pass/Fail Rates: Detailed statistics for all test categories - Performance Trends: Historical performance data and trends - Coverage Reports: Code coverage analysis and recommendations - Failure Analysis: Root cause analysis for test failures - Improvement Recommendations: Suggestions for test suite optimization

🛑 Shutdown and Cleanup

Graceful Shutdown

`bash

Stop all services gracefully

make stop

Or use the direct script

./scripts/stop-testnet.sh

Emergency shutdown if needed

./scripts/kill_knirv.sh `

Cleanup Operations

`bash

Clean temporary files and logs

make clean

Deep cleanup including data

make clean-all

Reset testnet to initial state

./scripts/reset-testnet.sh `

Data Management

- Log Rotation: Automatic log file rotation and archival - Data Backup: Regular backup of important testnet data - State Reset: Easy reset to clean testnet state - Configuration Backup: Backup and restore of configuration files

🔗 Integration with KNIRV Ecosystem

Ecosystem Components

- KNIRVCHAIN: Blockchain layer with smart contract execution - KNIRVGRAPH: Graph database for network topology and analytics - KNIRV-NEXUS: Distributed validation environment for AI agents - KNIRV-ROUTER: Network routing and connectivity management - KNIRV-GATEWAY: API gateway and service orchestration - KNIRVSDK: Software development kit for application integration

Cross-Component Testing

The testnet validates interactions between all ecosystem components: - Service discovery and registration - Cross-service API communication - Data consistency across components - Event propagation and handling - Error handling and recovery

🎯 Best Practices

Development Workflow

1. Start Clean: Always start with a clean testnet state 2. Incremental Testing: Test individual components before integration 3. Monitor Resources: Keep an eye on system resource usage 4. Regular Cleanup: Clean logs and temporary files regularly 5. Version Control: Track configuration changes and test results

Testing Guidelines

- Test Early: Run tests frequently during development - Test Thoroughly: Use all test categories for comprehensive validation - Document Issues: Record and track any issues or anomalies - Share Results: Communicate test results with the development team - Continuous Improvement: Regularly update and improve test coverage

📚 Additional Resources

Documentation

- KNIRV Network Documentation - Testing Best Practices - Deployment Guide - API Reference

Community

- KNIRV GitHub - Discord Community - Developer Forum - Bug Reports

---

KNIRV TESTNET - Comprehensive Testing Infrastructure for the Decentralized Future

Built with ❤️ by the KNIRV Network Community

© 2024 KNIRV Network. All rights reserved.