Synced from the repo — do not edit here

Canonical source: TESTING_GUIDE.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Testing Guide for Enhanced Basis Features

This guide provides comprehensive testing strategies for all the new enhanced features implemented:

1. Terra Cache Manager - Firestore caching for Terra data
2. Enhanced AI Copilot - Comprehensive data querying
3. LLM Selector UI - Model selection interface
4. Enhanced Chat Interface - Cursor-like chat experience
5. Canvas Reports - Health data visualization

🚀 Quick Start Testing

Prerequisites

# Python dependencies
cd basis-functions
pip install pytest pytest-asyncio

# Flutter dependencies
cd hybrid/basishybrid
flutter pub get
flutter test

Run All Tests

# Backend tests
cd basis-functions
python -m pytest functions/test/test_enhanced_features.py -v

# Frontend tests  
cd hybrid/basishybrid
flutter test test/enhanced_features_test.dart

---

1. Terra Cache Manager Testing

Unit Tests

# Run cache manager tests
python -m pytest functions/test/test_enhanced_features.py::TestTerraCacheManager -v

Manual Testing - Cache Operations

# Test cache update
from src.terra_cache_manager import TerraCacheManager

async def test_cache_manually():
    cache_manager = TerraCacheManager('test_user_123')
    
    # Update cache from DuckDB
    result = await cache_manager.update_cache_from_duckdb(['hr', 'glucose'])
    print(f"Cache update result: {result}")
    
    # Get cached summary
    summary = await cache_manager.get_cached_summary('hr')
    print(f"HR summary: {summary}")
    
    # Get recent data
    recent = await cache_manager.get_recent_cached_data('hr')
    print(f"Recent HR data: {len(recent)} records")

# Run with asyncio
import asyncio
asyncio.run(test_cache_manually())

Integration Testing - Terra Webhook → Cache

# Simulate Terra webhook processing
from src.terra_adapter import process_terra_webhook_with_gcs
from src.terra_cache_manager import update_terra_cache_on_webhook

# Mock Terra webhook data
mock_webhook = {
    "type": "body",
    "user": {"user_id": "test_user"},
    "data": [{
        "heart_rate_data": {
            "detailed": {
                "hr_samples": [
                    {"timestamp": "2024-01-01T10:00:00Z", "bpm": 75},
                    {"timestamp": "2024-01-01T10:01:00Z", "bpm": 78}
                ]
            }
        }
    }]
}

# Test webhook processing
result = process_terra_webhook_with_gcs('body', mock_webhook, 'test_user')
print(f"Webhook processed: {result}")

# Test cache update
await update_terra_cache_on_webhook('test_user', 'body')

---

2. Enhanced AI Copilot Testing

Unit Tests

# Run AI function tests
python -m pytest functions/test/test_enhanced_features.py::TestEnhancedAIFunctions -v

Manual Testing - Individual Tools

from src.functions_ai_enhanced import (
    get_user_events, get_user_protocols, 
    get_user_documents, get_scheduled_items
)

# Test event querying
events = get_user_events(
    clinic_id='test_clinic',
    user_id='test_user',
    event_types=['exercise', 'meal'],
    start_date='2024-01-01T00:00:00Z',
    limit=10
)
print("User Events:")
print(events)

# Test protocol querying
protocols = get_user_protocols(
    clinic_id='test_clinic',
    user_id='test_user',
    status='active'
)
print("\nActive Protocols:")
print(protocols)

# Test document querying
documents = get_user_documents(
    clinic_id='test_clinic',
    user_id='test_user',
    document_type='lab_report'
)
print("\nLab Reports:")
print(documents)

Integration Testing - Full AI Agent

from src.functions_ai_enhanced import create_enhanced_clinical_agent

# Create enhanced agent
agent = create_enhanced_clinical_agent()

# Test complex health queries
test_queries = [
    "What was the patient's average heart rate last week?",
    "Show me the patient's recent exercise events",
    "What lab reports does the patient have?",
    "When is the patient's next appointment?",
    "Is there correlation between exercise and sleep quality?"
]

for query in test_queries:
    print(f"\n🤖 Query: {query}")
    try:
        response = agent.invoke({
            "input": query,
            "clinic_id": "test_clinic",
            "user_id": "test_user"
        })
        print(f"✅ Response: {response['output']}")
    except Exception as e:
        print(f"❌ Error: {e}")

---

3. LLM Selector UI Testing

Widget Tests

// test/widgets/llm_selector_test.dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:basis_hybrid/view/widgets/widget_llm_selector.dart';

void main() {
  testWidgets('LLM Selector displays models correctly', (tester) async {
    LLMModel? selectedModel;
    
    await tester.pumpWidget(MaterialApp(
      home: Scaffold(
        body: LLMSelectorWidget(
          selectedModel: LLMModel.gemini2Flash,
          onModelChanged: (model) => selectedModel = model,
        ),
      ),
    ));
    
    // Verify widget displays
    expect(find.text('Gemini 2.0 Flash'), findsOneWidget);
    expect(find.text('✨'), findsOneWidget);
    
    // Test model selection
    await tester.tap(find.byType(DropdownButton<LLMModel>));
    await tester.pumpAndSettle();
    
    // Verify dropdown options
    expect(find.text('Claude 3.5 Sonnet'), findsOneWidget);
    expect(find.text('GPT-4o'), findsOneWidget);
  });
}

Manual Testing - Model Selection

// Create test app with LLM selector
class TestLLMSelectorApp extends StatefulWidget {
  @override
  _TestLLMSelectorAppState createState() => _TestLLMSelectorAppState();
}

class _TestLLMSelectorAppState extends State<TestLLMSelectorApp> {
  LLMModel selectedModel = LLMModel.gemini2Flash;
  
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('LLM Selector Test')),
        body: Column(
          children: [
            LLMSelectorWidget(
              selectedModel: selectedModel,
              onModelChanged: (model) {
                setState(() => selectedModel = model);
                print('Selected model: ${model.displayName}');
              },
            ),
            SizedBox(height: 20),
            Text('Current: ${selectedModel.displayName}'),
            Text('Provider: ${selectedModel.provider}'),
            Text('Performance: ${selectedModel.performanceInfo}'),
          ],
        ),
      ),
    );
  }
}

---

4. Enhanced Chat Interface Testing

Widget Tests

// test/routes/chat_enhanced_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:basis_hybrid/view/routes/chat/route_chat_enhanced.dart';

void main() {
  testWidgets('Enhanced chat interface loads correctly', (tester) async {
    await tester.pumpWidget(MaterialApp(
      home: ChatRouteEnhanced(),
    ));
    
    // Verify main components
    expect(find.text('Basis Copilot'), findsOneWidget);
    expect(find.byType(LLMSelectorWidget), findsOneWidget);
    expect(find.text('New Chat'), findsOneWidget);
    
    // Test new chat creation
    await tester.tap(find.byIcon(Icons.add));
    await tester.pumpAndSettle();
    
    // Verify chat creation
    expect(find.text('Chat 1'), findsOneWidget);
  });
}

Manual Testing - Chat Flow

1. Open Enhanced Chat Interface

   Navigator.push(context, MaterialPageRoute(
     builder: (context) => ChatRouteEnhanced(
       enableModelSelection: true,
     ),
   ));

2. Test Model Selection

   • Click LLM dropdown
   • Select different models (GPT-4o, Claude, Gemini)
   • Verify model indicator updates

3. Test Chat Management

   • Create new chat
   • Switch between chats
   • Verify chat history persistence

4. Test Message Flow

   • Send test message: "What's my average heart rate?"
   • Verify processing indicators show
   • Verify model-specific responses

---

5. Canvas Reports Testing

Widget Tests

// test/routes/canvas_reports_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:basis_hybrid/view/routes/canvas/route_canvas_reports.dart';

void main() {
  testWidgets('Canvas reports interface loads', (tester) async {
    await tester.pumpWidget(MaterialApp(
      home: CanvasReportsRoute(),
    ));
    
    // Verify main components
    expect(find.text('Templates'), findsOneWidget);
    expect(find.text('Metabolic Health Report'), findsOneWidget);
    expect(find.text('Add Elements'), findsOneWidget);
    
    // Test template selection
    await tester.tap(find.text('Metabolic Health Report'));
    await tester.pumpAndSettle();
    
    // Verify canvas elements loaded
    expect(find.text('Blood Glucose Trend'), findsOneWidget);
  });
}

Manual Testing - Report Generation

1. Open Canvas Interface

   Navigator.push(context, MaterialPageRoute(
     builder: (context) => CanvasReportsRoute(),
   ));

2. Test Template Loading

   • Select "Metabolic Health Report"
   • Verify charts and elements appear
   • Test different date ranges

3. Test Element Creation

   • Add line chart
   • Add text element
   • Test drag and resize

4. Test AI Generation

   • Click "AI Analysis"
   • Enter prompt: "Generate glucose trend analysis"
   • Verify AI elements are added

---

🧪 End-to-End Testing Scenarios

Scenario 1: Complete Health Data Query

# 1. Process Terra webhook
webhook_data = {
    "type": "activity",
    "user": {"user_id": "test_user"},
    "data": [{"activity_name": "Running", "calories": 350}]
}
process_terra_webhook_with_gcs('activity', webhook_data, 'test_user')

# 2. Update cache
await update_terra_cache_on_webhook('test_user', 'activity')

# 3. Query with AI
agent = create_enhanced_clinical_agent()
response = agent.invoke({
    "input": "What exercise did the user do today and how many calories burned?",
    "clinic_id": "test_clinic",
    "user_id": "test_user"
})
print(response['output'])

Scenario 2: Multi-Model Chat Session

// 1. Start with Gemini
setState(() => selectedModel = LLMModel.gemini2Flash);
await sendMessage("Analyze my sleep patterns");

// 2. Switch to Claude for detailed analysis
setState(() => selectedModel = LLMModel.claudeSonnet35);
await sendMessage("Provide detailed recommendations");

// 3. Switch to GPT-4o for action plan
setState(() => selectedModel = LLMModel.gpt4o);
await sendMessage("Create a 30-day improvement plan");

Scenario 3: Complete Report Generation

// 1. Open canvas with template
final template = ReportTemplate.metabolicHealth;
Navigator.push(context, MaterialPageRoute(
  builder: (context) => CanvasReportsRoute(
    initialTemplate: template,
  ),
));

// 2. Customize with AI
await generateAIReport("Generate quarterly metabolic health summary for patient John Doe");

// 3. Export report
await exportReport(); // PDF/PNG export

---

🐛 Debugging and Troubleshooting

Common Issues

1. Cache Update Fails

   # Check DuckDB connection
   with db_manager.open(user_id) as ctx:
       result = ctx.execute("SELECT COUNT(*) FROM hr").fetchone()
       print(f"HR records: {result[0]}")

2. AI Agent Tools Not Working

   # Verify tool registration
   agent = create_enhanced_clinical_agent()
   tool_names = [tool.name for tool in agent.tools]
   print(f"Available tools: {tool_names}")

3. UI Widget Not Responding

   // Enable debug mode
   MaterialApp(
     debugShowCheckedModeBanner: true,
     home: YourWidget(),
   )

Performance Monitoring

# Monitor cache performance
import time

start_time = time.time()
result = await cache_manager.update_cache_from_duckdb(['hr', 'glucose'])
duration = time.time() - start_time

print(f"Cache update took: {duration:.2f}s")
print(f"Records processed: {result.get('total_recent_records', 0)}")

---

📊 Test Data Setup

Create Test User Data

from functions.test.test_enhanced_features import create_test_user_data

# Generate comprehensive test data
test_data = create_test_user_data()

# Populate Firestore with test data
# (This would integrate with your existing data setup)

Mock Health Data

from functions.test.test_enhanced_features import generate_mock_health_data

# Generate realistic health metrics
health_data = generate_mock_health_data()
print(f"Generated data types: {list(health_data.keys())}")

---

✅ Testing Checklist

Terra Cache Manager

• Cache update from DuckDB works
• Firestore storage is correct
• Cache retrieval is fast (<100ms)
• Cache invalidation works
• Error handling is robust

Enhanced AI Copilot

• All 7 tools are available
• Health data queries work
• Event queries work
• Protocol queries work
• Document queries work
• Schedule queries work
• Complex multi-tool queries work

LLM Selector UI

• All models display correctly
• Model switching works
• Preferences persist
• Visual indicators update
• Performance info shows

Enhanced Chat Interface

• Sidebar shows/hides correctly
• Chat history loads
• New chat creation works
• Model indicator updates
• Processing status shows
• Message sending works

Canvas Reports

• Templates load correctly
• Charts render with data
• Elements can be moved/resized
• AI generation works
• Export functionality works

Run this comprehensive testing strategy to ensure all enhanced features work correctly in your environment! 🎉