# Ghost Module

> Automated QA testing with headless AI agents

# Ghost Module

`Ghóst_Módule // Autómated_QA`

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

The Ghost module runs **headless AI agents** for automated game testing. Ghosts explore, fight, dialogue, and report bugs.

> *T̸h̵e̷ ̴g̸h̴o̸s̶t̶s̷ ̵w̷a̶l̵k̶ ̵w̵h̸e̷r̵e̴ ̷p̷l̸a̷y̴e̵r̶s̷ ̷f̷e̵a̷r̷.*

***

## Overview

Ghost provides:

* **Multiple Test Suites**: Exploration, combat, dialogue, pathfinding
* **Real-time Status**: Monitor progress and duration
* **Comprehensive Results**: Pass/fail, coverage, performance metrics
* **Screenshot Capture**: Visual evidence of failures

***

## Quick Start

```typescript
import { createGhost } from 'forbocai';

// Configure Ghost session
const ghost = createGhost({
  testSuite: 'exploration',
  duration: 300,  // 5 minutes
  captureScreenshots: true
});

// Start session
const sessionId = await ghost.run();

// Wait for completion
const results = await ghost.waitForCompletion();

console.log(`${results.passed}/${results.totalTests} tests passed`);
console.log(`Coverage: ${(results.coverage * 100).toFixed(1)}%`);
```

***

## Configuration

| Option               | Type      | Default  | Description                    |
| -------------------- | --------- | -------- | ------------------------------ |
| `testSuite`          | `string`  | required | Test suite to run              |
| `duration`           | `number`  | required | Max duration in seconds        |
| `captureScreenshots` | `boolean` | `false`  | Capture screenshots on failure |
| `apiUrl`             | `string`  | API URL  | Ghost orchestration endpoint   |
| `params`             | `object`  | `{}`     | Custom test parameters         |

### Test Suites

| Suite         | Description                             |
| ------------- | --------------------------------------- |
| `exploration` | Pathfinding, map coverage, navigation   |
| `combat`      | Battle mechanics, AI decisions, balance |
| `dialogue`    | NPC conversations, branching logic      |
| `pathfinding` | Navigation mesh, obstacle avoidance     |
| `full`        | All tests combined                      |

***

## API Reference

### `createGhost(config)`

Factory function to create a Ghost session.

```typescript
import { createGhost } from 'forbocai';

const ghost = createGhost({
  testSuite: 'combat',
  duration: 600,
  params: {
    difficulty: 'hard',
    enemies: ['orc', 'goblin', 'dragon']
  }
});
```

***

### `ghost.run()`

Start the Ghost testing session.

**Returns:** `Promise<string>` (sessionId)

```typescript
const sessionId = await ghost.run();
console.log(`Started session: ${sessionId}`);
```

***

### `ghost.status()`

Get current session status.

**Returns:** `Promise<GhostStatus>`

```typescript
interface GhostStatus {
  sessionId: string;
  status: 'pending' | 'running' | 'completed' | 'failed';
  progress: number;      // 0-100
  startedAt: string;     // ISO timestamp
  duration: number;      // seconds elapsed
  errors: number;        // error count
}
```

```typescript
const status = await ghost.status();
console.log(`${status.progress}% complete`);
console.log(`Errors: ${status.errors}`);
```

***

### `ghost.results()`

Get session test results.

**Returns:** `Promise<GhostResults>`

```typescript
interface GhostResults {
  sessionId: string;
  totalTests: number;
  passed: number;
  failed: number;
  skipped: number;
  duration: number;           // total ms
  tests: GhostTestResult[];
  coverage: number;           // 0.0-1.0
  metrics: Record<string, number>;
}

interface GhostTestResult {
  name: string;
  passed: boolean;
  duration: number;           // ms
  error?: string;
  screenshot?: string;        // URL/path
}
```

```typescript
const results = await ghost.results();

// Summary
console.log(`Tests: ${results.passed}/${results.totalTests}`);
console.log(`Duration: ${results.duration}ms`);

// Failed tests
results.tests
  .filter(t => !t.passed)
  .forEach(t => {
    console.log(`FAIL: ${t.name}`);
    console.log(`  Error: ${t.error}`);
    console.log(`  Screenshot: ${t.screenshot}`);
  });
```

***

### `ghost.stop()`

Stop the running session.

**Returns:** `Promise<void>`

***

### `ghost.waitForCompletion(pollInterval?, timeout?, onProgress?)`

Wait for session to complete with progress updates.

**Parameters:**

* `pollIntervalMs` (number): Polling interval (default: 5000)
* `timeoutMs` (number): Maximum wait time (default: 300000)
* `onProgress` (function): Progress callback

**Returns:** `Promise<GhostResults>`

```typescript
const results = await ghost.waitForCompletion(
  5000,    // Poll every 5 seconds
  600000,  // Timeout after 10 minutes
  (status) => {
    console.log(`Progress: ${status.progress}%`);
    console.log(`Duration: ${status.duration}s`);
  }
);
```

***

## Standalone Functions

### `startGhostSession(config)`

Start a session without class instance.

```typescript
import { startGhostSession } from 'forbocai';

const { sessionId, status } = await startGhostSession({
  testSuite: 'exploration',
  duration: 300
});
```

***

### `getGhostStatus(sessionId, apiUrl?)`

Get status for any session.

```typescript
import { getGhostStatus } from 'forbocai';

const status = await getGhostStatus('sess_123');
```

***

### `getGhostResults(sessionId, apiUrl?)`

Get results for any session.

```typescript
import { getGhostResults } from 'forbocai';

const results = await getGhostResults('sess_123');
```

***

### `stopGhostSession(sessionId, apiUrl?)`

Stop a running Ghost session.

```typescript
import { stopGhostSession } from 'forbocai';

const { stopped, status } = await stopGhostSession('sess_123');
console.log(`Session stopped: ${stopped}`);
```

**Returns:** `Promise<{ stopped: boolean; status: string }>`

***

### `getGhostHistory(limit?, apiUrl?)`

Get history of all Ghost sessions.

```typescript
import { getGhostHistory } from 'forbocai';

const history = await getGhostHistory(10);

history.forEach(entry => {
  console.log(`${entry.sessionId}: ${entry.testSuite} - ${entry.status}`);
  if (entry.passRate) {
    console.log(`  Pass Rate: ${(entry.passRate * 100).toFixed(1)}%`);
  }
});
```

**Returns:** `Promise<GhostHistoryEntry[]>`

```typescript
interface GhostHistoryEntry {
  sessionId: string;
  testSuite: string;
  startedAt: string;
  completedAt?: string;
  status: string;
  passRate: number;
}
```

***

## Metrics

Ghost collects performance and coverage metrics:

| Metric                | Description                   |
| --------------------- | ----------------------------- |
| `avgFrameRate`        | Average FPS during test       |
| `memoryUsageMB`       | Peak memory usage             |
| `aiDecisionsPerSec`   | Agent decision throughput     |
| `explorationCoverage` | Map area discovered (0.0-1.0) |

```typescript
const results = await ghost.results();

console.log('Performance Metrics:');
console.log(`  FPS: ${results.metrics.avgFrameRate}`);
console.log(`  Memory: ${results.metrics.memoryUsageMB} MB`);
console.log(`  AI/sec: ${results.metrics.aiDecisionsPerSec}`);
console.log(`  Coverage: ${(results.metrics.explorationCoverage * 100).toFixed(1)}%`);
```

***

## CI/CD Integration

Integrate Ghost into your CI pipeline:

```yaml
# .github/workflows/ghost-tests.yml
name: Ghost QA Tests

on: [push, pull_request]

jobs:
  ghost:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Run Ghost tests
        run: npx forbocai ghost run --suite full --duration 300
      
      - name: Upload screenshots
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: ghost-screenshots
          path: ./screenshots/
```

***

## Test Report Format

Ghost outputs results in JUnit-compatible format:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<testsuite name="Ghost QA" tests="5" failures="1" time="1.245">
  <testcase name="test.navigation.basic" time="0.150"/>
  <testcase name="test.combat.attack" time="0.230"/>
  <testcase name="test.inventory.pickup" time="0.095"/>
  <testcase name="test.dialogue.npc" time="0.450">
    <failure message="Timeout waiting for NPC response"/>
  </testcase>
  <testcase name="test.ai.pathfinding" time="0.320"/>
</testsuite>
```

***

## Custom Test Parameters

Pass custom parameters to test suites:

```typescript
const ghost = createGhost({
  testSuite: 'combat',
  duration: 300,
  params: {
    difficulty: 'nightmare',
    playerLevel: 50,
    enemies: ['dragon', 'lich', 'demon'],
    allowFlee: false,
    requireWin: true
  }
});
```

***

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

> *G̵h̴o̷s̶t̵s̴ ̸n̶e̷v̸e̷r̷ ̵s̶l̷e̴e̸p̸.̵ ̷T̵h̶e̸y̴ ̵o̵n̵l̵y̴ ̸w̷a̸t̷c̶h̶.*