web-a2e 1.0.0

package/tests/integration/phase-test.js

@@ -0,0 +1,159 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { createContext, runInContext } from 'vm';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function loadWasmModule() {
+  const wasmJsPath = join(__dirname, '..', 'public', 'a2e.js');
+  const wasmDir = dirname(wasmJsPath);
+  const code = readFileSync(wasmJsPath, 'utf8');
+  const context = {
+    module: { exports: {} },
+    exports: {},
+    globalThis: global,
+    console: console,
+    require: (await import('module')).createRequire(import.meta.url),
+    __dirname: wasmDir,
+    __filename: wasmJsPath,
+    process: process,
+    WebAssembly: WebAssembly,
+    URL: URL,
+    TextDecoder: TextDecoder,
+    setTimeout: setTimeout,
+    clearTimeout: clearTimeout,
+    performance: { now: () => Date.now() }
+  };
+  createContext(context);
+  runInContext(code, context);
+  return context.module.exports;
+}
+
+async function runTest() {
+  const createA2EModule = await loadWasmModule();
+  const Module = await createA2EModule();
+  Module._init();
+
+  const diskPath = join(__dirname, '..', 'public', 'Apple DOS 3.3 August 1980.dsk');
+  const diskData = readFileSync(diskPath);
+  const diskPtr = Module._malloc(diskData.length);
+  Module.HEAPU8.set(diskData, diskPtr);
+  const filename = 'test.dsk';
+  const filenamePtr = Module._malloc(filename.length + 1);
+  Module.stringToUTF8(filename, filenamePtr, filename.length + 1);
+  Module._insertDisk(0, diskPtr, diskData.length, filenamePtr);
+  Module._free(filenamePtr);
+
+  console.log('=== PHASE/HEAD MOVEMENT TEST ===\n');
+
+  // Manually test phase switching by writing to soft switches
+  // Slot 6 soft switches: $C0E0-$C0EF
+  // Phase 0: $C0E0 (off), $C0E1 (on)
+  // Phase 1: $C0E2 (off), $C0E3 (on)
+  // Phase 2: $C0E4 (off), $C0E5 (on)
+  // Phase 3: $C0E6 (off), $C0E7 (on)
+  // Motor: $C0E8 (off), $C0E9 (on)
+
+  const getTrack = () => Module._getDiskTrack(0);
+  const getQuarterTrack = () => Module._getDiskHeadPosition(0);
+  const getPhaseStates = () => Module._getDiskPhase(0);
+
+  console.log('Initial state:');
+  console.log('  Track: ' + getTrack() + ', Quarter-track: ' + getQuarterTrack() + ', Phases: ' + getPhaseStates().toString(2).padStart(4, '0'));
+
+  // Turn on motor
+  Module._readMemory(0xC0E9);  // Motor on
+  Module._runCycles(100);
+
+  console.log('\nAfter motor on:');
+  console.log('  Motor: ' + Module._getDiskMotorOn(0));
+
+  // Test stepping from track 0 to track 1
+  // Starting at track 0 (quarter-track 0), phase 0 should be on
+  // To move to track 1 (quarter-track 4):
+  // Phase 0 -> Phase 1 (+2 QT) -> Phase 2 (+2 QT) = quarter-track 4
+
+  console.log('\n=== Testing step from track 0 to track 1 ===');
+  console.log('Expected sequence: Phase 0 -> 1 -> 2 (quarter-tracks 0 -> 2 -> 4)');
+
+  // Make sure we start at track 0
+  Module._readMemory(0xC0E1);  // Phase 0 on
+  Module._runCycles(10);
+  console.log('\nPhase 0 on:');
+  console.log('  Quarter-track: ' + getQuarterTrack() + ', Phases: ' + getPhaseStates().toString(2).padStart(4, '0'));
+
+  // Step to phase 1
+  Module._readMemory(0xC0E0);  // Phase 0 off
+  Module._readMemory(0xC0E3);  // Phase 1 on
+  Module._runCycles(10);
+  console.log('\nPhase 1 on (phase 0 off):');
+  console.log('  Quarter-track: ' + getQuarterTrack() + ', Track: ' + getTrack() + ', Phases: ' + getPhaseStates().toString(2).padStart(4, '0'));
+
+  // Step to phase 2
+  Module._readMemory(0xC0E2);  // Phase 1 off
+  Module._readMemory(0xC0E5);  // Phase 2 on
+  Module._runCycles(10);
+  console.log('\nPhase 2 on (phase 1 off):');
+  console.log('  Quarter-track: ' + getQuarterTrack() + ', Track: ' + getTrack() + ', Phases: ' + getPhaseStates().toString(2).padStart(4, '0'));
+
+  // Should now be at track 1 (quarter-track 4)
+  console.log('\n=== Expected: Quarter-track 4, Track 1 ===');
+
+  // Test stepping back to track 0
+  console.log('\n=== Testing step from track 1 back to track 0 ===');
+  console.log('Expected sequence: Phase 2 -> 1 -> 0 (quarter-tracks 4 -> 2 -> 0)');
+
+  // Step to phase 1
+  Module._readMemory(0xC0E4);  // Phase 2 off
+  Module._readMemory(0xC0E3);  // Phase 1 on
+  Module._runCycles(10);
+  console.log('\nPhase 1 on (phase 2 off):');
+  console.log('  Quarter-track: ' + getQuarterTrack() + ', Track: ' + getTrack() + ', Phases: ' + getPhaseStates().toString(2).padStart(4, '0'));
+
+  // Step to phase 0
+  Module._readMemory(0xC0E2);  // Phase 1 off
+  Module._readMemory(0xC0E1);  // Phase 0 on
+  Module._runCycles(10);
+  console.log('\nPhase 0 on (phase 1 off):');
+  console.log('  Quarter-track: ' + getQuarterTrack() + ', Track: ' + getTrack() + ', Phases: ' + getPhaseStates().toString(2).padStart(4, '0'));
+
+  console.log('\n=== Expected: Quarter-track 0, Track 0 ===');
+
+  // Now test multiple track stepping
+  console.log('\n=== Testing multiple track step (track 0 -> track 5) ===');
+  
+  // Reset to track 0
+  Module._readMemory(0xC0E1);  // Phase 0 on
+  Module._runCycles(10);
+  
+  for (let targetTrack = 1; targetTrack <= 5; targetTrack++) {
+    // Step through phases: 0 -> 1 -> 2 -> 3 -> 0 (repeats)
+    const phases = [0xC0E1, 0xC0E3, 0xC0E5, 0xC0E7];  // Phase on addresses
+    const phaseOff = [0xC0E0, 0xC0E2, 0xC0E4, 0xC0E6];  // Phase off addresses
+    
+    // Calculate current phase from quarter-track
+    const qt = getQuarterTrack();
+    const currentPhase = (qt / 2) % 4;
+    const nextPhase = (currentPhase + 1) % 4;
+    
+    // Turn off current phase
+    Module._readMemory(phaseOff[currentPhase]);
+    // Turn on next phase
+    Module._readMemory(phases[nextPhase]);
+    Module._runCycles(10);
+    
+    // Step again to complete the track
+    const phase2 = (nextPhase + 1) % 4;
+    Module._readMemory(phaseOff[nextPhase]);
+    Module._readMemory(phases[phase2]);
+    Module._runCycles(10);
+    
+    console.log('After stepping to track ' + targetTrack + ': Quarter-track=' + getQuarterTrack() + ', Track=' + getTrack());
+  }
+
+  Module._free(diskPtr);
+}
+
+runTest().catch(err => { console.error(err); process.exit(1); });

package/tests/integration/test_emulator.cpp

@@ -0,0 +1,291 @@
+/*
+ * test_emulator.cpp - Integration tests for the Emulator class
+ *
+ * Tests the full emulator coordinator including initialization, reset,
+ * execution, memory access, video, beam position, soft switches,
+ * slot management, screen text, disassembly, and speed control.
+ */
+
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+
+#include "emulator.hpp"
+
+using namespace a2e;
+
+// ---------------------------------------------------------------------------
+// Initialization
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator init does not crash", "[emulator][init]") {
+    Emulator emu;
+    REQUIRE_NOTHROW(emu.init());
+}
+
+TEST_CASE("Emulator PC points to reset vector destination after init", "[emulator][init]") {
+    Emulator emu;
+    emu.init();
+
+    // After reset, the 65C02 reads the reset vector at $FFFC/$FFFD and sets
+    // PC to that address.  The Apple IIe ROM reset vector points into the
+    // $FA00-$FFFF range (monitor / reset handler).
+    uint16_t pc = emu.getPC();
+    REQUIRE(pc >= 0xC000);
+    REQUIRE(pc <= 0xFFFF);
+}
+
+// ---------------------------------------------------------------------------
+// Reset
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator reset returns PC to reset vector", "[emulator][reset]") {
+    Emulator emu;
+    emu.init();
+
+    uint16_t pcAfterInit = emu.getPC();
+
+    // Run some cycles to move PC away from the reset address
+    emu.runCycles(1000);
+    REQUIRE(emu.getPC() != pcAfterInit);
+
+    // Reset should return PC to the same reset vector destination
+    emu.reset();
+    REQUIRE(emu.getPC() == pcAfterInit);
+}
+
+TEST_CASE("Emulator warmReset preserves memory but resets PC", "[emulator][reset]") {
+    Emulator emu;
+    emu.init();
+
+    uint16_t pcAfterInit = emu.getPC();
+
+    // Write a known value into low RAM
+    emu.writeMemory(0x0300, 0xAB);
+    REQUIRE(emu.readMemory(0x0300) == 0xAB);
+
+    // Run some cycles to move PC
+    emu.runCycles(1000);
+
+    // Warm reset: memory preserved, PC returns to reset vector
+    emu.warmReset();
+    REQUIRE(emu.getPC() == pcAfterInit);
+    REQUIRE(emu.readMemory(0x0300) == 0xAB);
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator runCycles advances cycles and PC", "[emulator][execution]") {
+    Emulator emu;
+    emu.init();
+
+    uint16_t pcBefore = emu.getPC();
+    uint64_t cyclesBefore = emu.getTotalCycles();
+
+    emu.runCycles(100);
+
+    REQUIRE(emu.getTotalCycles() > cyclesBefore);
+    REQUIRE(emu.getPC() != pcBefore);
+}
+
+TEST_CASE("Emulator stepInstruction executes one instruction", "[emulator][execution]") {
+    Emulator emu;
+    emu.init();
+
+    uint64_t cyclesBefore = emu.getTotalCycles();
+    uint16_t pcBefore = emu.getPC();
+
+    emu.stepInstruction();
+
+    // At least 2 cycles for the shortest 65C02 instruction, PC should have moved
+    REQUIRE(emu.getTotalCycles() > cyclesBefore);
+    REQUIRE(emu.getTotalCycles() <= cyclesBefore + 7); // max 7 cycles for any instruction
+    REQUIRE(emu.getPC() != pcBefore);
+}
+
+// ---------------------------------------------------------------------------
+// Pause
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator setPaused and isPaused", "[emulator][pause]") {
+    Emulator emu;
+    emu.init();
+
+    REQUIRE_FALSE(emu.isPaused());
+
+    emu.setPaused(true);
+    REQUIRE(emu.isPaused());
+
+    // runCycles should not advance when paused
+    uint64_t cyclesBefore = emu.getTotalCycles();
+    emu.runCycles(1000);
+    REQUIRE(emu.getTotalCycles() == cyclesBefore);
+
+    emu.setPaused(false);
+    REQUIRE_FALSE(emu.isPaused());
+}
+
+// ---------------------------------------------------------------------------
+// Memory access
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator writeMemory and readMemory round-trip", "[emulator][memory]") {
+    Emulator emu;
+    emu.init();
+
+    emu.writeMemory(0x0400, 0x42);
+    REQUIRE(emu.readMemory(0x0400) == 0x42);
+}
+
+TEST_CASE("Emulator peekMemory reads same as readMemory for normal RAM", "[emulator][memory]") {
+    Emulator emu;
+    emu.init();
+
+    emu.writeMemory(0x0400, 0x55);
+    REQUIRE(emu.peekMemory(0x0400) == emu.readMemory(0x0400));
+}
+
+// ---------------------------------------------------------------------------
+// Video / Framebuffer
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator getFramebuffer returns non-null after init", "[emulator][video]") {
+    Emulator emu;
+    emu.init();
+
+    const uint8_t* fb = emu.getFramebuffer();
+    REQUIRE(fb != nullptr);
+}
+
+TEST_CASE("Emulator getFramebufferSize equals expected RGBA buffer size", "[emulator][video]") {
+    Emulator emu;
+    emu.init();
+
+    // 560 * 384 * 4 (RGBA) = 860160
+    REQUIRE(emu.getFramebufferSize() == 860160);
+}
+
+// ---------------------------------------------------------------------------
+// Beam position
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator beam position returns valid scanline and hPos", "[emulator][beam]") {
+    Emulator emu;
+    emu.init();
+
+    // Run a few cycles so beam position is somewhere meaningful
+    emu.runCycles(200);
+
+    int scanline = emu.getBeamScanline();
+    int hPos = emu.getBeamHPos();
+
+    REQUIRE(scanline >= 0);
+    REQUIRE(scanline < 262);  // 262 scanlines per NTSC frame
+    REQUIRE(hPos >= 0);
+    REQUIRE(hPos < 65);       // 65 cycles per scanline
+}
+
+// ---------------------------------------------------------------------------
+// Soft switches
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator getSoftSwitchState returns packed state", "[emulator][softswitch]") {
+    Emulator emu;
+    emu.init();
+
+    // getSoftSwitchState returns a 64-bit packed value; just verify it is callable
+    // and produces a reasonable value (all zeros except TEXT mode which is set by default)
+    uint64_t state = emu.getSoftSwitchState();
+    // TEXT mode bit (bit 0) should be set on a fresh init
+    REQUIRE((state & 0x01) == 0x01);
+}
+
+// ---------------------------------------------------------------------------
+// Slot management
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator slot management: isSlotEmpty and getSlotCardName", "[emulator][slots]") {
+    Emulator emu;
+    emu.init();
+
+    SECTION("Slot 3 is never empty (built-in 80-column)") {
+        REQUIRE_FALSE(emu.isSlotEmpty(3));
+        REQUIRE(std::string(emu.getSlotCardName(3)) == "80col");
+    }
+
+    SECTION("Slot 6 has Disk II by default") {
+        REQUIRE_FALSE(emu.isSlotEmpty(6));
+        REQUIRE(std::string(emu.getSlotCardName(6)) == "disk2");
+    }
+
+    SECTION("Slot 4 has Mockingboard by default") {
+        REQUIRE_FALSE(emu.isSlotEmpty(4));
+        REQUIRE(std::string(emu.getSlotCardName(4)) == "mockingboard");
+    }
+
+    SECTION("Slot 1 is empty by default") {
+        REQUIRE(emu.isSlotEmpty(1));
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Screen text
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator readScreenText returns a string", "[emulator][screen]") {
+    Emulator emu;
+    emu.init();
+
+    // Read full screen (24 rows x 40 cols)
+    const char* text = emu.readScreenText(0, 0, 23, 39);
+    REQUIRE(text != nullptr);
+}
+
+// ---------------------------------------------------------------------------
+// Disassembly
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator disassembleAt returns non-empty string", "[emulator][disasm]") {
+    Emulator emu;
+    emu.init();
+
+    // Disassemble at current PC (should be in ROM after reset)
+    const char* disasm = emu.disassembleAt(emu.getPC());
+    REQUIRE(disasm != nullptr);
+    REQUIRE(std::string(disasm).length() > 0);
+}
+
+// ---------------------------------------------------------------------------
+// Speed control
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator speed multiplier set and get", "[emulator][speed]") {
+    Emulator emu;
+    emu.init();
+
+    REQUIRE(emu.getSpeedMultiplier() == 1);
+
+    emu.setSpeedMultiplier(2);
+    REQUIRE(emu.getSpeedMultiplier() == 2);
+
+    emu.setSpeedMultiplier(8);
+    REQUIRE(emu.getSpeedMultiplier() == 8);
+
+    // Values are clamped to 1-8
+    emu.setSpeedMultiplier(0);
+    REQUIRE(emu.getSpeedMultiplier() == 1);
+
+    emu.setSpeedMultiplier(100);
+    REQUIRE(emu.getSpeedMultiplier() == 8);
+}
+
+// ---------------------------------------------------------------------------
+// screenCodeToAscii
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator screenCodeToAscii converts known codes", "[emulator][screen]") {
+    // Normal ASCII 'A' = 0xC1 in Apple II screen memory
+    int result = Emulator::screenCodeToAscii(0xC1);
+    REQUIRE(result == 'A');
+}

package/tests/integration/test_emulator_basic.cpp

@@ -0,0 +1,91 @@
+/*
+ * test_emulator_basic.cpp - Integration tests for Emulator BASIC debugging
+ *
+ * Tests BASIC program tracking, BASIC breakpoints, BASIC error state,
+ * and related BASIC debugging API through the Emulator facade.
+ */
+
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+
+#include "emulator.hpp"
+
+using namespace a2e;
+
+// ---------------------------------------------------------------------------
+// BASIC program running state
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator isBasicProgramRunning is false after init", "[emulator][basic]") {
+    Emulator emu;
+    emu.init();
+
+    REQUIRE_FALSE(emu.isBasicProgramRunning());
+}
+
+// ---------------------------------------------------------------------------
+// BASIC breakpoints
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator addBasicBreakpoint makes hasBasicBreakpoints true", "[emulator][basic][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    REQUIRE_FALSE(emu.hasBasicBreakpoints());
+
+    emu.addBasicBreakpoint(10, -1); // Line 10, whole line
+    REQUIRE(emu.hasBasicBreakpoints());
+}
+
+TEST_CASE("Emulator clearBasicBreakpoints removes all BASIC breakpoints", "[emulator][basic][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    emu.addBasicBreakpoint(10, -1);
+    emu.addBasicBreakpoint(20, 0);
+    REQUIRE(emu.hasBasicBreakpoints());
+
+    emu.clearBasicBreakpoints();
+    REQUIRE_FALSE(emu.hasBasicBreakpoints());
+}
+
+TEST_CASE("Emulator removeBasicBreakpoint removes specific breakpoint", "[emulator][basic][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    emu.addBasicBreakpoint(10, -1);
+    emu.removeBasicBreakpoint(10, -1);
+
+    REQUIRE_FALSE(emu.hasBasicBreakpoints());
+}
+
+// ---------------------------------------------------------------------------
+// BASIC breakpoint hit state
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator isBasicBreakpointHit is initially false", "[emulator][basic][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    REQUIRE_FALSE(emu.isBasicBreakpointHit());
+}
+
+TEST_CASE("Emulator clearBasicBreakpointHit clears hit state", "[emulator][basic][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    // Hit state should already be false; clearing it should not crash
+    emu.clearBasicBreakpointHit();
+    REQUIRE_FALSE(emu.isBasicBreakpointHit());
+}
+
+// ---------------------------------------------------------------------------
+// BASIC error state
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator isBasicErrorHit is initially false", "[emulator][basic][error]") {
+    Emulator emu;
+    emu.init();
+
+    REQUIRE_FALSE(emu.isBasicErrorHit());
+}