aitbc/tests/docs/README.md

AITBC Test Suite - Updated Structure

This directory contains the comprehensive test suite for the AITBC platform, including unit tests, integration tests, end-to-end tests, security tests, and load tests.

Recent Updates (March 30, 2026)

✅ Structure Improvements Completed

• Scripts Organization: Test scripts moved to scripts/testing/ and scripts/utils/
• Logs Consolidation: All test logs now in /var/log/aitbc/
• Virtual Environment: Using central /opt/aitbc/venv
• Development Environment: Using /etc/aitbc/.env for configuration

Table of Contents

1. Test Structure
2. Prerequisites
3. Running Tests
4. Test Types
5. Configuration
6. CI/CD Integration
7. Troubleshooting

Test Structure

tests/
├── conftest.py              # Shared fixtures and configuration
├── test_runner.py          # Test suite runner script
├── load_test.py            # Load testing utilities
├── integration_test.sh     # Integration test shell script
├── docs/                   # Test documentation
│   ├── README.md
│   ├── USAGE_GUIDE.md
│   ├── TEST_REFACTORING_COMPLETED.md
│   └── test-integration-completed.md
├── e2e/                    # End-to-end tests
├── fixtures/               # Test fixtures and data
├── openclaw_marketplace/   # OpenClaw marketplace tests
├── .pytest_cache/          # Pytest cache (auto-generated)
└── __pycache__/            # Python cache (auto-generated)

Related Test Scripts

scripts/testing/           # Main testing scripts
├── comprehensive_e2e_test_fixed.py  # Comprehensive E2E testing
├── test_workflow.sh               # Workflow testing
├── run_all_tests.sh               # All tests runner
└── test-all-services.sh           # Service testing

scripts/utils/             # Testing utilities
├── requirements_migrator.py       # Dependency management
└── other utility scripts          # Various helper scripts

Prerequisites

Environment Setup

# Run main project setup (if not already done)
./setup.sh

# Activate central virtual environment
source /opt/aitbc/venv/bin/activate

# Ensure test dependencies are installed
pip install pytest pytest-cov pytest-asyncio

# Set environment configuration
source /etc/aitbc/.env  # Central environment configuration

Service Requirements

• AITBC blockchain node running
• Coordinator API service active
• Database accessible (SQLite/PostgreSQL)
• GPU services (if running AI tests)

Running Tests

Quick Start

# Run all fast tests
python tests/test_runner.py

# Run comprehensive test suite
python tests/test_runner.py --all

# Run with coverage
python tests/test_runner.py --coverage

Specific Test Types

# Unit tests only
python tests/test_runner.py --unit

# Integration tests only
python tests/test_runner.py --integration

# CLI tests only
python tests/test_runner.py --cli

# Performance tests
python tests/test_runner.py --performance

Advanced Testing

# Comprehensive E2E testing
python scripts/testing/comprehensive_e2e_test_fixed.py

# Workflow testing
bash scripts/testing/test_workflow.sh

# All services testing
bash scripts/testing/test-all-services.sh

Test Types

Unit Tests

• Location: tests/unit/ (if exists)
• Purpose: Test individual components in isolation
• Speed: Fast (< 1 second per test)
• Coverage: Core business logic

Integration Tests

• Location: tests/integration/ and tests/e2e/
• Purpose: Test component interactions
• Speed: Medium (1-10 seconds per test)
• Coverage: API endpoints, database operations

End-to-End Tests

• Location: tests/e2e/ and scripts/testing/
• Purpose: Test complete workflows
• Speed: Slow (10-60 seconds per test)
• Coverage: Full user scenarios

Performance Tests

• Location: tests/load_test.py
• Purpose: Test system performance under load
• Speed: Variable (depends on test parameters)
• Coverage: API response times, throughput

Configuration

Test Configuration Files

• pytest.ini: Pytest configuration (in root)
• conftest.py: Shared fixtures and configuration
• pyproject.toml: Project-wide test configuration

Environment Variables

# Test database (different from production)
TEST_DATABASE_URL=sqlite:///test_aitbc.db

# Test logging
TEST_LOG_LEVEL=DEBUG
TEST_LOG_FILE=/var/log/aitbc/test.log

# Test API endpoints
# Note: Port 8011 = Learning Service (updated port allocation)
TEST_API_BASE_URL=http://localhost:8011

CI/CD Integration

GitHub Actions

Test suite is integrated with CI/CD pipeline:

• Unit Tests: Run on every push
• Integration Tests: Run on pull requests
• E2E Tests: Run on main branch
• Performance Tests: Run nightly

Local CI Simulation

# Simulate CI pipeline locally
python tests/test_runner.py --all --coverage

# Generate coverage report
coverage html -o coverage_html/

Troubleshooting

Common Issues

Test Failures Due to Services

# Check service status
systemctl status aitbc-blockchain-node
systemctl status aitbc-coordinator

# Restart services if needed
sudo systemctl restart aitbc-blockchain-node
sudo systemctl restart aitbc-coordinator

Environment Issues

# Check virtual environment
which python
python --version

# Check dependencies
pip list | grep pytest

# Reinstall if needed
pip install -e .

Database Issues

# Reset test database
rm test_aitbc.db
python -m alembic upgrade head

# Check database connectivity
python -c "from aitbc_core.db import engine; print(engine.url)"

Test Logs

All test logs are now centralized in /var/log/aitbc/:

• test.log: General test output
• test_results.txt: Test results summary
• performance_test.log: Performance test results

Getting Help

1. Check test logs in /var/log/aitbc/
2. Review test documentation in tests/docs/
3. Run tests with verbose output: pytest -v
4. Check service status and configuration

---

Last updated: March 30, 2026
For questions or suggestions, please open an issue or contact the development team.

---

Last updated: March 30, 2026 For questions or suggestions, please open an issue or contact the development team.