play96

play96 is a Rust library and CLI for running *96 libretro fantasy-console cores in automated test harnesses. It can step cartridges frame by frame, control input, inspect framebuffer pixels, make assertions, capture PNG files, exercise save states, and compare deterministic frame logs.

Build and test

git submodule update --init --recursive
cargo test
cargo build --release

The build produces the play96-cli executable and Rust, C, and C++ compatible libraries. C headers are in include/.

Rust library

Add the repository dependency to a test harness or library:

[dev-dependencies]
play96 = { git = "https://codeberg.org/compu96/play96.git" }

For a packaged release, use play96 = "0.2" after publishing it to the configured Cargo registry.

use play96::{Button, Color, Session};

fn main() -> Result<(), play96::Error> {
    let mut game = Session::new("wasm96_libretro.dll", "cartridge.wasm")?;
    game.set_button(Button::A, true);
    game.run_frames(10)?;

    assert_eq!(game.framebuffer_width(), 320);
    game.assert_pixel(12, 20, Color::rgb(255, 0, 0))?;
    game.assert_pixel_xrgb(13, 20, 0x00ff00)?;
    assert_eq!(game.frame_hash(), 0x0123_4567_89ab_cdef);

    // Audio is interleaved signed 16-bit stereo PCM from the latest frame.
    assert_eq!(game.audio_sample_rate(), 48_000.0);
    game.assert_audio_sample(100, 0, 1200, 10)?;
    game.assert_audio_hash(0xfedc_ba98_7654_3210)?;
    let left_sample = game.audio_frame(100)?[0];
    assert_eq!(left_sample, game.audio_samples()[200]);
    game.write_png("actual.png")?;
    Ok(())
}

pixel and pixel_xrgb return colors for custom assertions. audio_samples returns the latest frame's interleaved stereo waveform, while audio_frame, assert_audio_sample, and assert_audio_hash support exact deterministic sound tests. Failed built-in assertions report expected and actual values.

Only one Session may execute at a time because libretro callbacks are global to the dynamically loaded core.

C++ wrapper

Link against the generated play96 library and include include/play96.hpp:

#include <play96.hpp>

int main() {
    play96::Session game("wasm96_libretro.dll", "cartridge.wasm");
    game.run_frames(10);
    game.assert_pixel(12, 20, {255, 0, 0});
    game.assert_pixel_xrgb(13, 20, 0x00ff00);
}

The wrapper throws std::runtime_error when loading, execution, or an assertion fails. include/play96.h provides the underlying exception-free C ABI for other languages.

CLI

play96-cli --core ../wasm96/zig-out/bin/wasm96_libretro.dll \
  --cart ../wasm96/templates/cartridge-c/cartridge.wasm \
  --frames 30 --shot-every 15 --macro "0-10:p1.a" \
  --assert-pixel 12,20,ff0000 \
  --assert-audio-sample 100,0,1200,10 \
  --assert-audio-hash fedcba9876543210 \
  --netplay-log wasm96.netplay

Screenshots are written as PNG files. A recorded netplay log can be checked by running the same command with --netplay-check instead of --netplay-log.