""" Tests for QuetzalWriter._generate_stks_chunk() serialization. The Stks chunk serializes the Z-machine call stack. Each frame has: - Bytes 0-2: return_pc (24-bit big-endian) - Byte 3: flags (bits 0-3 = num local vars) - Byte 4: varnum (which variable gets return value) - Byte 5: argflag (bitmask of supplied arguments) - Bytes 6-7: eval_stack_size (16-bit big-endian) - Next (num_local_vars * 2) bytes: local variables - Next (eval_stack_size * 2) bytes: evaluation stack values All multi-byte values are big-endian. Bottom frame has return_pc=0. """ from unittest import TestCase from mudlib.zmachine.quetzal import QuetzalWriter from mudlib.zmachine.zstackmanager import ZRoutine, ZStackManager class MockMemory: """Mock memory for testing.""" def __init__(self): self.version = 5 class MockZMachine: """Mock z-machine with stack manager.""" def __init__(self): self._mem = MockMemory() self._stackmanager = ZStackManager(self._mem) class QuetzalStksTests(TestCase): """Test suite for Stks chunk generation.""" def setUp(self): self.zmachine = MockZMachine() self.writer = QuetzalWriter(self.zmachine) def test_empty_call_stack_generates_empty_chunk(self): """With only the sentinel bottom, should generate empty bytes.""" # Call stack has only ZStackBottom sentinel chunk = self.writer._generate_stks_chunk() self.assertEqual(chunk, b"") def test_single_frame_serialization(self): """Single routine frame should serialize correctly.""" # Create a routine with known values routine = ZRoutine( start_addr=0x5000, return_addr=0x4200, zmem=self._mem, args=[], local_vars=[0x1234, 0x5678, 0xABCD], stack=[0x1111, 0x2222], ) self.zmachine._stackmanager.push_routine(routine) chunk = self.writer._generate_stks_chunk() # Expected bytes for this frame: # return_pc (0x4200): 0x00, 0x42, 0x00 # flags (3 local vars): 0x03 # varnum (0): 0x00 # argflag (0): 0x00 # eval_stack_size (2): 0x00, 0x02 # local_vars: 0x12, 0x34, 0x56, 0x78, 0xAB, 0xCD # stack: 0x11, 0x11, 0x22, 0x22 expected = bytes( [ 0x00, 0x42, 0x00, # return_pc 0x03, # flags (3 local vars) 0x00, # varnum 0x00, # argflag 0x00, 0x02, # eval_stack_size = 2 0x12, 0x34, # local_vars[0] 0x56, 0x78, # local_vars[1] 0xAB, 0xCD, # local_vars[2] 0x11, 0x11, # stack[0] 0x22, 0x22, # stack[1] ] ) self.assertEqual(chunk, expected) def test_multiple_frames_serialization(self): """Multiple nested frames should serialize in order.""" # Frame 1: outer routine routine1 = ZRoutine( start_addr=0x1000, return_addr=0, # bottom frame zmem=self._mem, args=[], local_vars=[0x0001], stack=[], ) self.zmachine._stackmanager.push_routine(routine1) # Frame 2: inner routine routine2 = ZRoutine( start_addr=0x2000, return_addr=0x1050, zmem=self._mem, args=[], local_vars=[0x0002, 0x0003], stack=[0xAAAA], ) self.zmachine._stackmanager.push_routine(routine2) chunk = self.writer._generate_stks_chunk() # Expected: frame1 bytes + frame2 bytes # Frame 1: return_pc=0, 1 local var, 0 stack frame1 = bytes( [ 0x00, 0x00, 0x00, # return_pc = 0 0x01, # flags (1 local var) 0x00, # varnum 0x00, # argflag 0x00, 0x00, # eval_stack_size = 0 0x00, 0x01, # local_vars[0] ] ) # Frame 2: return_pc=0x1050, 2 local vars, 1 stack frame2 = bytes( [ 0x00, 0x10, 0x50, # return_pc 0x02, # flags (2 local vars) 0x00, # varnum 0x00, # argflag 0x00, 0x01, # eval_stack_size = 1 0x00, 0x02, # local_vars[0] 0x00, 0x03, # local_vars[1] 0xAA, 0xAA, # stack[0] ] ) expected = frame1 + frame2 self.assertEqual(chunk, expected) def test_frame_with_no_locals_or_stack(self): """Frame with no local vars or stack values should serialize correctly.""" routine = ZRoutine( start_addr=0x3000, return_addr=0x2500, zmem=self._mem, args=[], local_vars=[], stack=[], ) self.zmachine._stackmanager.push_routine(routine) chunk = self.writer._generate_stks_chunk() expected = bytes( [ 0x00, 0x25, 0x00, # return_pc 0x00, # flags (0 local vars) 0x00, # varnum 0x00, # argflag 0x00, 0x00, # eval_stack_size = 0 ] ) self.assertEqual(chunk, expected) def test_round_trip_with_parser(self): """Generated stks bytes should parse back identically.""" from mudlib.zmachine.quetzal import QuetzalParser # Create a complex stack state routine1 = ZRoutine( start_addr=0x1000, return_addr=0, zmem=self._mem, args=[], local_vars=[0x1111, 0x2222, 0x3333], stack=[0xAAAA, 0xBBBB], ) self.zmachine._stackmanager.push_routine(routine1) routine2 = ZRoutine( start_addr=0x2000, return_addr=0x1234, zmem=self._mem, args=[], local_vars=[0x4444], stack=[0xCCCC, 0xDDDD, 0xEEEE], ) self.zmachine._stackmanager.push_routine(routine2) # Generate the stks chunk stks_bytes = self.writer._generate_stks_chunk() # Parse it back parser = QuetzalParser(self.zmachine) parser._parse_stks(stks_bytes) # Verify the stack was reconstructed correctly # Parser creates a new stack manager, skip bottom sentinel frames = self.zmachine._stackmanager._call_stack[1:] self.assertEqual(len(frames), 2) # Check frame 1 assert isinstance(frames[0], ZRoutine) self.assertEqual(frames[0].return_addr, 0) self.assertEqual(frames[0].local_vars[:3], [0x1111, 0x2222, 0x3333]) self.assertEqual(frames[0].stack, [0xAAAA, 0xBBBB]) # Check frame 2 assert isinstance(frames[1], ZRoutine) self.assertEqual(frames[1].return_addr, 0x1234) self.assertEqual(frames[1].local_vars[:1], [0x4444]) self.assertEqual(frames[1].stack, [0xCCCC, 0xDDDD, 0xEEEE]) def test_parse_return_pc_third_byte(self): """Parser should correctly read all 3 bytes of return_pc (regression test).""" from mudlib.zmachine.quetzal import QuetzalParser # Construct a minimal stack frame with return_pc=0x123456 # where the third byte (0x56) is non-zero and would be wrong if skipped. # # Stack frame format: # - Bytes 0-2: return_pc (0x12, 0x34, 0x56) # - Byte 3: flags (0 local vars) # - Byte 4: varnum (0) # - Byte 5: argflag (0) # - Bytes 6-7: eval_stack_size (0) stks_bytes = bytes( [ 0x12, 0x34, 0x56, # return_pc = 0x123456 0x00, # flags (0 local vars) 0x00, # varnum 0x00, # argflag 0x00, 0x00, # eval_stack_size = 0 ] ) parser = QuetzalParser(self.zmachine) parser._parse_stks(stks_bytes) # The parser should have reconstructed the stack with correct return_pc frames = self.zmachine._stackmanager._call_stack[1:] # skip sentinel self.assertEqual(len(frames), 1) # If bug exists, it would read bytes[0], bytes[1], bytes[3] = 0x12, 0x34, 0x00 # giving return_pc = 0x123400 instead of 0x123456 assert isinstance(frames[0], ZRoutine) self.assertEqual( frames[0].return_addr, 0x123456, "Parser should read bytes[ptr+2], not bytes[ptr+3]", ) @property def _mem(self): """Helper to get mock memory.""" return self.zmachine._mem