aitbc/tests/integration/README.md

# OpenClaw Agent Marketplace Test Suite

Comprehensive test suite for the OpenClaw Agent Marketplace implementation covering Phase 8-10 of the AITBC roadmap.

## 🎯 Test Coverage

### Phase 8: Global AI Power Marketplace Expansion (Weeks 1-6)

#### 8.1 Multi-Region Marketplace Deployment (Weeks 1-2)
- **File**: `test_multi_region_deployment.py`
- **Coverage**:
  - Geographic load balancing for marketplace transactions
  - Edge computing nodes for AI power trading globally
  - Multi-region redundancy and failover mechanisms
  - Global marketplace monitoring and analytics
  - Performance targets: <100ms response time, 99.9% uptime

#### 8.2 Blockchain Smart Contract Integration (Weeks 3-4)
- **File**: `test_blockchain_integration.py`
- **Coverage**:
  - AI power rental smart contracts
  - Payment processing contracts
  - Escrow services for transactions
  - Performance verification contracts
  - Dispute resolution mechanisms
  - Dynamic pricing contracts

#### 8.3 OpenClaw Agent Economics Enhancement (Weeks 5-6)
- **File**: `test_agent_economics.py`
- **Coverage**:
  - Advanced agent reputation and trust systems
  - Performance-based reward mechanisms
  - Agent-to-agent AI power trading protocols
  - Marketplace analytics and economic insights
  - Agent certification and partnership programs

### Phase 9: Advanced Agent Capabilities & Performance (Weeks 7-12)

#### 9.1 Enhanced OpenClaw Agent Performance (Weeks 7-9)
- **File**: `test_advanced_agent_capabilities.py`
- **Coverage**:
  - Advanced meta-learning for faster skill acquisition
  - Self-optimizing agent resource management
  - Multi-modal agent fusion for enhanced capabilities
  - Advanced reinforcement learning for marketplace strategies
  - Agent creativity and specialized AI capability development

#### 9.2 Marketplace Performance Optimization (Weeks 10-12)
- **File**: `test_performance_optimization.py`
- **Coverage**:
  - GPU acceleration and resource utilization optimization
  - Distributed agent processing frameworks
  - Advanced caching and optimization for marketplace data
  - Real-time marketplace performance monitoring
  - Adaptive resource scaling for marketplace demand

### Phase 10: OpenClaw Agent Community & Governance (Weeks 13-18)

#### 10.1 Agent Community Development (Weeks 13-15)
- **File**: `test_agent_governance.py`
- **Coverage**:
  - Comprehensive OpenClaw agent development tools and SDKs
  - Agent innovation labs and research programs
  - Marketplace for third-party agent solutions
  - Agent community support and collaboration platforms

#### 10.2 Decentralized Agent Governance (Weeks 16-18)
- **Coverage**:
  - Token-based voting and governance mechanisms
  - Decentralized autonomous organization (DAO) for agent ecosystem
  - Community proposal and voting systems
  - Governance analytics and transparency reporting
  - Agent certification and partnership programs

## 🚀 Quick Start

### Prerequisites

- Python 3.13+
- pytest with plugins:
  ```bash
  pip install pytest pytest-asyncio pytest-json-report httpx requests numpy psutil
  ```

### Running Tests

#### Run All Test Suites
```bash
cd tests/openclaw_marketplace
python run_all_tests.py
```

#### Run Individual Test Suites
```bash
# Framework tests
pytest test_framework.py -v

# Multi-region deployment tests
pytest test_multi_region_deployment.py -v

# Blockchain integration tests
pytest test_blockchain_integration.py -v

# Agent economics tests
pytest test_agent_economics.py -v

# Advanced agent capabilities tests
pytest test_advanced_agent_capabilities.py -v

# Performance optimization tests
pytest test_performance_optimization.py -v

# Governance tests
pytest test_agent_governance.py -v
```

#### Run Specific Test Classes
```bash
# Test only marketplace health
pytest test_multi_region_deployment.py::TestRegionHealth -v

# Test only smart contracts
pytest test_blockchain_integration.py::TestAIPowerRentalContract -v

# Test only agent reputation
pytest test_agent_economics.py::TestAgentReputationSystem -v
```

## 📊 Test Metrics and Targets

### Performance Targets
- **Response Time**: <50ms for marketplace operations
- **Throughput**: >1000 requests/second
- **GPU Utilization**: >90% efficiency
- **Cache Hit Rate**: >85%
- **Uptime**: 99.9% availability globally

### Economic Targets
- **AITBC Trading Volume**: 10,000+ daily
- **Agent Participation**: 5,000+ active agents
- **AI Power Transactions**: 1,000+ daily rentals
- **Transaction Speed**: <30 seconds settlement
- **Payment Reliability**: 99.9% success rate

### Governance Targets
- **Proposal Success Rate**: >60% approval threshold
- **Voter Participation**: >40% quorum
- **Trust System Accuracy**: >95%
- **Transparency Rating**: >80%

## 🛠️ CLI Tools

The enhanced marketplace CLI provides comprehensive operations:

### Agent Operations
```bash
# Register agent
aitbc marketplace agents register --agent-id agent001 --agent-type compute_provider --capabilities "gpu_computing,ai_inference"

# List agents
aitbc marketplace agents list --agent-type compute_provider --reputation-min 0.8

# List AI resource
aitbc marketplace agents list-resource --resource-id gpu001 --resource-type nvidia_a100 --price-per-hour 2.5

# Rent AI resource
aitbc marketplace agents rent --resource-id gpu001 --consumer-id consumer001 --duration 4

# Check agent reputation
aitbc marketplace agents reputation --agent-id agent001

# Check agent balance
aitbc marketplace agents balance --agent-id agent001
```

### Governance Operations
```bash
# Create proposal
aitbc marketplace governance create-proposal --title "Reduce Fees" --proposal-type parameter_change --params '{"transaction_fee": 0.02}'

# Vote on proposal
aitbc marketplace governance vote --proposal-id prop001 --vote for --reasoning "Good for ecosystem"

# List proposals
aitbc marketplace governance list-proposals --status active
```

### Blockchain Operations
```bash
# Execute smart contract
aitbc marketplace agents execute-contract --contract-type ai_power_rental --params '{"resourceId": "gpu001", "duration": 4}'

# Process payment
aitbc marketplace agents pay --from-agent consumer001 --to-agent provider001 --amount 10.0
```

### Testing Operations
```bash
# Run load test
aitbc marketplace test load --concurrent-users 50 --rps 100 --duration 60

# Check health
aitbc marketplace test health
```

## 📈 Test Reports

### JSON Reports
Test results are automatically saved in JSON format:
- `test_results.json` - Comprehensive test run results
- Individual suite reports in `/tmp/test_report.json`

### Report Structure
```json
{
  "test_run_summary": {
    "start_time": "2026-02-26T12:00:00",
    "end_time": "2026-02-26T12:05:00",
    "total_duration": 300.0,
    "total_suites": 7,
    "passed_suites": 7,
    "failed_suites": 0,
    "success_rate": 100.0
  },
  "suite_results": {
    "framework": { ... },
    "multi_region": { ... },
    ...
  },
  "recommendations": [ ... ]
}
```

## 🔧 Configuration

### Environment Variables
```bash
# Marketplace configuration
export AITBC_COORDINATOR_URL="http://127.0.0.1:18000"
export AITBC_API_KEY="your-api-key"

# Test configuration
export PYTEST_JSON_REPORT_FILE="/tmp/test_report.json"
export AITBC_TEST_TIMEOUT=30
```

### Test Configuration
Tests can be configured via pytest configuration:
```ini
[tool:pytest]
testpaths = .
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = -v --tb=short --json-report --json-report-file=/tmp/test_report.json
asyncio_mode = auto
```

## 🐛 Troubleshooting

### Common Issues

#### Test Failures
1. **Connection Errors**: Check marketplace service is running
2. **Timeout Errors**: Increase `AITBC_TEST_TIMEOUT`
3. **Authentication Errors**: Verify API key configuration

#### Performance Issues
1. **Slow Tests**: Check system resources and GPU availability
2. **Memory Issues**: Reduce concurrent test users
3. **Network Issues**: Verify localhost connectivity

#### Debug Mode
Run tests with additional debugging:
```bash
pytest test_framework.py -v -s --tb=long --log-cli-level=DEBUG
```

## 📝 Test Development

### Adding New Tests
1. Create test class inheriting from appropriate base
2. Use async/await for async operations
3. Follow naming convention: `test_*`
4. Add comprehensive assertions
5. Include error handling

### Test Structure
```python
class TestNewFeature:
    @pytest.mark.asyncio
    async def test_new_functionality(self, test_fixture):
        # Arrange
        setup_data = {...}
        
        # Act
        result = await test_function(setup_data)
        
        # Assert
        assert result.success is True
        assert result.data is not None
```

## 🎯 Success Criteria

### Phase 8 Success
- ✅ Multi-region deployment with <100ms latency
- ✅ Smart contract execution with <30s settlement
- ✅ Agent economics with 99.9% payment reliability

### Phase 9 Success
- ✅ Advanced agent capabilities with meta-learning
- ✅ Performance optimization with >90% GPU utilization
- ✅ Marketplace throughput >1000 req/s

### Phase 10 Success
- ✅ Community tools with comprehensive SDKs
- ✅ Governance systems with token-based voting
- ✅ DAO formation with transparent operations

## 📞 Support

For test-related issues:
1. Check test reports for detailed error information
2. Review logs for specific failure patterns
3. Verify environment configuration
4. Consult individual test documentation

## 🚀 Next Steps

After successful test completion:
1. Deploy to staging environment
2. Run integration tests with real blockchain
3. Conduct security audit
4. Performance testing under production load
5. Deploy to production with monitoring

---

**Note**: This test suite is designed for the OpenClaw Agent Marketplace implementation and covers all aspects of Phase 8-10 of the AITBC roadmap. Ensure all prerequisites are met before running tests.