mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-23 20:21:03 +02:00
Tests README (in wrong directory)
This commit is contained in:
Cyber MacGeddon
parent
3cdb4cd74b
commit
709f270a1a
1 changed files with 238 additions and 0 deletions
238
trustgraph-base/tests/README.md
Normal file
238
trustgraph-base/tests/README.md
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
# 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:**
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
pytest tests/test_api_integration.py -v
|
||||
```
|
||||
|
||||
### Running Specific Test Classes
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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`:
|
||||
```python
|
||||
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:
|
||||
```python
|
||||
@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:
|
||||
|
||||
```yaml
|
||||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue