vice-mcp/test/integration.test.ts

/**
 * VICE MCP Integration Test Suite
 *
 * Tests all MCP tools against a running VICE instance.
 *
 * Prerequisites:
 *   x64sc -binarymonitor -binarymonitoraddress ip4://127.0.0.1:6502
 *
 * Run:
 *   npx tsx test/integration.test.ts
 */

import { spawn, ChildProcess } from 'child_process';
import * as path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

interface MCPRequest {
  jsonrpc: '2.0';
  id: number;
  method: string;
  params?: Record<string, unknown>;
}

interface MCPResponse {
  jsonrpc: '2.0';
  id: number;
  result?: unknown;
  error?: { code: number; message: string };
}

class MCPTestClient {
  private process: ChildProcess;
  private requestId = 0;
  private pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
  private buffer = '';

  constructor(serverPath: string) {
    this.process = spawn('node', [serverPath], {
      stdio: ['pipe', 'pipe', 'pipe'],
    });

    this.process.stdout!.on('data', (data: Buffer) => {
      this.buffer += data.toString();
      this.processBuffer();
    });

    this.process.stderr!.on('data', (data: Buffer) => {
      // Log errors but don't fail - some debug output goes to stderr
      const msg = data.toString().trim();
      if (msg && !msg.includes('too large to log')) {
        console.error('[MCP stderr]', msg);
      }
    });
  }

  private processBuffer() {
    const lines = this.buffer.split('\n');
    this.buffer = lines.pop() || '';

    for (const line of lines) {
      if (!line.trim()) continue;
      try {
        const response: MCPResponse = JSON.parse(line);
        const pending = this.pending.get(response.id);
        if (pending) {
          this.pending.delete(response.id);
          if (response.error) {
            pending.reject(new Error(response.error.message));
          } else {
            pending.resolve(response.result);
          }
        }
      } catch {
        // Skip non-JSON lines
      }
    }
  }

  async call(method: string, params?: Record<string, unknown>): Promise<unknown> {
    const id = ++this.requestId;
    const request: MCPRequest = {
      jsonrpc: '2.0',
      id,
      method,
      params,
    };

    return new Promise((resolve, reject) => {
      this.pending.set(id, { resolve, reject });
      this.process.stdin!.write(JSON.stringify(request) + '\n');

      // Timeout after 10 seconds
      setTimeout(() => {
        if (this.pending.has(id)) {
          this.pending.delete(id);
          reject(new Error(`Timeout waiting for response to ${method}`));
        }
      }, 10000);
    });
  }

  async callTool(name: string, args: Record<string, unknown> = {}): Promise<unknown> {
    const response = await this.call('tools/call', { name, arguments: args }) as {
      content?: Array<{ type: string; text: string }>;
    };

    // MCP wraps tool results in content[].text as JSON string
    if (response?.content?.[0]?.text) {
      try {
        return JSON.parse(response.content[0].text);
      } catch {
        return response.content[0].text;
      }
    }
    return response;
  }

  close() {
    this.process.kill();
  }
}

// Test utilities
function assert(condition: boolean, message: string) {
  if (!condition) throw new Error(`Assertion failed: ${message}`);
}

function assertExists(value: unknown, message: string) {
  if (value === null || value === undefined) {
    throw new Error(`Assertion failed: ${message} - value is ${value}`);
  }
}

function assertNoError(result: unknown, toolName: string) {
  const r = result as Record<string, unknown>;
  if (r.error) {
    throw new Error(`${toolName} returned error: ${JSON.stringify(r)}`);
  }
}

// Test definitions
interface TestResult {
  name: string;
  passed: boolean;
  error?: string;
  duration: number;
}

const tests: Array<{ name: string; fn: (client: MCPTestClient) => Promise<void> }> = [];

function test(name: string, fn: (client: MCPTestClient) => Promise<void>) {
  tests.push({ name, fn });
}

// === CONNECTION TESTS ===

test('connect - connects to VICE', async (client) => {
  const result = await client.callTool('connect') as Record<string, unknown>;
  assertNoError(result, 'connect');
  assert(result.connected === true, 'should be connected');
  assert(result.host === '127.0.0.1', 'should use default host');
  assert(result.port === 6502, 'should use default port');
});

test('status - shows connected state', async (client) => {
  const result = await client.callTool('status') as Record<string, unknown>;
  assertNoError(result, 'status');
  assert(result.connected === true, 'should be connected');
  assertExists(result.host, 'should have host');
  assertExists(result.port, 'should have port');
});

// === MEMORY TESTS ===

test('readMemory - reads screen RAM', async (client) => {
  const result = await client.callTool('readMemory', {
    address: 0x0400,
    length: 40,
  }) as Record<string, unknown>;
  assertNoError(result, 'readMemory');
  assertExists(result.hex, 'should have hex output');
  assertExists(result.ascii, 'should have ascii output');
  assert((result.bytes as number[]).length === 40, 'should read 40 bytes');
});

test('writeMemory - writes to zero page', async (client) => {
  // Use zero page instead of I/O registers for reliable test
  const testAddr = 0x00FB; // Unused zero page location

  // Save original
  const original = await client.callTool('readMemory', {
    address: testAddr,
    length: 1,
  }) as Record<string, unknown>;
  const originalValue = (original.bytes as number[])[0];

  // Write new value
  const testValue = (originalValue + 1) & 0xFF; // Different value
  const result = await client.callTool('writeMemory', {
    address: testAddr,
    bytes: [testValue],
  }) as Record<string, unknown>;
  assertNoError(result, 'writeMemory');

  // Verify
  const verify = await client.callTool('readMemory', {
    address: testAddr,
    length: 1,
  }) as Record<string, unknown>;
  assert((verify.bytes as number[])[0] === testValue, `should read back ${testValue}`);

  // Restore
  await client.callTool('writeMemory', {
    address: testAddr,
    bytes: [originalValue],
  });
});

// === REGISTER TESTS ===

test('getRegisters - returns CPU state', async (client) => {
  const result = await client.callTool('getRegisters') as Record<string, unknown>;
  assertNoError(result, 'getRegisters');
  assertExists(result.a, 'should have accumulator');
  assertExists(result.x, 'should have X register');
  assertExists(result.y, 'should have Y register');
  assertExists(result.sp, 'should have stack pointer');
  assertExists(result.pc, 'should have program counter');
  assertExists(result.flags, 'should have flags');
});

// === SEMANTIC LAYER TESTS ===

test('readScreen - decodes PETSCII', async (client) => {
  const result = await client.callTool('readScreen') as Record<string, unknown>;
  assertNoError(result, 'readScreen');
  assertExists(result.lines, 'should have lines array');
  assert(Array.isArray(result.lines), 'lines should be array');
  assert((result.lines as string[]).length === 25, 'should have 25 lines');
  assertExists(result.screenAddress, 'should have screen address');
});

test('readVicState - interprets VIC-II', async (client) => {
  const result = await client.callTool('readVicState') as Record<string, unknown>;
  assertNoError(result, 'readVicState');
  assertExists(result.borderColor, 'should have border color');
  assertExists(result.backgroundColor, 'should have background color');
  assertExists(result.graphicsMode, 'should have graphics mode');
  assertExists(result.spriteEnable, 'should have sprite enable');

  // Check border color has name
  const border = result.borderColor as Record<string, unknown>;
  assertExists(border.name, 'border color should have name');
});

test('readSprites - returns all 8 sprites with diagnostics', async (client) => {
  const result = await client.callTool('readSprites') as Record<string, unknown>;
  assertNoError(result, 'readSprites');
  assert(result.count === 8, 'should have 8 sprites');
  assertExists(result.sprites, 'should have sprites array');

  const sprites = result.sprites as Array<Record<string, unknown>>;
  assert(sprites.length === 8, 'sprites array should have 8 entries');

  // Check first sprite has required fields
  const sprite0 = sprites[0];
  assertExists(sprite0.enabled, 'sprite should have enabled');
  assertExists(sprite0.position, 'sprite should have position');
  assertExists(sprite0.color, 'sprite should have color');
  assertExists(sprite0.dataAddress, 'sprite should have dataAddress');

  // Check dataAddress has diagnostics (AX design)
  const dataAddr = sprite0.dataAddress as Record<string, unknown>;
  assertExists(dataAddr.region, 'dataAddress should have region');
  assertExists(dataAddr.severity, 'dataAddress should have severity');
});

test('readColorRam - returns color info', async (client) => {
  const result = await client.callTool('readColorRam', { summary: true }) as Record<string, unknown>;
  assertNoError(result, 'readColorRam');
  assertExists(result.summary, 'should have summary');
  const summary = result.summary as Record<string, unknown>;
  assertExists(summary.usage, 'should have color usage');
});

// === EXECUTION CONTROL TESTS ===

test('step - executes single instruction', async (client) => {
  const before = await client.callTool('getRegisters') as Record<string, unknown>;
  const pcBefore = (before.pc as Record<string, unknown>).value;

  const result = await client.callTool('step') as Record<string, unknown>;
  assertNoError(result, 'step');

  const after = await client.callTool('getRegisters') as Record<string, unknown>;
  const pcAfter = (after.pc as Record<string, unknown>).value;

  // PC should have changed (unless we hit a JAM)
  // Just verify we got a response
  assertExists(pcAfter, 'should have PC after step');
});

test('continue - resumes execution', async (client) => {
  const result = await client.callTool('continue') as Record<string, unknown>;
  assertNoError(result, 'continue');

  // Give it a moment to run
  await new Promise(r => setTimeout(r, 100));

  const status = await client.callTool('status') as Record<string, unknown>;
  // Should be running now
  assertExists(status.running, 'should have running state');
});

// === BREAKPOINT TESTS ===

test('setBreakpoint - creates breakpoint', async (client) => {
  const result = await client.callTool('setBreakpoint', {
    address: 0xE000,
  }) as Record<string, unknown>;
  assertNoError(result, 'setBreakpoint');
  assertExists(result.breakpointId, 'should return breakpoint ID');

  // Clean up
  const bpId = result.breakpointId as number;
  await client.callTool('deleteBreakpoint', { breakpointId: bpId });
});

test('listBreakpoints - shows breakpoints', async (client) => {
  // Create a breakpoint
  const bp = await client.callTool('setBreakpoint', {
    address: 0xE544,
  }) as Record<string, unknown>;
  const bpId = bp.breakpointId as number;

  const result = await client.callTool('listBreakpoints') as Record<string, unknown>;
  assertNoError(result, 'listBreakpoints');
  assertExists(result.breakpoints, 'should have breakpoints array');

  // Clean up
  await client.callTool('deleteBreakpoint', { breakpointId: bpId });
});

test('setWatchpoint - creates memory watch', async (client) => {
  const result = await client.callTool('setWatchpoint', {
    startAddress: 0xD020,
    type: 'store',
  }) as Record<string, unknown>;
  assertNoError(result, 'setWatchpoint');
  assertExists(result.watchpointId, 'should return watchpoint ID');

  // Clean up
  const wpId = result.watchpointId as number;
  await client.callTool('deleteBreakpoint', { breakpointId: wpId });
});

// === DISASSEMBLY TEST ===

test('disassemble - shows assembly', async (client) => {
  const result = await client.callTool('disassemble', {
    address: 0xE000,
    count: 5,
  }) as Record<string, unknown>;
  assertNoError(result, 'disassemble');
  assertExists(result.instructions, 'should have instructions');

  const instrs = result.instructions as Array<Record<string, unknown>>;
  assert(instrs.length === 5, 'should have 5 instructions');

  // Check instruction format
  const instr0 = instrs[0];
  assertExists(instr0.address, 'instruction should have address');
  assertExists(instr0.mnemonic, 'instruction should have mnemonic');
});

// === RESET TEST ===

test('reset - soft resets machine', async (client) => {
  const result = await client.callTool('reset', { hard: false }) as Record<string, unknown>;
  assertNoError(result, 'reset');

  // Give it time to reset
  await new Promise(r => setTimeout(r, 500));

  // Check we're still connected
  const status = await client.callTool('status') as Record<string, unknown>;
  assert(status.connected === true, 'should still be connected after reset');
});

// === RUN TESTS ===

async function runTests() {
  const serverPath = path.join(__dirname, '..', 'dist', 'index.js');
  console.log(`\nVICE MCP Integration Tests`);
  console.log(`==========================`);
  console.log(`Server: ${serverPath}\n`);

  const client = new MCPTestClient(serverPath);
  const results: TestResult[] = [];

  // Wait for server to start
  await new Promise(r => setTimeout(r, 500));

  // Initialize MCP session
  try {
    await client.call('initialize', {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: { name: 'integration-test', version: '1.0.0' },
    });
  } catch (e) {
    console.error('Failed to initialize MCP session:', e);
    client.close();
    process.exit(1);
  }

  for (const { name, fn } of tests) {
    const start = Date.now();
    try {
      await fn(client);
      results.push({ name, passed: true, duration: Date.now() - start });
      console.log(`  ✓ ${name} (${Date.now() - start}ms)`);
    } catch (e) {
      const error = e instanceof Error ? e.message : String(e);
      results.push({ name, passed: false, error, duration: Date.now() - start });
      console.log(`  ✗ ${name}: ${error}`);
    }
  }

  client.close();

  // Summary
  const passed = results.filter(r => r.passed).length;
  const failed = results.filter(r => !r.passed).length;
  const totalTime = results.reduce((sum, r) => sum + r.duration, 0);

  console.log(`\n---------------------------`);
  console.log(`Passed: ${passed}/${results.length}`);
  console.log(`Failed: ${failed}`);
  console.log(`Total time: ${totalTime}ms`);

  if (failed > 0) {
    console.log(`\nFailed tests:`);
    for (const r of results.filter(r => !r.passed)) {
      console.log(`  - ${r.name}: ${r.error}`);
    }
  }

  process.exit(failed > 0 ? 1 : 0);
}

runTests().catch(e => {
  console.error('Test runner error:', e);
  process.exit(1);
});