AprNes Testing Methodology

AprNes uses hardware verification test ROMs originally written to validate real NES console behavior. These are actual NES programs (6502 machine code) that exercise specific hardware features and report pass/fail. The same ROMs are used by every major NES emulator project to measure accuracy.

Test coverage spans all major NES subsystems:

• CPU — All official 6502 instructions, addressing modes, timing, dummy reads/writes, interrupt behavior (NMI/IRQ/BRK interactions), branch timing, reset behavior
• PPU — VBlank/NMI timing, sprite 0 hit, sprite overflow, open bus behavior, palette RAM, VRAM access, read buffer, even/odd frame toggle
• APU — Frame counter timing (mode 0/1), length counter, IRQ flag timing, clock jitter, DMC rates, channel mixing, reset behavior
• Mapper — MMC3 (Mapper 004) IRQ counter clocking, A12 detection, scanline timing, Rev A/B behavior
• I/O — Controller reading accuracy, DPCM interference, DMA timing

All ROMs come from the nes-test-roms collection, primarily authored by:

• blargg (Shay Green) — The most comprehensive NES test ROM author. His suites cover CPU instructions (v3/v5), APU timing, PPU VBL/NMI, sprite hit/overflow, and more. Two result protocols: legacy (screen-based) and modern ($6000 memory-mapped).
• bisqwit — CPU timing tests
• other community authors — MMC3 IRQ tests, DMA interaction tests, controller tests

These are the same ROMs used by Mesen, Nestopia, FCEUX, and other reference emulators. Passing them indicates cycle-accurate or near-cycle-accurate emulation.

Headless Mode

The emulator has a built-in TestRunner.cs that runs in headless mode — no window, no audio, no frame rate limiter. The CPU/PPU/APU all tick at maximum speed. A single test ROM typically completes in under 1 second.

Orchestration Script

A bash script (run_tests_report.sh) handles the full pipeline:

1. Build the project with MSBuild
2. Run each of 174 ROM files through the headless emulator
3. Capture the final frame as PNG, convert to lossless WebP
4. Collect results into a JSON array
5. Generate a single-file HTML report with embedded data

Mechanism A: $6000 Memory Protocol

Modern blargg test ROMs use a memory-mapped status protocol. The test runner polls address $6000 every frame:

Result text is read from $6004+ as null-terminated ASCII. This gives detailed error messages like "Flag first set too late" or "Length counter not clocked correctly".

Mechanism B: Screen Stability Detection

Older blargg tests (2005 era) don't use the $6000 protocol. They render results directly to the PPU nametable. The test runner handles these with a multi-step heuristic:

1. After 120 frames (~2 sec), start sampling the screen buffer every frame
2. Compute a hash of the framebuffer (sampling every 37th pixel for speed)
3. When the hash stays identical for 90 consecutive frames (~1.5 sec), the screen is "stable"
4. Scan the PPU nametable (character map) for known result strings:
   • "Passed" / "PASSED" → PASS
   • "Failed" / "FAILED" → FAIL
   • "$01" (hex on screen) → PASS
   • "$02" ~ "$FF" (hex on screen) → FAIL
   • "All tests complete" → PASS
   • " 0/" (zero error count) → PASS

This approach reads the PPU nametable directly (not OCR on pixels), making it fast and reliable.

Auto Soft Reset

Some test ROMs write $81 to $6000 to request a console reset (testing power-on/reset behavior). The runner detects this and automatically performs a soft reset after a 100ms delay, mimicking a human pressing the reset button. Supports up to 10 sequential resets per ROM.

Simulated Controller Input

Controller read tests need actual button presses. The --input parameter schedules timed button events:

--input "A:2.0,B:4.0,Select:6.0,Start:8.0,Up:10.0,Down:12.0,Left:14.0,Right:16.0"

Each button is pressed at the specified time (seconds) and held for 10 frames (~166ms). This lets tests like read_joy3/test_buttons verify that all 8 buttons are correctly detected in sequence.

Screenshot Capture

The final frame of each test is captured as a 256x240 PNG, then converted to lossless WebP (typically 60-80% smaller). Screenshots serve as visual evidence — many test ROMs display their results on screen as text, showing exactly what passed or failed.

Timeout Safety

Each ROM has a configurable --max-wait timeout (default 30 seconds, 120 for longer tests). If a test ROM enters an infinite loop or hangs, the runner terminates it gracefully and reports the last known state.

The headless test runner is invoked directly via the emulator executable:

AprNes.exe --rom <file.nes> [options]

Exit codes: 0 = pass, 1-127 = fail (test error code), 255 = timeout/no result.