Guide · Chapter 13 of 14

Test a program on the 6510

Write assertions about target behavior, then use the right emulator for each question.

Jump to a section

Start with a rule you can check without a screen

Take a function that turns input into an output, such as a coordinate conversion or a game rule. Run it through zp64c, assemble the emitted code, and assert the result on the emulated 6510. This checks code generation as well as source semantics. Put pure fixtures under tests/fixtures/emu/lang/pass/ and import test6502.

Layout assertions from the target fixture
const test6502 = @import("test6502");

// Inside main, using Header from the record layout chapter:
test6502.expectEqualU16(1, 5, @sizeOf(Header));
test6502.expectEqualU16(2, 1, @offsetOf(Header, "word"));
test6502.pass();

The first argument is an assertion id that helps identify a failing check. For values that depend on runtime code, pass the expression or result as the final argument. For instance, the indexed update fixture runs an effectful right-hand call and checks both the resulting array and the number of index evaluations. Effectful indexed update fixture · Header definition and byte layout

Test rejected source and runtime failures

Use a compile-fail fixture when a supported build must reject a construct or a bad machine plan. The expected diagnostic directive names the text the runner should find. Use a runtime-fail fixture for a program that compiles but reaches a checked failure on the target, such as software-stack overflow. These check different stages of the program.

Build rejection

From the zero-length REU fixture
// zeropage-emu-error: unsupported REU transfer length
const ZeroPage = @import("ZeroPage");

export fn main() void {
    ZeroPage.reu.copyC64ToReu(0x0400, 0x010000, 0);
}

Target failure

From the recursive overflow fixture
pub const zeropage_options = .{
    .stack = .{ .base = 0xc800, .size = 0x0008 },
    .abi = .{ .functions = .{
        .main = .{ .frame = .stack },
        .burn = .{ .frame = .stack },
    } },
};

fn burn(value: u8) u8 {
    return burn(value - 1);
}

export fn main() void {
    _ = burn(99);
}

For an unavailable resource that the program handles, use a passing fixture that asserts the failure result. The DLL disk-missing case expects an unavailable module and a null call instead of a crash. Handled missing-disk fixture

Assert the thing that can actually go wrong

QuestionWhat to observeExample
Did a function compute the right value?A typed return or output byteFunction results
Did inline assembly leave live registers intact?Prime the registers and compare them at block exitRegister preservation
Did banked code restore the machine mapping?Check the processor port around the callKERNAL bank restoration
Did the loader use the expected window and cache?Check window RAM, REU bytes, and registry stateNamed arena and DLL regions
Did a typed REU update survive a flush?Read the far record again after releasing the near viewFar view round trip

Use the Peddle host runner for these checks. It models the required KERNAL calls and a 16 MiB REU. Use VICE for behavior involving the full C64 environment, such as an interactive keyboard session, disk autostart, or integration with the actual KERNAL.

Run one group of cases and inspect a failure

Filter the host run by fixture path to check the behavior you're working on. If the compiler rejects a case unexpectedly, read its diagnostic and open the exact source that ran. If it assembles but behaves incorrectly, inspect the generated assembly, symbols, and map before attributing the failure to the source or runtime.

The full end-to-end gate compiles the demos and checks the assembler and disk artifacts. The optional VICE harness exercises the programs with hardware-facing assertions. For a change that affects both lowering and runtime behavior, use the focused fixture during development and the broader gates before publishing. Commands, prerequisites, and VICE harness setup