web-a2e 1.0.0

package/tests/unit/test_cpu_interrupts.cpp

@@ -0,0 +1,285 @@
+/*
+ * test_cpu_interrupts.cpp - 65C02 interrupt handling tests
+ *
+ * Tests BRK, IRQ, NMI behavior, RTI, and level-triggered IRQ
+ * via the IRQ status callback mechanism.
+ */
+
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+#include "test_helpers.hpp"
+
+// ============================================================================
+// BRK Instruction
+// ============================================================================
+
+TEST_CASE("BRK instruction behavior", "[cpu][interrupt]") {
+
+    SECTION("BRK pushes PC+2 onto stack") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x1000);
+        // NOP at handler to prevent undefined behavior
+        f.mem.loadProgram(0x1000, {0xEA});
+        f.loadAndReset(0x0400, {0x00, 0xEA}); // BRK, padding
+        uint8_t spBefore = f.cpu->getSP();
+        f.cpu->executeInstruction();
+
+        // BRK pushes PC+2 (address after BRK + signature byte)
+        uint8_t retHi = f.mem[0x0100 + spBefore];
+        uint8_t retLo = f.mem[0x0100 + spBefore - 1];
+        uint16_t retAddr = (retHi << 8) | retLo;
+        REQUIRE(retAddr == 0x0402);
+    }
+
+    SECTION("BRK pushes P with B flag set") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x1000);
+        f.mem.loadProgram(0x1000, {0xEA});
+        f.loadAndReset(0x0400, {0x00, 0xEA});
+        uint8_t spBefore = f.cpu->getSP();
+        f.cpu->executeInstruction();
+
+        // P is pushed after the two PC bytes, at SP+3 from final SP
+        uint8_t pushedP = f.mem[0x0100 + spBefore - 2];
+        REQUIRE((pushedP & a2e::FLAG_B) != 0); // B flag set in pushed P
+        REQUIRE((pushedP & a2e::FLAG_U) != 0); // U flag always set
+    }
+
+    SECTION("BRK jumps to IRQ vector") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x1000);
+        f.mem.loadProgram(0x1000, {0xEA});
+        f.loadAndReset(0x0400, {0x00, 0xEA});
+        f.cpu->executeInstruction();
+        REQUIRE(f.cpu->getPC() == 0x1000);
+    }
+
+    SECTION("BRK sets I flag") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x1000);
+        f.mem.loadProgram(0x1000, {0xEA});
+        f.loadAndReset(0x0400, {0x00, 0xEA});
+        f.cpu->setFlag(a2e::FLAG_I, false);
+        f.cpu->executeInstruction();
+        REQUIRE(f.cpu->getFlag(a2e::FLAG_I) == true);
+    }
+
+    SECTION("BRK clears D flag on 65C02") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x1000);
+        f.mem.loadProgram(0x1000, {0xEA});
+        // SED; BRK
+        f.loadAndReset(0x0400, {0xF8, 0x00, 0xEA});
+        test::runInstructions(*f.cpu, 2);
+        // On 65C02, BRK clears D flag
+        REQUIRE(f.cpu->getFlag(a2e::FLAG_D) == false);
+    }
+}
+
+// ============================================================================
+// IRQ - Maskable Interrupt
+// ============================================================================
+
+TEST_CASE("IRQ behavior", "[cpu][interrupt]") {
+
+    SECTION("IRQ fires when I flag is clear") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x2000);
+        f.mem.loadProgram(0x2000, {0xEA}); // NOP at handler
+        // CLI; NOP; NOP
+        f.loadAndReset(0x0400, {0x58, 0xEA, 0xEA});
+        f.cpu->executeInstruction(); // CLI
+
+        // Trigger IRQ
+        f.cpu->irq();
+        f.cpu->executeInstruction(); // This NOP should complete, then IRQ fires
+        f.cpu->executeInstruction(); // Process the IRQ
+
+        REQUIRE(f.cpu->getPC() == 0x2001); // One instruction into handler (NOP executed)
+    }
+
+    SECTION("IRQ does not fire when I flag is set") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x2000);
+        f.mem.loadProgram(0x2000, {0xEA});
+        // SEI; NOP; NOP
+        f.loadAndReset(0x0400, {0x78, 0xEA, 0xEA});
+        f.cpu->executeInstruction(); // SEI
+
+        f.cpu->irq();
+        f.cpu->executeInstruction(); // NOP at $0401
+        f.cpu->executeInstruction(); // NOP at $0402
+
+        // Should still be executing main code, not at handler
+        REQUIRE(f.cpu->getPC() == 0x0403);
+    }
+
+    SECTION("IRQ pushes PC and P with B flag clear") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x2000);
+        f.mem.loadProgram(0x2000, {0xEA, 0xEA});
+        // CLI; NOP (will be interrupted after this)
+        f.loadAndReset(0x0400, {0x58, 0xEA, 0xEA});
+        f.cpu->executeInstruction(); // CLI
+        f.cpu->irq();
+        uint8_t spBefore = f.cpu->getSP();
+        f.cpu->executeInstruction(); // NOP completes
+        f.cpu->executeInstruction(); // IRQ serviced
+
+        // P pushed during IRQ should have B flag CLEAR (unlike BRK)
+        uint8_t pushedP = f.mem[0x0100 + spBefore - 2];
+        REQUIRE((pushedP & a2e::FLAG_B) == 0);
+    }
+
+    SECTION("IRQ sets I flag") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x2000);
+        f.mem.loadProgram(0x2000, {0xEA});
+        f.loadAndReset(0x0400, {0x58, 0xEA}); // CLI; NOP
+        f.cpu->executeInstruction(); // CLI
+        f.cpu->irq();
+        f.cpu->executeInstruction(); // NOP
+        f.cpu->executeInstruction(); // IRQ serviced
+
+        REQUIRE(f.cpu->getFlag(a2e::FLAG_I) == true);
+    }
+}
+
+// ============================================================================
+// NMI - Non-Maskable Interrupt
+// ============================================================================
+
+TEST_CASE("NMI behavior", "[cpu][interrupt]") {
+
+    SECTION("NMI fires regardless of I flag") {
+        test::CPUTestFixture f;
+        f.mem.setNMIVector(0x3000);
+        f.mem.loadProgram(0x3000, {0xEA, 0xEA});
+        // SEI; NOP (NMI should still fire even with I set)
+        f.loadAndReset(0x0400, {0x78, 0xEA, 0xEA});
+        f.cpu->executeInstruction(); // SEI
+        f.cpu->nmi();
+        f.cpu->executeInstruction(); // NOP completes
+        f.cpu->executeInstruction(); // NMI serviced
+
+        // Should be at NMI handler
+        REQUIRE(f.cpu->getPC() == 0x3001);
+    }
+
+    SECTION("NMI pushes PC and P") {
+        test::CPUTestFixture f;
+        f.mem.setNMIVector(0x3000);
+        f.mem.loadProgram(0x3000, {0xEA, 0xEA});
+        f.loadAndReset(0x0400, {0xEA, 0xEA}); // NOP; NOP
+        uint8_t spBefore = f.cpu->getSP();
+        f.cpu->nmi();
+        f.cpu->executeInstruction(); // NOP completes
+        f.cpu->executeInstruction(); // NMI serviced
+
+        // SP should have moved down by 3 (PCH, PCL, P)
+        REQUIRE(f.cpu->getSP() == static_cast<uint8_t>(spBefore - 3));
+    }
+
+    SECTION("NMI jumps to NMI vector") {
+        test::CPUTestFixture f;
+        f.mem.setNMIVector(0x3000);
+        f.mem.loadProgram(0x3000, {0xEA});
+        f.loadAndReset(0x0400, {0xEA}); // NOP
+        f.cpu->nmi();
+        f.cpu->executeInstruction(); // NOP completes
+        f.cpu->executeInstruction(); // NMI serviced
+        REQUIRE(f.cpu->getPC() == 0x3001); // After executing NOP at $3000
+    }
+}
+
+// ============================================================================
+// IRQ Status Callback (Level-Triggered IRQs)
+// ============================================================================
+
+TEST_CASE("IRQ status callback for level-triggered IRQs", "[cpu][interrupt]") {
+
+    SECTION("IRQ status callback triggers repeated interrupts while active") {
+        test::CPUTestFixture f;
+        bool irqActive = true;
+
+        f.mem.setIRQVector(0x2000);
+        // Handler: increment counter memory location, RTI
+        // LDA $10; CLC; ADC #$01; STA $10; RTI
+        f.mem.loadProgram(0x2000, {0xA5, 0x10, 0x18, 0x69, 0x01, 0x85, 0x10, 0x40});
+        f.mem[0x10] = 0x00;
+
+        // Main: CLI; NOP loop
+        f.loadAndReset(0x0400, {0x58, 0xEA, 0xEA, 0xEA, 0xEA, 0xEA, 0xEA, 0xEA,
+                                0xEA, 0xEA, 0xEA, 0xEA, 0xEA, 0xEA, 0xEA, 0xEA});
+
+        f.cpu->setIRQStatusCallback([&irqActive]() { return irqActive; });
+
+        // Run CLI
+        f.cpu->executeInstruction();
+
+        // Trigger IRQ and run enough instructions for it to be serviced and return
+        f.cpu->irq();
+        test::runInstructions(*f.cpu, 20);
+
+        // Counter should have been incremented at least once
+        REQUIRE(f.mem[0x10] >= 1);
+    }
+}
+
+// ============================================================================
+// RTI - Return from Interrupt
+// ============================================================================
+
+TEST_CASE("RTI instruction", "[cpu][interrupt]") {
+
+    SECTION("RTI restores P and PC from stack") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x2000);
+        // Handler: LDA #$42; RTI
+        f.mem.loadProgram(0x2000, {0xA9, 0x42, 0x40});
+
+        // Main: CLC; CLI; NOP; LDX #$99
+        f.loadAndReset(0x0400, {0x18, 0x58, 0xEA, 0xA2, 0x99});
+        f.cpu->executeInstruction(); // CLC
+        f.cpu->executeInstruction(); // CLI
+
+        uint8_t pBeforeIRQ = f.cpu->getP();
+        f.cpu->irq();
+        f.cpu->executeInstruction(); // NOP completes
+        f.cpu->executeInstruction(); // IRQ serviced, now at handler
+
+        // Execute handler: LDA #$42
+        f.cpu->executeInstruction();
+        REQUIRE(f.cpu->getA() == 0x42);
+
+        // RTI should restore PC and P
+        f.cpu->executeInstruction(); // RTI
+        // PC should be back to where we were interrupted
+        // After RTI, should execute LDX #$99
+        f.cpu->executeInstruction(); // LDX #$99
+        REQUIRE(f.cpu->getX() == 0x99);
+    }
+
+    SECTION("RTI restores flags correctly") {
+        test::CPUTestFixture f;
+        f.mem.setIRQVector(0x2000);
+        // Handler: SEC; RTI (modifies carry, but RTI restores original flags)
+        f.mem.loadProgram(0x2000, {0x38, 0x40});
+
+        // Main: CLC; CLI; NOP
+        f.loadAndReset(0x0400, {0x18, 0x58, 0xEA, 0xEA});
+        f.cpu->executeInstruction(); // CLC -> C=0
+        f.cpu->executeInstruction(); // CLI
+
+        f.cpu->irq();
+        // IRQ is serviced at the start of the next executeInstruction call,
+        // before fetching any opcode. So the IRQ fires immediately.
+        f.cpu->executeInstruction(); // IRQ serviced (pushes PC and P, jumps to handler)
+
+        f.cpu->executeInstruction(); // SEC -> C=1 in handler
+        REQUIRE(f.cpu->getFlag(a2e::FLAG_C) == true);
+
+        f.cpu->executeInstruction(); // RTI -> restores original P with C=0
+        REQUIRE(f.cpu->getFlag(a2e::FLAG_C) == false);
+    }
+}

package/tests/unit/test_disassembler.cpp

@@ -0,0 +1,323 @@
+/*
+ * test_disassembler.cpp - Unit tests for 65C02 disassembler
+ */
+
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+
+#include "disassembler.hpp"
+
+#include <cstring>
+
+using namespace a2e;
+
+// ============================================================================
+// disassembleInstruction tests
+// ============================================================================
+
+TEST_CASE("disassembleInstruction NOP (0xEA)", "[disasm][single]") {
+    uint8_t data[] = {0xEA};
+    auto instr = disassembleInstruction(data, sizeof(data), 0x1000);
+
+    CHECK(instr.address == 0x1000);
+    CHECK(instr.length == 1);
+    CHECK(instr.opcode == 0xEA);
+    CHECK(std::string(instr.mnemonic) == "NOP");
+    CHECK(instr.mode == static_cast<uint8_t>(AddrMode::IMP));
+}
+
+TEST_CASE("disassembleInstruction LDA immediate (0xA9)", "[disasm][single]") {
+    uint8_t data[] = {0xA9, 0x42};
+    auto instr = disassembleInstruction(data, sizeof(data), 0x2000);
+
+    CHECK(instr.address == 0x2000);
+    CHECK(instr.length == 2);
+    CHECK(instr.opcode == 0xA9);
+    CHECK(instr.operand1 == 0x42);
+    CHECK(std::string(instr.mnemonic) == "LDA");
+    CHECK(instr.mode == static_cast<uint8_t>(AddrMode::IMM));
+}
+
+TEST_CASE("disassembleInstruction JMP absolute (0x4C)", "[disasm][single]") {
+    uint8_t data[] = {0x4C, 0x00, 0xC0};
+    auto instr = disassembleInstruction(data, sizeof(data), 0x0300);
+
+    CHECK(instr.address == 0x0300);
+    CHECK(instr.length == 3);
+    CHECK(instr.opcode == 0x4C);
+    CHECK(instr.operand1 == 0x00);
+    CHECK(instr.operand2 == 0xC0);
+    CHECK(instr.target == 0xC000);
+    CHECK(std::string(instr.mnemonic) == "JMP");
+    CHECK(instr.mode == static_cast<uint8_t>(AddrMode::ABS));
+}
+
+TEST_CASE("disassembleInstruction BRK (0x00)", "[disasm][single]") {
+    uint8_t data[] = {0x00};
+    auto instr = disassembleInstruction(data, sizeof(data), 0x0400);
+
+    CHECK(instr.address == 0x0400);
+    CHECK(instr.length == 1);
+    CHECK(instr.opcode == 0x00);
+    CHECK(std::string(instr.mnemonic) == "BRK");
+}
+
+TEST_CASE("disassembleInstruction branch instruction calculates target", "[disasm][single]") {
+    // BNE with forward branch (+5)
+    uint8_t data[] = {0xD0, 0x05};
+    auto instr = disassembleInstruction(data, sizeof(data), 0x1000);
+
+    CHECK(instr.length == 2);
+    CHECK(std::string(instr.mnemonic) == "BNE");
+    // Target = address + 2 + offset = 0x1000 + 2 + 5 = 0x1007
+    CHECK(instr.target == 0x1007);
+}
+
+TEST_CASE("disassembleInstruction branch with negative offset", "[disasm][single]") {
+    // BEQ with backward branch (-10 = 0xF6)
+    uint8_t data[] = {0xF0, 0xF6};
+    auto instr = disassembleInstruction(data, sizeof(data), 0x1000);
+
+    CHECK(instr.length == 2);
+    CHECK(std::string(instr.mnemonic) == "BEQ");
+    // Target = 0x1000 + 2 + (-10) = 0x0FF8
+    CHECK(instr.target == 0x0FF8);
+}
+
+TEST_CASE("disassembleInstruction null data returns zero-length", "[disasm][single]") {
+    auto instr = disassembleInstruction(nullptr, 0, 0x0000);
+    CHECK(instr.length == 0);
+}
+
+// ============================================================================
+// disassembleBlock tests
+// ============================================================================
+
+TEST_CASE("disassembleBlock multiple instructions", "[disasm][block]") {
+    // NOP; LDA #$42; RTS
+    uint8_t data[] = {0xEA, 0xA9, 0x42, 0x60};
+    auto result = disassembleBlock(data, sizeof(data), 0x0800);
+
+    REQUIRE(result.instructions.size() == 3);
+
+    CHECK(std::string(result.instructions[0].mnemonic) == "NOP");
+    CHECK(result.instructions[0].address == 0x0800);
+    CHECK(result.instructions[0].length == 1);
+
+    CHECK(std::string(result.instructions[1].mnemonic) == "LDA");
+    CHECK(result.instructions[1].address == 0x0801);
+    CHECK(result.instructions[1].length == 2);
+
+    CHECK(std::string(result.instructions[2].mnemonic) == "RTS");
+    CHECK(result.instructions[2].address == 0x0803);
+    CHECK(result.instructions[2].length == 1);
+}
+
+TEST_CASE("disassembleBlock empty data returns empty result", "[disasm][block]") {
+    auto result = disassembleBlock(nullptr, 0, 0x0000);
+    CHECK(result.instructions.empty());
+}
+
+// ============================================================================
+// disassembleWithFlowAnalysis tests
+// ============================================================================
+
+TEST_CASE("disassembleWithFlowAnalysis traces code paths", "[disasm][flow]") {
+    // Simple subroutine:
+    // 0x1000: LDA #$01  (A9 01)
+    // 0x1002: BNE $1005 (D0 01)
+    // 0x1004: NOP       (EA)
+    // 0x1005: RTS       (60)
+    uint8_t data[] = {0xA9, 0x01, 0xD0, 0x01, 0xEA, 0x60};
+    std::vector<uint16_t> entries = {0x1000};
+
+    auto result = disassembleWithFlowAnalysis(data, sizeof(data), 0x1000, entries);
+
+    // Flow analysis should find all reachable instructions
+    REQUIRE(result.instructions.size() >= 3);
+
+    // Check that we traced both the branch-taken and fall-through paths
+    bool foundLDA = false, foundRTS = false, foundBNE = false;
+    for (const auto& instr : result.instructions) {
+        if (std::string(instr.mnemonic) == "LDA") foundLDA = true;
+        if (std::string(instr.mnemonic) == "BNE") foundBNE = true;
+        if (std::string(instr.mnemonic) == "RTS") foundRTS = true;
+    }
+    CHECK(foundLDA);
+    CHECK(foundBNE);
+    CHECK(foundRTS);
+}
+
+TEST_CASE("disassembleWithFlowAnalysis convenience overload", "[disasm][flow]") {
+    uint8_t data[] = {0xEA, 0x60}; // NOP; RTS
+    auto result = disassembleWithFlowAnalysis(data, sizeof(data), 0x0800);
+
+    REQUIRE(result.instructions.size() == 2);
+    CHECK(std::string(result.instructions[0].mnemonic) == "NOP");
+    CHECK(std::string(result.instructions[1].mnemonic) == "RTS");
+}
+
+// ============================================================================
+// getInstructionLength tests
+// ============================================================================
+
+TEST_CASE("getInstructionLength implied is 1", "[disasm][length]") {
+    // NOP (0xEA) is implied
+    CHECK(getInstructionLength(0xEA) == 1);
+    // RTS (0x60) is implied
+    CHECK(getInstructionLength(0x60) == 1);
+    // BRK (0x00) is implied
+    CHECK(getInstructionLength(0x00) == 1);
+    // INX (0xE8) is implied
+    CHECK(getInstructionLength(0xE8) == 1);
+}
+
+TEST_CASE("getInstructionLength immediate is 2", "[disasm][length]") {
+    // LDA # (0xA9)
+    CHECK(getInstructionLength(0xA9) == 2);
+    // LDX # (0xA2)
+    CHECK(getInstructionLength(0xA2) == 2);
+    // CMP # (0xC9)
+    CHECK(getInstructionLength(0xC9) == 2);
+}
+
+TEST_CASE("getInstructionLength absolute is 3", "[disasm][length]") {
+    // JMP abs (0x4C)
+    CHECK(getInstructionLength(0x4C) == 3);
+    // JSR abs (0x20)
+    CHECK(getInstructionLength(0x20) == 3);
+    // LDA abs (0xAD)
+    CHECK(getInstructionLength(0xAD) == 3);
+    // STA abs (0x8D)
+    CHECK(getInstructionLength(0x8D) == 3);
+}
+
+TEST_CASE("getInstructionLength relative (branches) is 2", "[disasm][length]") {
+    // BNE (0xD0)
+    CHECK(getInstructionLength(0xD0) == 2);
+    // BEQ (0xF0)
+    CHECK(getInstructionLength(0xF0) == 2);
+    // BCC (0x90)
+    CHECK(getInstructionLength(0x90) == 2);
+}
+
+TEST_CASE("getInstructionLength zero page is 2", "[disasm][length]") {
+    // LDA zp (0xA5)
+    CHECK(getInstructionLength(0xA5) == 2);
+    // STA zp (0x85)
+    CHECK(getInstructionLength(0x85) == 2);
+}
+
+// ============================================================================
+// getMnemonic tests
+// ============================================================================
+
+TEST_CASE("getMnemonic returns correct mnemonic strings", "[disasm][mnemonic]") {
+    CHECK(std::string(getMnemonic(0xEA)) == "NOP");
+    CHECK(std::string(getMnemonic(0xA9)) == "LDA");
+    CHECK(std::string(getMnemonic(0x4C)) == "JMP");
+    CHECK(std::string(getMnemonic(0x20)) == "JSR");
+    CHECK(std::string(getMnemonic(0x60)) == "RTS");
+    CHECK(std::string(getMnemonic(0x00)) == "BRK");
+    CHECK(std::string(getMnemonic(0xE8)) == "INX");
+    CHECK(std::string(getMnemonic(0xC8)) == "INY");
+    CHECK(std::string(getMnemonic(0x48)) == "PHA");
+    CHECK(std::string(getMnemonic(0x68)) == "PLA");
+}
+
+// ============================================================================
+// getAddressingMode tests
+// ============================================================================
+
+TEST_CASE("getAddressingMode returns correct modes", "[disasm][addrmode]") {
+    CHECK(getAddressingMode(0xEA) == AddrMode::IMP);   // NOP - implied
+    CHECK(getAddressingMode(0xA9) == AddrMode::IMM);   // LDA # - immediate
+    CHECK(getAddressingMode(0xA5) == AddrMode::ZP);    // LDA zp - zero page
+    CHECK(getAddressingMode(0xAD) == AddrMode::ABS);   // LDA abs - absolute
+    CHECK(getAddressingMode(0xB5) == AddrMode::ZPX);   // LDA zp,X
+    CHECK(getAddressingMode(0xBD) == AddrMode::ABX);   // LDA abs,X
+    CHECK(getAddressingMode(0xB9) == AddrMode::ABY);   // LDA abs,Y
+    CHECK(getAddressingMode(0xA1) == AddrMode::IZX);   // LDA (zp,X)
+    CHECK(getAddressingMode(0xB1) == AddrMode::IZY);   // LDA (zp),Y
+    CHECK(getAddressingMode(0x6C) == AddrMode::IND);   // JMP (abs)
+    CHECK(getAddressingMode(0xD0) == AddrMode::REL);   // BNE rel
+    CHECK(getAddressingMode(0x0A) == AddrMode::ACC);   // ASL A
+}
+
+// ============================================================================
+// getInstructionCategory tests
+// ============================================================================
+
+TEST_CASE("getInstructionCategory returns correct categories", "[disasm][category]") {
+    // Branch instructions
+    CHECK(getInstructionCategory(0x4C) == InstrCategory::BRANCH);   // JMP
+    CHECK(getInstructionCategory(0x20) == InstrCategory::BRANCH);   // JSR
+    CHECK(getInstructionCategory(0xD0) == InstrCategory::BRANCH);   // BNE
+    CHECK(getInstructionCategory(0x60) == InstrCategory::BRANCH);   // RTS
+
+    // Load/store instructions
+    CHECK(getInstructionCategory(0xA9) == InstrCategory::LOAD);     // LDA #
+    CHECK(getInstructionCategory(0x85) == InstrCategory::LOAD);     // STA zp
+    CHECK(getInstructionCategory(0xA2) == InstrCategory::LOAD);     // LDX #
+
+    // Math/logic instructions
+    CHECK(getInstructionCategory(0x69) == InstrCategory::MATH);     // ADC
+    CHECK(getInstructionCategory(0x29) == InstrCategory::MATH);     // AND #
+    CHECK(getInstructionCategory(0xC9) == InstrCategory::MATH);     // CMP #
+
+    // Stack instructions
+    CHECK(getInstructionCategory(0x48) == InstrCategory::STACK);    // PHA
+    CHECK(getInstructionCategory(0x68) == InstrCategory::STACK);    // PLA
+    CHECK(getInstructionCategory(0x00) == InstrCategory::STACK);    // BRK
+
+    // Flag instructions
+    CHECK(getInstructionCategory(0x18) == InstrCategory::FLAG);     // CLC
+    CHECK(getInstructionCategory(0x38) == InstrCategory::FLAG);     // SEC
+    CHECK(getInstructionCategory(0x78) == InstrCategory::FLAG);     // SEI
+}
+
+// ============================================================================
+// getFlowType tests
+// ============================================================================
+
+TEST_CASE("getFlowType SEQUENTIAL for normal instructions", "[disasm][flow]") {
+    CHECK(getFlowType(0xEA) == FlowType::SEQUENTIAL);   // NOP
+    CHECK(getFlowType(0xA9) == FlowType::SEQUENTIAL);   // LDA #
+    CHECK(getFlowType(0x85) == FlowType::SEQUENTIAL);   // STA zp
+    CHECK(getFlowType(0xE8) == FlowType::SEQUENTIAL);   // INX
+    CHECK(getFlowType(0x48) == FlowType::SEQUENTIAL);   // PHA
+}
+
+TEST_CASE("getFlowType CONDITIONAL for branches", "[disasm][flow]") {
+    CHECK(getFlowType(0xD0) == FlowType::CONDITIONAL);  // BNE
+    CHECK(getFlowType(0xF0) == FlowType::CONDITIONAL);  // BEQ
+    CHECK(getFlowType(0x90) == FlowType::CONDITIONAL);  // BCC
+    CHECK(getFlowType(0xB0) == FlowType::CONDITIONAL);  // BCS
+    CHECK(getFlowType(0x10) == FlowType::CONDITIONAL);  // BPL
+    CHECK(getFlowType(0x30) == FlowType::CONDITIONAL);  // BMI
+}
+
+TEST_CASE("getFlowType UNCONDITIONAL for JMP absolute and BRA", "[disasm][flow]") {
+    CHECK(getFlowType(0x4C) == FlowType::UNCONDITIONAL); // JMP abs
+    CHECK(getFlowType(0x80) == FlowType::UNCONDITIONAL); // BRA (65C02)
+}
+
+TEST_CASE("getFlowType CALL for JSR", "[disasm][flow]") {
+    CHECK(getFlowType(0x20) == FlowType::CALL);          // JSR
+}
+
+TEST_CASE("getFlowType RETURN for RTS and RTI", "[disasm][flow]") {
+    CHECK(getFlowType(0x60) == FlowType::RETURN);        // RTS
+    CHECK(getFlowType(0x40) == FlowType::RETURN);        // RTI
+}
+
+TEST_CASE("getFlowType HALT for BRK, STP, WAI", "[disasm][flow]") {
+    CHECK(getFlowType(0x00) == FlowType::HALT);          // BRK
+    CHECK(getFlowType(0xDB) == FlowType::HALT);          // STP
+    CHECK(getFlowType(0xCB) == FlowType::HALT);          // WAI
+}
+
+TEST_CASE("getFlowType INDIRECT for JMP indirect", "[disasm][flow]") {
+    CHECK(getFlowType(0x6C) == FlowType::INDIRECT);      // JMP (abs)
+    CHECK(getFlowType(0x7C) == FlowType::INDIRECT);      // JMP (abs,X) - 65C02
+}