DHIVA LABS · LEARN

Appearance

Run the test suite ​

chip8 proves its behaviour with test ROMs. One script runs the Timendus chip8-test-suite without a window, compares each final screen with a recorded copy, and checks that the SDL window program starts.

Run everything ​

  1. Build the project. See Install.

  2. Download the test ROMs, once:

    bash
    ./tests/roms/fetch_roms.sh

    The script pins the suite to the revision the recorded screens were made with.

  3. Run the suite:

    bash
    ./tests/run_tests.sh

    If your build folder is not build, pass it: ./tests/run_tests.sh my-build.

A passing run prints:

text
PASS  1-chip8-logo
PASS  2-ibm-logo
PASS  3-corax-plus
PASS  4-flags
PASS  5-quirks-vip
PASS  6-keypad-ex9e
PASS  6-keypad-exa1
PASS  6-keypad-fx0a
PASS  frontend (dummy SDL video+audio drivers, screenshot written)
9/9 passed

The script exits with status 0 when everything passes and non-zero otherwise, so you can use it in CI.

What each line checks ​

LineWhat it runs
1-chip8-logo, 2-ibm-logoThe logo ROMs draw the right picture
3-corax-plusThe corax+ opcode test
4-flagsArithmetic results and the VF flag
5-quirks-vipThe quirks test, with the CHIP-8 (VIP) option selected
6-keypad-ex9e, 6-keypad-exa1, 6-keypad-fx0aThe three keypad tests, with scripted key presses
frontendThe real chip8 window program, run for 180 frames with SDL's dummy video and audio drivers, writing a screenshot

The beep ROM (7-beep.ch8) is not part of the script: sound cannot be checked without a speaker. Run it yourself and listen for the SOS pattern.

When a test fails ​

A failing line starts with FAIL and says why:

  • framebuffer differs from tests/expected/<name>.txt is followed by a diff of the expected and actual screens.
  • runner exited non-zero means chip8_run_rom itself failed.
  • A WARNING: unknown opcode line means the ROM used an instruction chip8 does not implement.

If the script stops with test ROMs missing, run tests/roms/fetch_roms.sh first. If it reports that chip8_run_rom was not found, build the project.

Run one test ROM by hand ​

chip8_run_rom runs a ROM for a fixed number of frames and prints the screen. The Timendus ROMs with menus read their menu choice from memory address 0x1FF, which --poke sets. --key scripts a key press.

bash
./build/chip8_run_rom tests/roms/1-chip8-logo.ch8 --frames 120
./build/chip8_run_rom tests/roms/2-ibm-logo.ch8   --frames 120
./build/chip8_run_rom "tests/roms/3-corax+.ch8"   --frames 480
./build/chip8_run_rom tests/roms/4-flags.ch8      --frames 480
./build/chip8_run_rom tests/roms/5-quirks.ch8     --poke 0x1FF=1 --frames 600
./build/chip8_run_rom tests/roms/6-keypad.ch8     --poke 0x1FF=3 --key 5:120:180 --frames 360

In the last command, --key 5:120:180 presses CHIP-8 key 5 at frame 120 and releases it at frame 180.

All options are listed in the reference.

Update the recorded screens ​

If you change the interpreter on purpose and the screens change, rewrite the recorded copies:

bash
./tests/run_tests.sh --update

Review the changes to tests/expected/*.txt before you keep them. An update records whatever the interpreter produced, right or wrong.

Next steps ​