Step-by-step tutorial · Test Driven Development

NES Emulator by TDD

Build a Nintendo Entertainment System emulator from scratch in Python by following 356 test-driven lessons.

Author: linkfy · 14 chapters · 356 lessons

Start the course View repository Reference implementation

What this tutorial is

This is a tests-only starter project. It intentionally does not contain the completed emulator: the tests/ directory is the curriculum. Each numbered test explains why the next behavior matters, which production file to create or update, and the smallest implementation expected at that point.

This tutorial takes the deliberate route, not the fast route.

The first chapters build and verify the CPU, memory, cartridge, and PPU foundations. Game graphics and the interactive frontend arrive later, after the components that support them have earned their place through tests. Do not expect a game on screen in the first few lessons; expect to understand why it works when it finally appears.

Getting started

1. Clone the repository

git clone https://github.com/linkfy/nes-emulator-tutorial-tdd
cd nes-emulator-tutorial-tdd

2. Install uv and create the locked environment

Do not run uv init inside the repository: the project is already initialized. From the project root, install the dependencies pinned in uv.lock.

uv --version
uv sync

docs.astral.sh/uv

3. Open lesson 001 and run only that test

Read its module-level documentation from beginning to end before writing production code. Then run only that lesson:

uv run pytest tests/chapter_01_cpu/test_001_initial_files.py -v

4. Repeat Red → Green → Refactor

Move one numbered test at a time. Every completed lesson must remain green before you move forward. Run completed tests only; do not run future chapters yet.

After lesson 356, run the complete suite:

uv run pytest

The TDD loop

Red

Run the lesson test and watch it fail.

Green

Write the smallest implementation that makes it pass.

Refactor

Clean up while keeping every earlier test green.

Markers in code

Lesson examples may use NEW LINE / NEW BLOCK for code to add, UPDATED LINE / UPDATED BLOCK for code to change, DELETED LINE / DELETED BLOCK for obsolete code and ... where existing code stays unchanged.

Curriculum map

Fourteen chapters and 356 ordered lessons. Use the ranges to see where you are and what comes next.

01CPUCPU, RAM, bus, addressing modes, instructions, flags, and validationTests 001–211 · 211 lessons

02ROM loadingiNES parsing, cartridges, Mapper 000, and ROM executionTests 212–223 · 12 lessons

03PPU memory & graphicsPPU registers, PPU bus, VRAM, CHR data, and graphics decodingTests 224–258 · 35 lessons

04PPU timing & VBlankPPU timing, VBlank, NMI, and CPU/PPU coordinationTests 259–269 · 11 lessons

05Rendering pipelinePure rendering pipeline, framebuffer data, and pygame helpersTests 270–287 · 18 lessons

06ROM startupROM startup preparation, APU no-ops, and OAM DMATests 288–289 · 2 lessons

07Controller inputNES controller protocol and $4016 integrationTests 290–293 · 4 lessons

08Manual mainManual ROM loop, pygame frontend, keyboard input, and errorsTests 294–298 · 5 lessons

09Sprite renderingSprite decoding, rendering, priority, and compositionTests 299–314 · 16 lessons

10PerformanceFPS reporting, fast framebuffer upload, PyPy, and initial pacingTests 315–318 · 4 lessons

11Sprite Zero HitSprite-zero-hit detection and timing integrationTests 319–323 · 5 lessons

12MirroringCartridge nametable mirroringTests 324–327 · 4 lessons

13ScrollingHorizontal viewport composition and timed scrollingTests 328–353 · 26 lessons

14OptimizationsImmutable rendering caches and absolute-deadline frame pacingTests 354–356 · 3 lessons

Manual ROMs

Some later lessons include manual checks with legally obtained real ROMs (for example Super Mario Bros. or Mario Bros.). They are only needed when a lesson reaches a manual checkpoint.