Ghost Module

View as MarkdownOpen in Claude

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

1import { createGhost } from 'forbocai';
2
3// Configure Ghost session
4const ghost = createGhost({
5 testSuite: 'exploration',
6 duration: 300, // 5 minutes
7 captureScreenshots: true
8});
9
10// Start session
11const sessionId = await ghost.run();
12
13// Wait for completion
14const results = await ghost.waitForCompletion();
15
16console.log(`${results.passed}/${results.totalTests} tests passed`);
17console.log(`Coverage: ${(results.coverage * 100).toFixed(1)}%`);

Configuration

OptionTypeDefaultDescription
testSuitestringrequiredTest suite to run
durationnumberrequiredMax duration in seconds
captureScreenshotsbooleanfalseCapture screenshots on failure
apiUrlstringAPI URLGhost orchestration endpoint
paramsobject{}Custom test parameters

Test Suites

SuiteDescription
explorationPathfinding, map coverage, navigation
combatBattle mechanics, AI decisions, balance
dialogueNPC conversations, branching logic
pathfindingNavigation mesh, obstacle avoidance
fullAll tests combined

API Reference

createGhost(config)

Factory function to create a Ghost session.

1import { createGhost } from 'forbocai';
2
3const ghost = createGhost({
4 testSuite: 'combat',
5 duration: 600,
6 params: {
7 difficulty: 'hard',
8 enemies: ['orc', 'goblin', 'dragon']
9 }
10});

ghost.run()

Start the Ghost testing session.

Returns: Promise<string> (sessionId)

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

ghost.status()

Get current session status.

Returns: Promise<GhostStatus>

1interface GhostStatus {
2 sessionId: string;
3 status: 'pending' | 'running' | 'completed' | 'failed';
4 progress: number; // 0-100
5 startedAt: string; // ISO timestamp
6 duration: number; // seconds elapsed
7 errors: number; // error count
8}
1const status = await ghost.status();
2console.log(`${status.progress}% complete`);
3console.log(`Errors: ${status.errors}`);

ghost.results()

Get session test results.

Returns: Promise<GhostResults>

1interface GhostResults {
2 sessionId: string;
3 totalTests: number;
4 passed: number;
5 failed: number;
6 skipped: number;
7 duration: number; // total ms
8 tests: GhostTestResult[];
9 coverage: number; // 0.0-1.0
10 metrics: Record<string, number>;
11}
12
13interface GhostTestResult {
14 name: string;
15 passed: boolean;
16 duration: number; // ms
17 error?: string;
18 screenshot?: string; // URL/path
19}
1const results = await ghost.results();
2
3// Summary
4console.log(`Tests: ${results.passed}/${results.totalTests}`);
5console.log(`Duration: ${results.duration}ms`);
6
7// Failed tests
8results.tests
9 .filter(t => !t.passed)
10 .forEach(t => {
11 console.log(`FAIL: ${t.name}`);
12 console.log(` Error: ${t.error}`);
13 console.log(` Screenshot: ${t.screenshot}`);
14 });

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>

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

Standalone Functions

startGhostSession(config)

Start a session without class instance.

1import { startGhostSession } from 'forbocai';
2
3const { sessionId, status } = await startGhostSession({
4 testSuite: 'exploration',
5 duration: 300
6});

getGhostStatus(sessionId, apiUrl?)

Get status for any session.

1import { getGhostStatus } from 'forbocai';
2
3const status = await getGhostStatus('sess_123');

getGhostResults(sessionId, apiUrl?)

Get results for any session.

1import { getGhostResults } from 'forbocai';
2
3const results = await getGhostResults('sess_123');

stopGhostSession(sessionId, apiUrl?)

Stop a running Ghost session.

1import { stopGhostSession } from 'forbocai';
2
3const { stopped, status } = await stopGhostSession('sess_123');
4console.log(`Session stopped: ${stopped}`);

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


getGhostHistory(limit?, apiUrl?)

Get history of all Ghost sessions.

1import { getGhostHistory } from 'forbocai';
2
3const history = await getGhostHistory(10);
4
5history.forEach(entry => {
6 console.log(`${entry.sessionId}: ${entry.testSuite} - ${entry.status}`);
7 if (entry.passRate) {
8 console.log(` Pass Rate: ${(entry.passRate * 100).toFixed(1)}%`);
9 }
10});

Returns: Promise<GhostHistoryEntry[]>

1interface GhostHistoryEntry {
2 sessionId: string;
3 testSuite: string;
4 startedAt: string;
5 completedAt?: string;
6 status: string;
7 passRate: number;
8}

Metrics

Ghost collects performance and coverage metrics:

MetricDescription
avgFrameRateAverage FPS during test
memoryUsageMBPeak memory usage
aiDecisionsPerSecAgent decision throughput
explorationCoverageMap area discovered (0.0-1.0)
1const results = await ghost.results();
2
3console.log('Performance Metrics:');
4console.log(` FPS: ${results.metrics.avgFrameRate}`);
5console.log(` Memory: ${results.metrics.memoryUsageMB} MB`);
6console.log(` AI/sec: ${results.metrics.aiDecisionsPerSec}`);
7console.log(` Coverage: ${(results.metrics.explorationCoverage * 100).toFixed(1)}%`);

CI/CD Integration

Integrate Ghost into your CI pipeline:

1# .github/workflows/ghost-tests.yml
2name: Ghost QA Tests
3
4on: [push, pull_request]
5
6jobs:
7 ghost:
8 runs-on: ubuntu-latest
9 steps:
10 - uses: actions/checkout@v3
11
12 - name: Setup Node
13 uses: actions/setup-node@v3
14 with:
15 node-version: '20'
16
17 - name: Install dependencies
18 run: npm install
19
20 - name: Run Ghost tests
21 run: npx forbocai ghost run --suite full --duration 300
22
23 - name: Upload screenshots
24 if: failure()
25 uses: actions/upload-artifact@v3
26 with:
27 name: ghost-screenshots
28 path: ./screenshots/

Test Report Format

Ghost outputs results in JUnit-compatible format:

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

Custom Test Parameters

Pass custom parameters to test suites:

1const ghost = createGhost({
2 testSuite: 'combat',
3 duration: 300,
4 params: {
5 difficulty: 'nightmare',
6 playerLevel: 50,
7 enemies: ['dragon', 'lich', 'demon'],
8 allowFlee: false,
9 requireWin: true
10 }
11});

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

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̶.