trustgraph/trustgraph-base/tests/README.md

TrustGraph Python API Integration Tests

This directory contains integration tests for the TrustGraph Python API refactor.

Overview

The integration tests verify the following components:

• Basic API instantiation and client creation
• REST API functionality (synchronous and asynchronous)
• WebSocket API functionality (synchronous and asynchronous)
• Bulk operations for data import/export
• Metrics endpoints
• Streaming types and data structures

Prerequisites

1. Python dependencies:

   pip install pytest pytest-asyncio
   

2. Running TrustGraph Gateway API:

   • The tests require a running TrustGraph Gateway API server
   • Default URL: http://localhost:8088/
   • Configure via environment variables (see below)

Running the Tests

Quick Start (No Gateway Required)

To run tests in "skip mode" (validates structure without requiring a running server):

export SKIP_INTEGRATION_TESTS=true
pytest tests/test_api_integration.py -v

Full Integration Tests (Requires Running Gateway)

1. Start your TrustGraph Gateway API server

2. Configure environment variables:

   export TRUSTGRAPH_URL=http://localhost:8088/
   export TRUSTGRAPH_TOKEN=your-auth-token-here  # Optional
   export TRUSTGRAPH_TEST_FLOW=test-flow         # Optional
   export SKIP_INTEGRATION_TESTS=false           # Enable tests
   

3. Run the tests:

   pytest tests/test_api_integration.py -v
   

Running Specific Test Classes

# Test only REST API
pytest tests/test_api_integration.py::TestRESTAPI -v

# Test only WebSocket API
pytest tests/test_api_integration.py::TestWebSocketAPI -v

# Test only async functionality
pytest tests/test_api_integration.py::TestAsyncRESTAPI -v
pytest tests/test_api_integration.py::TestAsyncWebSocketAPI -v

# Test only bulk operations
pytest tests/test_api_integration.py::TestBulkOperations -v

# Test only metrics
pytest tests/test_api_integration.py::TestMetrics -v

Running with Coverage

pytest tests/test_api_integration.py --cov=trustgraph.api --cov-report=html

Environment Variables

Variable	Description	Default
TRUSTGRAPH_URL	Gateway API URL	http://localhost:8088/
TRUSTGRAPH_TOKEN	Authentication token	None
TRUSTGRAPH_TEST_FLOW	Flow ID for testing	test-flow
SKIP_INTEGRATION_TESTS	Skip tests requiring live server	false

Test Categories

1. Basic Connection Tests (TestBasicConnection)

• API instantiation with/without token
• Context manager support
• Lazy initialization of clients

2. REST API Tests (TestRESTAPI)

• Flow listing
• Flow class listing
• Flow instance creation
• Method existence verification

3. Async REST API Tests (TestAsyncRESTAPI)

• Async flow operations
• Async context manager
• Async/await patterns

4. WebSocket API Tests (TestWebSocketAPI)

• WebSocket client creation
• Flow instance creation
• Method availability
• URL conversion (HTTP → WS)

5. Async WebSocket API Tests (TestAsyncWebSocketAPI)

• Async WebSocket operations
• Streaming support verification
• Method signatures

6. Bulk Operations Tests (TestBulkOperations)

• Bulk client instantiation
• Import/export methods
• Async bulk operations
• Iterator-based data transfer

7. Metrics Tests (TestMetrics)

• Metrics endpoint access
• Prometheus format validation
• Async metrics retrieval

8. Streaming Types Tests (TestStreamingTypes)

• AgentThought chunk creation
• AgentObservation chunk creation
• AgentAnswer chunk creation
• RAGChunk creation

9. Triple Type Tests (TestTripleType)

• Triple data structure validation

Test Structure

tests/
├── __init__.py                  # Test package marker
├── README.md                    # This file
└── test_api_integration.py      # Main integration test suite

Adding New Tests

To add new integration tests:

1. Create a new test class in test_api_integration.py:

   class TestNewFeature:
       """Test new feature functionality"""
   
       @skip_if_no_gateway
       def test_new_feature(self):
           api = Api(url=GATEWAY_URL, token=AUTH_TOKEN)
           # Your test code here
           assert result is not None
   

2. Add the @skip_if_no_gateway decorator to tests requiring a live server

3. Use pytest.mark.asyncio for async tests:

   @skip_if_no_gateway
   @pytest.mark.asyncio
   async def test_async_feature(self):
       api = Api(url=GATEWAY_URL, token=AUTH_TOKEN)
       result = await api.async_flow().list()
       assert isinstance(result, list)
   

Continuous Integration

For CI/CD pipelines:

# Example GitHub Actions workflow
- name: Run Integration Tests
  env:
    TRUSTGRAPH_URL: http://localhost:8088/
    SKIP_INTEGRATION_TESTS: false
  run: |
    # Start Gateway API in background
    ./start-gateway.sh &
    sleep 10

    # Run tests
    pytest tests/test_api_integration.py -v

    # Stop Gateway API
    ./stop-gateway.sh

Troubleshooting

Tests are skipped

• Check that SKIP_INTEGRATION_TESTS is set to false
• Verify the Gateway API is running at the configured URL

Connection errors

• Verify TRUSTGRAPH_URL is correct
• Check that the Gateway API is accessible
• Ensure firewall rules allow connections

Authentication errors

• Verify TRUSTGRAPH_TOKEN is set correctly
• Check token validity with the Gateway API

Timeout errors

• Increase timeout in Api instantiation
• Check Gateway API performance
• Verify network connectivity

Future Enhancements

Planned test additions:

• End-to-end streaming tests (requires live LLM)
• Bulk operation performance tests
• Error handling and edge cases
• WebSocket reconnection scenarios
• Token refresh mechanisms
• Multi-flow coordination tests

Contributing

When adding new API features:

1. Add corresponding integration tests
2. Document environment variables if needed
3. Update this README with new test categories
4. Ensure tests can run in skip mode for CI

License

Same as TrustGraph project license.