Unit testing

FantASM ships with an integrated Z80/Z80N simulator, so you can write and run unit tests directly in your assembly source — no external harness required. The simulator is paging-aware: banked code runs with a live MMU, so NEXTREG (and the 128K $7FFD port) remap memory during a test just as on real hardware.

Test blocks

Wrap a test in a !test "<name>" … !endtest block. Inside, set up machine state, run your code, and assert the result:

!test "ADD A, B adds correctly"
    init_reg A, 5
    init_reg B, 10
    add a, b
    assert_reg A, 15
!endtest

Test directives

Directive	Description
`init_reg <REG>, <val>`	Initialise an 8- or 16-bit register.
`init_mem <addr>, <val>`	Initialise a memory location.
`assert_reg <REG>, <val>`	Assert a register’s value after execution.
`assert_mem <addr>, <val>`	Assert a memory location’s value after execution.
`assert_cycles <limit>`	Assert that execution stayed within a T-state budget.

assert_cycles is handy for guarding performance-critical routines:

!test "clear screen is fast enough"
    call clear_screen
    assert_cycles 8000
!endtest

Running tests

Pass --test to a build to execute every !test block instead of producing output:

fantasm build main.asm --test