EU-Utility/plugins/integration_tests/README.md

EU-Utility Integration Tests

This directory contains comprehensive integration and compatibility tests for EU-Utility.

Test Plugins

1. Discord Integration Tester (integration_discord/)

Tests Discord webhook integration for:

• Message delivery
• Embed formatting
• Error handling
• Payload validation

Features:

• Webhook URL validation
• Multiple test cases (simple, embed, global, skill gain)
• Custom payload builder
• Result export

2. Home Assistant Integration Tester (integration_homeassistant/)

Tests Home Assistant integration via:

• REST API (webhooks, state updates)
• MQTT publishing
• WebSocket subscriptions

Features:

• Multi-protocol testing
• Connection validation
• Entity state updates
• Event subscriptions

3. Browser Extension Tester (integration_browser/)

Tests browser extension communication:

• Native messaging protocol
• WebSocket bridge
• HTTP API
• Message serialization

Features:

• Protocol testing
• Manifest generation
• Message validator
• Cross-browser support

4. Platform Compatibility Tester (platform_compat/)

Tests cross-platform compatibility:

• Windows-specific features
• Linux compatibility
• Path handling differences
• File locking mechanisms

Features:

• Platform detection
• Path tests (Unicode, long paths)
• File locking tests (fcntl, portalocker)
• System information

5. Service Fallback Tester (service_fallback/)

Tests graceful degradation:

• Network failures
• Missing dependencies
• API errors
• Timeout handling

Features:

• Failure simulation
• Recovery mechanisms
• Error message quality
• Retry logic validation

Test Scripts

Located in scripts/:

api_client_test.py

Python client for testing EU-Utility external API.

python api_client_test.py health
python api_client_test.py status
python api_client_test.py notify "Test" "Hello"
python api_client_test.py search "ArMatrix"
python api_client_test.py test  # Run all tests

api_client_test.js

Node.js client for testing EU-Utility external API.

node api_client_test.js health
node api_client_test.js test

api_client_test.sh

Bash/curl client for testing EU-Utility external API.

./api_client_test.sh health
./api_client_test.sh test

webhook_validator.py

Validates webhook payloads for Discord, Home Assistant, and generic webhooks.

python webhook_validator.py discord payload.json
python webhook_validator.py homeassistant payload.json
python webhook_validator.py test  # Run test payloads

platform_detector.py

Detects platform capabilities and available features.

python platform_detector.py
python platform_detector.py --json
python platform_detector.py --markdown

Compatibility Matrix

Feature	Windows	Linux	macOS
Window Manager	✅ Full	⚠️ Limited	⚠️ Limited
Native Hotkeys	✅ Full	⚠️ Limited	⚠️ Limited
Global Hotkeys	✅ Full	✅ Full	✅ Full
File Locking	✅ portalocker	✅ fcntl	✅ fcntl
Long Paths	✅*	✅	✅
Unicode Paths	✅	✅	✅
OCR (EasyOCR)	✅	✅	✅
Discord Webhooks	✅	✅	✅
MQTT	✅	✅	✅
WebSocket	✅	✅	✅
REST API	✅	✅	✅

*Requires Windows 10 1607+ with registry key

Running Tests

Install Dependencies

# Python dependencies
pip install requests paho-mqtt aiohttp websockets psutil

# Optional dependencies
pip install portalocker  # Windows file locking
pip install easyocr      # OCR engine

Run Integration Tests

# Start EU-Utility with test plugins enabled
python -m core.main

# In EU-Utility, navigate to:
# Plugins → Integration Tests → [Select Tester]

Run API Client Tests

cd scripts

# Python
python api_client_test.py test

# Node.js
node api_client_test.js test

# Bash
./api_client_test.sh test

Run Platform Detection

python scripts/platform_detector.py

Test Coverage

External Integrations

• Discord webhooks
• Home Assistant (REST, MQTT, WebSocket)
• Browser extension protocols
• Generic REST API clients

Platform Compatibility

• Windows 10/11
• Linux (Ubuntu, Debian, etc.)
• WSL support
• Path handling (Windows vs Unix)
• File locking (fcntl vs portalocker)

Service Availability

• Graceful degradation
• Timeout handling
• Retry mechanisms
• Error message quality
• Recovery detection

Reporting Issues

When reporting integration issues, please include:

1. Platform details (run platform_detector.py)
2. Test results (export from relevant tester)
3. Error messages
4. Steps to reproduce

Contributing

To add new integration tests:

1. Create a new directory under integration_tests/
2. Implement plugin.py with BasePlugin subclass
3. Create plugin.json metadata
4. Add README.md with documentation
5. Update this main README