frontends/webcomponent/TEST_README.md
This test suite validates all component types and update patterns in the vanna-webcomponent before pruning unused code.
The test suite consists of:
test_backend.py: Real Python backend that streams all component typestest-comprehensive.html: Browser-based test interface with visual validationcd submodule/vanna-webcomponent
pip install -r requirements-test.txt
npm run build
# Realistic mode (with delays between components)
python test_backend.py --mode realistic
# Rapid mode (fast stress test)
python test_backend.py --mode rapid
The backend will start on http://localhost:5555 and automatically serve the test page.
Simply open your browser to:
http://localhost:5555
The test page will load automatically!
The test exercises all rich component types with 19 different components:
For each component type, the test validates:
lifecycle: create) - Initial component renderinglifecycle: update) - Incremental property updatespython test_backend.py --mode realistic
python test_backend.py --mode rapid
The test interface provides real-time validation:
The test suite is designed to validate that pruning doesn't break functionality:
Run baseline test:
python test_backend.py --mode realistic
# Browser: Open http://localhost:5555 and run test
# Verify: All 19 components render, 0 errors
Identify cruft to remove:
Remove one piece of cruft:
# Example: Remove unused import from vanna-chat.ts
# or delete unused utility file
Rebuild:
npm run build
Refresh browser test:
If green → continue; if red → investigate:
Repeat until clean: Continue removing cruft until webcomponent is minimal
Look for these common types of cruft:
Be careful with these:
Edit test_backend.py and add new test functions:
async def test_my_component(conversation_id: str, request_id: str, mode: str):
"""Test my custom component."""
my_component = MyComponent(
id=str(uuid.uuid4()),
# ... component properties
)
yield await yield_chunk(my_component, conversation_id, request_id)
await delay(mode)
# Then add to run_comprehensive_test():
async for chunk in test_my_component(conversation_id, request_id, mode):
yield chunk
In test_backend.py, adjust the delay() function:
async def delay(mode: str, short: float = 0.1, long: float = 0.5):
if mode == "realistic":
await asyncio.sleep(long) # Adjust long delay here
elif mode == "rapid":
await asyncio.sleep(short) # Adjust short delay here
Edit test-comprehensive.html and add custom validation logic:
// Add to MutationObserver callback
const componentType = node.getAttribute('data-component-type');
if (componentType === 'my_component') {
// Custom validation for my_component
console.log('My component rendered!');
}
Error: ModuleNotFoundError: No module named 'vanna'
Solution: Make sure vanna is in the Python path:
cd submodule/vanna-webcomponent
python test_backend.py # Already adds ../vanna/src to sys.path
Solutions:
curl http://localhost:5555/healthlsof -i :5555Check:
ls dist/<script type="module" src="./dist/index.js"></script>Solutions:
cd submodule/vanna-webcomponent
python -m http.server 8080
http://localhost:8080/test-comprehensive.htmlThe checklist tracks components by their data-component-type attribute. If components don't have this attribute, they won't be tracked.
Verify: Open browser DevTools and inspect rendered components for data-component-type.
python test_backend.py --port 8000
Then update test-comprehensive.html:
<vanna-chat
api-url="http://localhost:8000"
...
></vanna-chat>
Add to test_backend.py:
import logging
logging.basicConfig(level=logging.DEBUG)
Validate the backend code with mypy:
python -m mypy test_backend.py
This catches type errors before runtime (e.g., wrong field names in Pydantic models).
Modify run_comprehensive_test() to only run specific tests:
async def run_comprehensive_test(conversation_id, request_id, mode):
# Comment out tests you don't want to run
async for chunk in test_status_card(conversation_id, request_id, mode):
yield chunk
# async for chunk in test_progress_display(...): # Disabled
# yield chunk
/api/vanna/v2/chat_ssechat_sse() creates async generatorChatStreamChunkdata: {json}\n\ndata: [DONE]\n\n<vanna-chat> web component connects to backend/api/vanna/v2/chat_sseComponentManager processes updatesComponentRegistry renders HTML elementsaction property sent as new message/api/vanna/v2/chat_sse POSThandle_action_message() processes actiontest_backend.py - Python FastAPI backend (400 lines)test-comprehensive.html - Browser test interface (500 lines)requirements-test.txt - Python dependenciesTEST_README.md - This documentationAfter validating the webcomponent with this test suite:
If you encounter issues with the test suite:
Happy Testing! 🧪