Learn Go with Tests: a TDD-first Go book you clone and run

The problem: Go tutorials that never make you run a test

Most introductory Go material hands you a snippet, tells you what it prints, and moves on. You finish able to read Go and unable to verify anything you write. This project takes the opposite position. Its stated aim is to let you explore the language by writing tests, and it argues that Go is a good language for learning TDD because the language is small and testing is built in. The audience is a developer who already programs in some other language and wants Go's syntax, its standard library and its testing conventions at the same time. The repository is a book plus a directory of Go modules, one per chapter, so the prose and the code you compile are the same artifact. That coupling is the whole point: a chapter on concurrency ships a concurrency/ directory, a chapter on generics ships generics/, and the chapter on templating ships blogrenderer/.

How the book is structured: fundamentals, then one application

The table of contents splits into four parts. Go fundamentals runs from install-go.md through hello-world.md, integers, iteration, arrays and slices, structs and interfaces, pointers and errors, maps, dependency injection, mocking, concurrency, select, reflection, sync, context, Roman numerals as an introduction to property-based tests, math, reading files, html/template, generics, and a chapter that revisits arrays and slices with generics. The second part builds a single application across chapters: an HTTP server, then JSON and routing, then IO and sorting, then command line and project structure, then time, then a chapter that revisits time using Go 1.25's testing/synctest, then WebSockets. Because each chapter iterates on the previous one, the application grows the way a real codebase does, and new standard library packages arrive when the feature needs them. The third part covers acceptance tests, scaling them, working without mocks by using fakes and contracts, and a refactoring checklist. The fourth part answers reader questions, with chapters on OS exec and on defining your own error types. The ordering matters: if you skip fundamentals and jump to the HTTP server, you meet dependency injection and mocking without the chapter that introduced them.

Installing Go and running your first failing test

The book's own entry point is install-go.md, which sets up the environment before any Go is written. The repository declares its module and toolchain in go.mod, and the file gives go 1.25 as the language version, so a toolchain older than that will not build every chapter. Clone the repository, then work inside a chapter directory rather than at the root, because each chapter is its own package with its own tests. The hello-world chapter is the first exercise, and the TDD loop it teaches is write a test, watch it fail, make it pass.

What a chapter's test run actually looks like

The module file at the repository root lists the third-party dependencies the book's own chapters use: go-approval-tests for the approval testing material, gomarkdown/markdown, and gorilla/websocket for the WebSockets chapter. Everything else in the fundamentals chapters comes from the standard library, which is why the exercises stay readable. Running the test command in a chapter directory is the loop the book repeats: the first run fails because the function under test does not exist or returns the wrong value, and you edit until it passes. The repository also carries build.sh and build.books.sh at the top level, which produce the book artifacts, so the EPUB and PDF in the releases are generated from the same Markdown the Gitbook renders.

Where the book stops being the right tool

This is a teaching text, not a reference. If you need to look up a standard library signature, the Go documentation is the place, and the book will not save you that trip. It also stays close to the standard library on purpose, so a reader hoping for a tour of Go web frameworks, ORMs or CLI libraries will not find one here. The chapters are ordered and cumulative, and the repository gives no index that maps a language feature to a single chapter, so using it as a lookup table means scrolling the table of contents. There is a further constraint in the code itself: the newest chapter depends on Go 1.25's testing/synctest, and go.mod states go 1.25, so anyone pinned to an older toolchain should expect that chapter and any others using recent language features not to build. The README does not document a rollback path for readers on older Go versions.

Alternatives and how they differ

Go by Example takes the opposite approach: short, self-contained annotated snippets, one per topic, with no test-first loop and no cumulative application. It is faster to skim and better as a lookup, and it teaches you nothing about structuring a test suite. A general TDD book in another language gives you the discipline but not Go's tooling, and you would have to translate every example. A video course gives you a walkthrough you cannot diff against your own code. The distinguishing property here is that the code is in the repository next to the prose, so you can read a chapter, run its tests, and compare your solution with a working one. If that feedback loop is not what you want, this book is more ceremony than you need.

Licence, maintenance and the cost of keeping up

The repository is MIT licensed, which permits reuse and adaptation with the licence and copyright notice retained; that is a statement about the licence text, not legal advice, and anyone redistributing the book or a translation should read LICENSE.md themselves. The project is not archived, and the last push was on 2026-08-26, so the repository is being touched. The release history shows 17.0.0 on 2026-08-17 with a new chapter on sync testing, 16.3.0 on 2026-08-14 described as a batch of fixes and improvements, and 16.2.0 on 2025-07-16. The upgrade cost for a reader is low because there is nothing to install beyond a Go toolchain, but the cost is not zero when the book tracks the language: a chapter written against testing/synctest requires the Go release that introduced it. Translations are hosted separately on Gitbook, and the README lists them for Chinese, Portuguese, Japanese, French, Korean, Turkish, Persian, Dutch, Vietnamese and Russian; those are community-maintained pages, and the README does not state how far behind the English text each one is.

Editorial conclusion

Adopt it if you already write code in another language and want Go's standard library and testing package explained through exercises you run yourself; the repository states go 1.25 in go.mod and the newest chapter depends on Go 1.25's testing/synctest, so an older toolchain will not build every chapter. Do not adopt it if you want a language reference or a survey of third-party Go libraries, because the book deliberately stays close to the standard library. Before committing, check the two facts that decide your path: whether you want the Gitbook, EPUB or PDF format, and whether the chapter directories you plan to work through build on your installed Go version.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. quii/learn-go-with-tests on GitHub
4. README
5. Releases