Sudoku Test Driven Development: A Solver Kata

Why Sudoku is a perfect TDD kata

Test driven development thrives when correctness is unambiguous, and Sudoku fits that description exactly. Every rule is precise, every board is either valid or not, and a solved grid can be checked in a single pass. That clarity makes Sudoku test driven development ideal for practicing the discipline: you can always state, in advance, what a passing test should assert. There is no fuzzy specification to argue about, so you can focus entirely on the rhythm of writing a test, watching it fail, and making it pass.

Start with the validator

Do not begin with the solver; begin with the checker. The first behaviors you need are simple to test and form the foundation everything else rests on. Write the test first, watch it fail, then write just enough code to pass.

• A fully and correctly filled board is reported valid.
• A board with the same digit twice in a row is reported invalid.
• A board with a duplicate in a column is reported invalid.
• A board with a duplicate in a 3 by 3 box is reported invalid.
• A partially filled board with no conflicts so far is reported consistent.

Red, green, refactor in practice

The cycle is the whole point. Write one failing test, the red step. Make it pass with the simplest code that works, the green step. Then clean up duplication and clarify names while the tests stay green, the refactor step. Resist the urge to write the clever solver early. Each small test nudges the design forward, and by the time your validator is solid you will already have the row, column, and box helpers your solver needs.

Grow toward a solver

With the validator in place, add tests that push toward solving. Start with a puzzle that needs only a single naked single and assert that your code fills it. Next, assert that a straightforward puzzle returns a completed, valid grid. Then assert that an unsolvable board returns no solution rather than looping forever. Each test forces a little more machinery: candidate tracking, then recursion, then a clean failure path. The backtracking solver emerges from the tests instead of being written all at once.

Test the hard cases

• A known difficult puzzle is solved and the result passes the validator.
• A completely empty grid produces some valid completed grid.
• A puzzle with more than one solution is handled the way your specification says.
• The solver leaves the input untouched and returns a new grid, so tests stay isolated.

Keep tests fast and focused

Unit tests should be quick and deterministic, so keep the fixtures small and avoid timing anything inside them. Measuring speed is a separate concern that belongs in a benchmark, not in a correctness test. If you want to guard against performance regressions, assert on a countable quantity like the number of backtracks rather than on wall-clock seconds, which vary from machine to machine.

What TDD teaches beyond Sudoku

By the end, Sudoku test driven development has given you more than a solver. You have practiced letting a clean design emerge from constraints, keeping a safety net of tests green during refactors, and writing code that is easy to change because it is easy to verify. Those habits transfer to any project. The engine behind shapedoku.com was grown the same way, test first, which is part of why its shape puzzles behave so predictably when you play at app.shapedoku.com.