# EU-Utility UI Test Suite Documentation

## Overview

The UI Test Suite is a comprehensive validation framework for testing all EU-Utility UI components and user flows. It provides automated testing, visual validation, and detailed bug reporting.

## Installation

The test suite is located at:
```
/home/impulsivefps/.openclaw/workspace/projects/EU-Utility/plugins/ui_test_suite/
```

To enable the test suite:
1. Open EU-Utility Settings
2. Go to the Plugins tab
3. Enable "UI Test Suite"
4. Restart the overlay

## Test Modules

The test suite includes 9 comprehensive test modules:

### 1. Overlay Window Tests 🪟
Tests main overlay window functionality:
- Window initialization and sizing
- Tab navigation (Plugins, Widgets, Settings)
- Responsive sidebar behavior
- Theme toggle functionality
- Keyboard shortcuts (ESC, Ctrl+T, Ctrl+1-9)
- Plugin display in sidebar
- Window positioning and centering
- System tray icon
- Animation smoothness
- Content switching between tabs/plugins

### 2. Activity Bar Tests 📊
Tests in-game activity bar:
- Layout modes (Horizontal, Vertical, Grid)
- Dragging and positioning
- Plugin drawer functionality
- Pinned plugins management
- Opacity control
- Auto-hide behavior
- Settings dialog
- Mini widgets support
- Configuration persistence

### 3. Widget System Tests 🎨
Tests widget registry and management:
- Registry initialization (singleton pattern)
- Widget registration/unregistration
- Widget creation via registry
- Widget lookup by ID
- Widgets by plugin filtering
- WidgetInfo dataclass structure
- Overlay widget creation
- Widget positioning

### 4. Settings UI Tests ⚙️
Tests settings interface:
- Settings dialog creation
- General settings (theme, opacity)
- Plugin management UI
- Hotkey configuration
- Appearance settings
- Data and backup (export/import)
- Updates tab
- About tab
- Save/Cancel functionality
- Dependency checking integration

### 5. Plugin Store Tests 🔌
Tests plugin store interface:
- Store UI creation
- Plugin listing and display
- Search functionality
- Install workflow
- Uninstall workflow
- Dependency display
- Category filtering
- Refresh functionality
- Error handling

### 6. Theme & Styling Tests 🎨
Tests theme consistency:
- Color system (dark/light themes)
- Typography system
- Theme switching
- Button styles (variants and sizes)
- Input field styles
- Table styles
- Scrollbar styles
- Global stylesheet
- Component consistency
- Accessibility colors

### 7. User Flow Tests 👤
Tests complete user workflows:
- First-time user experience
- Plugin installation workflow
- Widget creation workflow
- Settings change workflow
- Hotkey functionality
- Window positioning persistence
- Overlay toggle flow
- Tab navigation flow
- Plugin drawer flow
- Error recovery

### 8. Accessibility Tests ♿
Tests accessibility features:
- Keyboard navigation
- Focus indicators
- Screen reader support
- Color contrast
- High contrast mode
- Shortcut hints
- Accessible names
- Tab order
- Reduced motion support
- Font scaling

### 9. Performance Tests ⚡
Tests UI performance:
- Animation performance
- Stylesheet efficiency
- Plugin loading speed
- Widget creation speed
- Rendering performance
- Memory efficiency
- Responsive breakpoints
- Lazy loading opportunities
- Caching implementation
- Optimization flags

## Running Tests

### Via UI
1. Open EU-Utility overlay
2. Select "UI Test Suite" from sidebar
3. Click "▶ Run All Tests" to run complete suite
4. Or select individual test module and run

### Programmatically
```python
from plugins.ui_test_suite.test_modules import OverlayWindowTests

tests = OverlayWindowTests()
for test_name, test_func in tests.tests.items():
    result = test_func()
    print(f"{test_name}: {'PASS' if result['passed'] else 'FAIL'}")
    print(f"  Message: {result['message']}")
```

## Test Results Format

Each test returns a dictionary with:
```python
{
    'passed': bool,          # True if test passed
    'message': str,          # Description of result
    'severity': str,         # 'error', 'warning', or 'info'
    'recommendation': str    # Optional improvement suggestion
}
```

## Test Widgets

The test suite registers three test widgets:

### 1. Overlay Validator 🔍
Real-time overlay window validation widget
- Validates window positioning
- Checks theme consistency
- Tests animation smoothness
- Verifies keyboard navigation
- Checks Z-order (always on top)

### 2. Theme Consistency Checker 🎨
Validates theme consistency across components
- Displays color samples
- Checks component styling
- Validates dark/light themes

### 3. Accessibility Auditor ♿
Validates accessibility features
- Tests keyboard navigation
- Checks screen reader labels
- Validates color contrast
- Verifies focus indicators

## Interpreting Results

### Console Output
- ✅ PASS: Test passed successfully
- ❌ FAIL: Test failed (critical issue)
- ⚠️ Warning: Non-critical issue found

### Results Tab
Shows detailed results for each test with color coding:
- Green: Passed
- Yellow: Warning
- Red: Failed

### Issues Tab
Lists all found issues with:
- Module name
- Test name
- Severity level
- Error message
- Recommended fix

## Common Issues and Fixes

### Issue: Missing Focus Indicators
**Fix**: Add to stylesheet:
```css
QPushButton:focus, QLineEdit:focus {
    outline: 2px solid #ff8c42;
    outline-offset: 2px;
}
```

### Issue: Animation Too Slow
**Fix**: Reduce animation duration in `AnimationHelper`:
```python
animation.setDuration(150)  # Instead of 500+
```

### Issue: No Keyboard Shortcuts
**Fix**: Add to `_setup_shortcuts`:
```python
shortcut = QShortcut(QKeySequence("Ctrl+X"), self)
shortcut.activated.connect(self.my_action)
```

### Issue: Theme Not Applied
**Fix**: Call after theme change:
```python
self.setStyleSheet(get_global_stylesheet())
self._refresh_ui()
```

## Performance Benchmarks

Expected performance metrics:
- Overlay show/hide: < 200ms
- Tab switching: < 100ms
- Plugin loading: < 500ms for 20 plugins
- Widget creation: < 100ms
- Settings save: < 300ms

## Contributing

To add new tests:
1. Create test method in appropriate module
2. Return standard result dictionary
3. Add to module's `tests` dictionary
4. Update documentation

## Bug Reporting

When reporting bugs found by the test suite, include:
1. Test module name
2. Test name
3. Error message
4. Severity level
5. Steps to reproduce
6. Expected vs actual behavior

## Version History

- v1.0.0 (2025-02-15): Initial release
  - 9 test modules
  - 90+ individual tests
  - 3 test widgets
  - Comprehensive documentation