# Testing Guide
## Overview
This project uses consolidated integration test suites covering all MCP tools:
- **Core Suite** (17 original tools, 44 scenarios)
- **Advanced Suite** (15 new Phase 6-20 tools, 80 scenarios)
Plus Vitest for unit tests and a CI smoke test for mock-mode validation.
## Test Commands
| Command | Description | Requires UE? |
|---------|-------------|--------------|
| `npm test` | Run core integration suite | Yes |
| `npm run test:advanced` | Run advanced integration suite (Phases 6-20) | Yes |
| `npm run test:all` | Run both integration suites | Yes |
| `npm run test:unit` | Run Vitest unit tests | No |
| `npm run test:smoke` | CI smoke test (mock mode) | No |
## Integration Tests
### Running
```bash
# Ensure Unreal Engine is running with MCP Automation Bridge plugin enabled
npm test # Core suite (44 tests)
npm run test:advanced # Advanced suite (80 tests)
npm run test:all # Both suites (124 tests)
```
### Core Suite (`tests/integration.mjs`)
Covers 44 scenarios across the original 17 tool categories:
- Infrastructure & Discovery
- Asset & Material Lifecycle
- Actor Control & Introspection
- Blueprint Authoring
- Environment & Visuals
- AI & Input
- Cinematics & Audio
- Operations & Performance
### Advanced Suite (`tests/integration-advanced.mjs`)
Covers 80 scenarios across the 15 new Phase 6-20 tools:
- Phase 6: Geometry & Mesh Creation (`manage_geometry`)
- Phase 7: Skeletal Mesh & Rigging (`manage_skeleton`)
- Phase 8: Advanced Material Authoring (`manage_material_authoring`)
- Phase 9: Texture Generation (`manage_texture`)
- Phase 10: Animation Authoring (`manage_animation_authoring`)
- Phase 11: Audio Authoring (`manage_audio_authoring`)
- Phase 12: Niagara VFX Authoring (`manage_niagara_authoring`)
- Phase 13: Gameplay Ability System (`manage_gas`)
- Phase 14: Character & Movement (`manage_character`)
- Phase 15: Combat & Weapons (`manage_combat`)
- Phase 16: AI System - Enhanced (`manage_ai`)
- Phase 17: Inventory & Items (`manage_inventory`)
- Phase 18: Interaction System (`manage_interaction`)
- Phase 19: Widget Authoring (`manage_widget_authoring`)
- Phase 20: Networking & Multiplayer (`manage_networking`)
### Test Structure
```
tests/
├── integration.mjs # Core test suite (44 scenarios)
├── integration-advanced.mjs # Advanced test suite (80 scenarios)
├── test-runner.mjs # Shared test harness
└── reports/ # JSON test results (gitignored)
```
### Adding New Tests
Edit `tests/integration.mjs` and add a test case to the `testCases` array:
```javascript
{
scenario: 'Your test description',
toolName: 'manage_asset',
arguments: { action: 'list', path: '/Game/MyFolder' },
expected: 'success'
}
```
The `expected` field supports flexible matching:
- `'success'` — response must have `success: true`
- `'success|not found'` — either success OR "not found" in response
- `'error'` — expects failure
### Test Output
Console shows pass/fail status with timing:
```
[PASSED] Asset: create test folder (234.5 ms)
[PASSED] Actor: spawn StaticMeshActor (456.7 ms)
[FAILED] Level: get summary (123.4 ms) => {"success":false,"error":"..."}
```
JSON reports are saved to `tests/reports/` with timestamps.
## Unit Tests
```bash
npm run test:unit # Run once
npm run test:unit:watch # Watch mode
npm run test:unit:coverage # With coverage
```
Unit tests use Vitest and don't require Unreal Engine. They cover:
- Utility functions (`normalize.ts`, `validation.ts`, `safe-json.ts`)
- Pure TypeScript logic
## CI Smoke Test
```bash
MOCK_UNREAL_CONNECTION=true npm run test:smoke
```
Runs in GitHub Actions on every push/PR. Uses mock mode to validate server startup and basic tool registration without an actual Unreal connection.
## Prerequisites
### Unreal Engine Setup
1. **Unreal Engine 5.0–5.7** must be running
2. **MCP Automation Bridge plugin** enabled and listening on port 8091
### Environment Variables (optional)
```bash
MCP_AUTOMATION_HOST=127.0.0.1 # Default
MCP_AUTOMATION_PORT=8091 # Default
```
## Troubleshooting
### All Tests Fail with ECONNREFUSED
- Unreal Engine is not running, or
- MCP Automation Bridge plugin is not enabled, or
- Port 8091 is blocked
### Specific Tests Fail
- Check Unreal Output Log for errors
- Verify the asset/actor/level referenced in the test exists
- Some tests create temporary assets in `/Game/IntegrationTest` (cleaned up at end)
### Test Times Out
- Default timeout is 30 seconds per test
- Complex operations (lighting builds, large imports) may need longer
- Check if Unreal is frozen or unresponsive
## Exit Codes
- `0` — All tests passed
- `1` — One or more tests failed
Use in CI/CD:
```bash
npm test && echo "All tests passed"
```
