EU-Utility/TESTING.md

# EU-Utility Testing Guide

Complete testing instructions for EU-Utility Premium with Entropia Universe.

## 🚀 Quick Start

### 1. Install Dependencies

```bash
cd ~/EU-Utility
pip install -r requirements.txt
```

**Required packages:**
- PyQt6 (GUI framework)
- psutil (process monitoring)
- pywin32 (Windows API) - Windows only
- pillow (screenshots)

### 2. Configure Game Path

Edit the config file (created automatically on first run):

```bash
# Windows default paths:
# C:\Program Files (x86)\Entropia Universe\ClientLoader.exe
# C:\Users\<username>\AppData\Local\Entropia Universe

# Or create manually:
python -c "
import json
from pathlib import Path
config = {
    'game_path': r'C:\\Program Files (x86)\\Entropia Universe',
    'overlay_enabled': True,
    'overlay_mode': 'overlay_toggle',
    'hotkey': 'ctrl+shift+b',
    'plugins_enabled': ['dashboard_widget'],
}
Path.home().joinpath('.eu-utility', 'config.json').write_text(json.dumps(config, indent=2))
"
```

### 3. Launch EU-Utility

```bash
python main.py
```

**Command line options:**
```bash
python main.py --verbose          # Debug logging
python main.py --test             # Test mode (no game required)
python main.py --no-overlay       # Headless mode
```

---

## 🎮 Testing With Entropia Universe

### Test 1: Basic Launch

**Steps:**
1. Launch EU-Utility: `python main.py`
2. Check console output - should show "EU-Utility Premium initialized"
3. Look for system tray icon (small EU logo)
4. Press `Ctrl+Shift+B` to toggle overlay

**Expected:** Overlay appears with dashboard widget

### Test 2: Game Detection

**Steps:**
1. Launch Entropia Universe game client
2. Wait 5-10 seconds
3. Check EU-Utility console for "Game client detected"

**Expected:** Log shows process detection working

**Debug:** If not detected, check game path in config

### Test 3: Overlay Modes

Test each overlay mode in config:

**Mode: `overlay_toggle`** (default)
- Press `Ctrl+Shift+B` to show/hide overlay
- Should toggle instantly (<100ms)

**Mode: `overlay_game`**
- Overlay auto-shows when EU window is focused
- Overlay auto-hides when EU loses focus
- Should be smooth (no lag)

**Mode: `overlay_temp`**
- Press hotkey to show for 8 seconds
- Auto-hides after duration

### Test 4: Dashboard Widget

**Steps:**
1. Open overlay with hotkey
2. Verify dashboard widget loads
3. Check for player stats display

**Features to test:**
- [ ] Player name display
- [ ] Skill levels visible
- [ ] Health/Energy bars
- [ ] PED balance (if available)

### Test 5: Log File Parsing

**Steps:**
1. In game, get some loot or skill gain
2. Check EU-Utility console for events
3. Look for: `[GameEvent] Loot: ...` or `[GameEvent] Skill: ...`

**Expected:** Real-time event detection

**Log locations:**
```
%LOCALAPPDATA%\Entropia Universe\chat.log
%LOCALAPPDATA%\Entropia Universe\Entropia.log
```

### Test 6: Performance Test

**Steps:**
1. Run EU-Utility with game for 30 minutes
2. Monitor CPU usage (should be <5%)
3. Check for "Focus check took Xms" warnings

**Expected:** 
- No lag spikes
- Smooth 60fps overlay
- CPU usage minimal

**Debug:** If slow, check overlay_controller.py optimizations

---

## 🔧 Troubleshooting

### Issue: "Game not detected"

**Check:**
1. Game path in config is correct
2. Game is actually running
3. Try running EU-Utility as administrator

**Fix:**
```python
# Update config with correct path
config['game_path'] = r'C:\Your\Actual\Path\To\Entropia Universe'
```

### Issue: "Overlay not appearing"

**Check:**
1. Hotkey is not conflicting with other apps
2. Overlay mode is set correctly
3. No Qt/OpenGL errors in console

**Fix:**
```bash
# Try test mode
python main.py --test

# Or disable overlay temporarily
python main.py --no-overlay
```

### Issue: "App is slow/laggy"

**Check:**
1. Focus check timing in logs
2. CPU/memory usage
3. Number of plugins loaded

**Fix:**
- Reduce poll interval in config
- Disable unused plugins
- Check for window manager conflicts

### Issue: "Plugins not loading"

**Check:**
1. Plugin files exist in `plugins/builtin/`
2. plugin.json is valid JSON
3. No import errors in console

**Fix:**
```bash
# Verify plugin structure
ls plugins/builtin/dashboard_widget/
# Should show: plugin.json, main.py

# Check for syntax errors
python -m py_compile plugins/builtin/dashboard_widget/main.py
```

---

## 🧪 Advanced Testing

### Test Plugin Development

Create a test plugin:

```python
# plugins/user/test_plugin/main.py
from premium.plugins.api import BasePlugin, PluginManifest

class TestPlugin(BasePlugin):
    manifest = PluginManifest(
        name="Test Plugin",
        version="1.0.0",
        author="Tester"
    )
    
    def on_load(self):
        print("Test plugin loaded!")
        return True
    
    def on_enable(self):
        print("Test plugin enabled!")
    
    def on_disable(self):
        print("Test plugin disabled!")
```

```json
// plugins/user/test_plugin/plugin.json
{
  "name": "Test Plugin",
  "version": "1.0.0",
  "author": "Tester",
  "main": "main.py",
  "entry_point": "TestPlugin"
}
```

### Test Event System

```python
# Test event bus
from premium.core.event_bus import EventBus, Event

bus = EventBus()

@bus.on("game.loot")
def on_loot(event):
    print(f"Got loot: {event.data}")

bus.emit("game.loot", {"item": "Ammunition", "amount": 100})
```

### Test State Management

```python
# Test state store
from premium.core.state.store import StateStore, ActionBase

class IncrementAction(ActionBase):
    type = "INCREMENT"

def counter_reducer(state, action):
    if action.type == "INCREMENT":
        return state + 1
    return state

store = StateStore(counter_reducer, initial_state=0)
store.dispatch(IncrementAction())
print(store.state)  # 1
```

---

## 📊 Performance Benchmarks

### Expected Performance

| Metric | Target | Acceptable |
|--------|--------|------------|
| Startup time | <3s | <5s |
| Focus check | <10ms | <50ms |
| Overlay toggle | <100ms | <200ms |
| CPU usage | <3% | <10% |
| Memory usage | <200MB | <500MB |
| Log parsing | Real-time | <1s delay |

### Benchmark Script

```bash
# Run performance test
python -c "
import time
from premium.eu_integration.game_client import GameClient

start = time.time()
client = GameClient()
client.initialize()
print(f'Init time: {time.time() - start:.2f}s')

# Test detection
start = time.time()
found = client.find_game_process()
print(f'Detection time: {time.time() - start:.2f}s')
print(f'Game found: {found}')
"
```

---

## 🐛 Debug Mode

### Enable Debug Logging

```bash
python main.py --verbose
```

### Key Log Messages

| Message | Meaning |
|---------|---------|
| "Game client detected" | Process found |
| "Window focused" | EU window active |
| "Overlay shown/hidden" | Toggle working |
| "Plugin loaded: X" | Plugin loaded |
| "Focus check took Xms" | Performance warning |
| "Event: game.loot" | Game event detected |

### Check Logs

```bash
# Real-time log view
tail -f ~/.eu-utility/logs/app.log

# Search for errors
grep ERROR ~/.eu-utility/logs/app.log
```

---

## ✅ Final Checklist

Before considering ready for production:

- [ ] App launches without errors
- [ ] Game detection works
- [ ] Overlay appears with hotkey
- [ ] Dashboard shows data
- [ ] Log events are captured
- [ ] Performance is smooth
- [ ] No memory leaks (stable after 1 hour)
- [ ] Plugins load/unload correctly
- [ ] Settings save/load properly
- [ ] Exits gracefully on close

---

## 🆘 Getting Help

If issues persist:

1. Check logs: `~/.eu-utility/logs/`
2. Run tests: `python -m pytest tests/`
3. Check config: `~/.eu-utility/config.json`
4. Verify game running and accessible

**Debug info to collect:**
- Console output
- Log files
- System specs (CPU, RAM, GPU)
- Windows version
- Game version