Open-source project
quii/learn-go-with-tests avatar
quii/learn-go-with-tests

Learn Go with Tests pairs every chapter with a directory of runnable Go

Learn Go with test-driven development

23,963 stars2,937 forksGoMIT

At a glance

What is it?
quii/learn-go-with-tests is a free MIT-licensed book that teaches Go through test-driven development, with each Markdown chapter paired to a same-named directory of code. Its go.mod pins two of three dependencies to untagged commits and declares go 1.25, which sets the toolchain floor for every exercise.
Who is it for?
Work through Learn Go with Tests if you already write code in another language and want Go's testing idioms rather than a Go tutorial that starts at variable declarations. Do not expect a full Go curriculum from it: the fundamentals stop at generics, the application section never adds authentication, migrations or deployment, and the testing coverage leaves race detection, fuzzing and profiling untouched.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 20 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • quii/learn-go-with-tests23,963 ★ · +72
Star history
Repository2026-09-222026-11-15
quii/learn-go-with-tests23.9k24k

72 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Every chapter is a Markdown file with a same-named directory of Go code

The repository is laid out in pairs. install-go.md sits next to hello-world.md, which sits next to hello-world/, and the pattern repeats through concurrency.md with concurrency/, context.md with context/, dependency-injection.md with di/, and command-line.md with command-line/. The Markdown carries the prose and the exercise, the directory carries the code that goes with it, so a reader working offline has both halves without a second download.

code
install-go.md
hello-world.md
hello-world/
dependency-injection.md
di/
concurrency.md
concurrency/

The book build tooling lives in the same flat top level: book.json, build.sh, build.books.sh, a .gitbook directory, fix-internal-links.lua and a .mdlrc for markdown linting. The flatness is also the limit. There is no per-chapter dependency manifest, so anyone who wants to run a single exercise inherits the single root go.mod described next.

go.mod pins approval tests to a 2021 commit and markdown to a 2024 pseudo-version

The module declares three requirements and not one of them carries a release tag. go-approval-tests is pinned to the pseudo-version v0.0.0-20211008131110-0c40b30e0000, which resolves to an October 2021 commit. gomarkdown/markdown is pinned the same way to a June 2024 commit. Only gorilla/websocket has a real version behind it, v1.5.3.

go
module github.com/quii/learn-go-with-tests

go 1.25

require (
	github.com/approvals/go-approval-tests v0.0.0-20211008131110-0c40b30e0000
	github.com/gomarkdown/markdown v0.0.0-20240626202925-2eda941fd024
	github.com/gorilla/websocket v1.5.3
)

That shape matters for the chapters built on approval testing, where rendered output is compared against a checked-in golden file. The comparison runs against a library snapshot from October 2021.

The go directive is 1.25 and the timer chapter is what sets it

The module declares go 1.25, and release 17.0.0, titled "New chapter on sync test", added the chapter that uses it. Revisiting time, with testing/synctest uses Go 1.25's testing/synctest package to exercise the real timer-based code from the Time chapter instead of a stand-in, and the chapter description puts the payoff as tests that are neither slow nor flaky.

The go directive applies to the whole module rather than to one directory, so the toolchain floor created by that single chapter is also the floor for every other exercise in the repository. The table of contents does not state a minimum Go version, so go.mod is the place to check.

The application chapters build one toy product that a fictional product owner dictates

Seven chapters under Build an application all operate on the same codebase: an HTTP server that listens and responds, endpoints returning JSON with routing and embedding, IO and sorting that persists data to disk, a command line supporting multiple applications from one code base, the time package for scheduling activities, the synctest revisit, and WebSockets. Each chapter is framed as iterating on the last one as the product owner expands functionality, and the stated goal is a grasp of what the standard library can do.

The scope stops at that line. Nothing in the application section adds authentication, authorization, schema migrations, deployment, configuration files or observability, so a reader who finishes it has written a worked example rather than a system. What is covered outside that arc is thinner still: Testing fundamentals is four chapters on acceptance tests, scaling them, working without mocks, and a refactoring checklist.

Ten translations sit in separate Gitbook forks that nothing ties to the English chapters

The README links ten translations, each hosted on somebody else's Gitbook: Chinese, Portuguese, Japanese, French, Korean, Turkish, Persian, Dutch, Vietnamese and Russian. None of them live in this repository. They are separate sites maintained by separate people, and the English main branch is the only copy under version control.

The consequence is that nothing in the repository records which English chapter a given translation corresponds to, or when it was last synced. A reader working in one of those languages can fall several chapters behind with no signal from the project, and a chapter added on main, such as the synctest one shipped in 17.0.0, simply will not exist in a fork until somebody translates it.

Chapters arrive when the author has time, and the release numbers show the gaps

The Questions and answers section states its own policy: readers raise a question as a GitHub issue, and the author will try and find time to write a short chapter to tackle it. Entries listed there include the following. OS exec covers reaching out to the OS to execute commands while keeping business logic testable, error types covers building your own error types to improve tests, and the context-aware Reader chapter TDDs cancellation onto io.Reader.

The release history carries the same message. Version 16.2.0 shipped on 2025-07-16, then nothing for thirteen months until 16.3.0 on 2026-08-14, described only as a big batch of fixes and improvements, with 17.0.0 following three days later carrying one new chapter. The last push to the repository is dated 2026-10-26. For a reader, that means there is no fixed syllabus: whether a topic you need exists is a function of what somebody asked and when.

The README has no clone or build command, only Gitbook and release downloads

What the README offers for getting the material is a Formats list of two: a Gitbook edition at quii.gitbook.io/learn-go-with-tests, and EPUB or PDF files from the repository's releases page.

For a reader who wants the code rather than the prose, the repository layout is a guide: the book build scripts, build.sh and build.books.sh, sit next to book.json. Worth noticing on the other side: nothing is gated. There is no account, no key and no paid tier, and the support links are a tweet, a Mastodon handle, a coffee page and GitHub Sponsors, all optional.

Testing fundamentals is four chapters, so the tooling gaps are the reader's to close

Everything under Testing fundamentals fits in four links: an introduction to acceptance tests with a worked example of gracefully shutting down an HTTP server, techniques for scaling acceptance tests in non-trivial systems, working without mocks, stubs and spies by using fakes and contracts, and a refactoring checklist. Benchmarking appears once, inside the Iteration chapter. Coverage appears once, inside Arrays and slices.

None of the table of contents sections listed above includes a chapter on the race detector, fuzzing, coverage reporting, profiling, build tags or test timeouts. A reader arriving from another language expecting a full testing toolchain will find the philosophy covered at length and the tooling largely absent, and the only route the project offers for closing that gap is the issue tracker.

Editorial conclusion

Work through Learn Go with Tests if you already write code in another language and want Go's testing idioms rather than a Go tutorial that starts at variable declarations. Do not expect a full Go curriculum from it: the fundamentals stop at generics, the application section never adds authentication, migrations or deployment, and the testing coverage leaves race detection, fuzzing and profiling untouched. Check your toolchain before starting, because go.mod declares go 1.25 and there is no fallback for the synctest chapter. Then confirm that the community Gitbook translation in your language has actually caught up, since nothing in the repository records which English chapter it corresponds to.

Frequently asked questions

Is Learn Go with Tests free to read?

Yes. The book is published under the MIT license and the README asks for no account and no payment. Support is entirely optional, offered through a tweet, a Mastodon handle, a buymeacoffee page and GitHub Sponsors. Ten community translations are also linked, each hosted on its own Gitbook.

What does Learn Go with Tests actually teach?

Go through test-driven development rather than through syntax alone. Go fundamentals runs through 21 chapters covering variables, integers, iteration, slices, structs and interfaces, pointers and errors, maps, dependency injection, mocking, concurrency, select, reflection, sync, context and generics. A second section builds one application across seven chapters, and a third covers testing fundamentals.

What Go version does Learn Go with Tests require?

go.mod declares go 1.25, and release 17.0.0 added a chapter using Go 1.25's testing/synctest package. The README table of contents states no minimum version, so check go.mod.

Does Learn Go with Tests come as a PDF or EPUB?

The Formats section links a Gitbook edition and EPUB or PDF downloads from the repository's releases page. The three most recent releases are 17.0.0 on 2026-08-17, 16.3.0 on 2026-08-14 and 16.2.0 on 2025-07-16.

Is Learn Go with Tests still being updated?

The repository is not archived and its last push is dated 2026-10-26. Releases are irregular: 16.2.0 shipped on 2025-07-16 and the next one, 16.3.0, did not arrive until 2026-08-14. New chapters are driven by reader questions raised as GitHub issues.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/quii-learn-go-with-tests.svg)](https://hysenlabs.com/projects/quii-learn-go-with-tests)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/quii-learn-go-with-tests.svg)](https://hysenlabs.com/projects/quii-learn-go-with-tests)

Was this useful?