[
{
"path": ".editorconfig",
"content": "# Top-most EditorConfig file\nroot = true\n\n# Every file should according to these default configurations if not specified\n[*]\n# Use UNIX-style line endings\nend_of_line = LF\n# Use utf-8 file encoding\ncharset = utf-8\n# 4 space indent\nindent_style = space\nindent_size = 4\n# Ensure file ends with a newline when saving(prevent `no newline at EOF`)\ninsert_final_newline = true\n# Remove any whitespace characters preceding newline characters\ntrim_trailing_whitespace = true\n\n# For YAML\n[*.{yml,yaml}]\nindent_size = 2\n\n# For Go files\n[*.go]\n# `gofmt` uses tabs for indentation\nindent_style = tab\n"
},
{
"path": ".github/FUNDING.yml",
"content": "# These are supported funding model platforms\n\ngithub: [quii]\n"
},
{
"path": ".github/workflows/go.yml",
"content": "name: Go\n\non:\n push:\n branches: [ main ]\n pull_request:\n branches: [ main ]\n release:\n types: [ published ]\n\njobs:\n\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Go\n uses: actions/setup-go@v5\n with:\n go-version: 1.24\n\n - name: Build\n run: ./build.sh\n\n - name: Build books\n run: ./build.books.sh\n\n - name: Get release\n id: get_release\n if: github.event_name == 'release' && github.event.action == 'published'\n uses: bruceadams/get-release@v1.3.2\n env:\n GITHUB_TOKEN: ${{ github.token }}\n\n - name: Attach generated epub upon release publish\n if: github.event_name == 'release' && github.event.action == 'published'\n with:\n upload_url: ${{ steps.get_release.outputs.upload_url }}\n asset_path: ./learn-go-with-tests.epub\n asset_name: learn-go-with-tests.epub\n asset_content_type: application/epub+zip\n uses: actions/upload-release-asset@v1.0.2\n env:\n GITHUB_TOKEN: ${{ github.token }}\n\n - name: Attach generated PDF upon release publish\n if: github.event_name == 'release' && github.event.action == 'published'\n with:\n upload_url: ${{ steps.get_release.outputs.upload_url }}\n asset_path: ./learn-go-with-tests.pdf\n asset_name: learn-go-with-tests.pdf\n asset_content_type: application/pdf\n uses: actions/upload-release-asset@v1.0.2\n env:\n GITHUB_TOKEN: ${{ github.token }}\n\n"
},
{
"path": ".gitignore",
"content": ".idea/\n*.iml\n\n# Book build output\n_book/\n\n# eBook build output\n*.epub\n*.mobi\n*.pdf\n\n# templated files\nmeta.tex\n\ngame.db.json\n.DS_Store\n"
},
{
"path": ".mdlrc",
"content": "git_recurse true\n\nrules \"MD001\", \"MD002\", \"MD003\", \"MD004\", \"MD005\", \"MD006\", \"MD007\", \"MD008\", \"MD009\", \"MD010\", \"MD011\", \"MD012\", \"MD014\", \"MD015\", \"MD016\", \"MD017\", \"MD018\", \"MD019\", \"MD020\", \"MD021\", \"MD023\", \"MD025\", \"MD028\", \"MD030\", \"MD035\", \"MD037\", \"MD038\", \"MD040\", \"MD041\", \"MD042\"\n\n# exclude rules\nexclude \"MD013\" # Line length\nexclude \"MD022\" # Headers should be surrounded by blank lines\nexclude \"MD024\" # Multiple headers with the same content\nexclude \"MD026\" # Trailing punctuation in header\nexclude \"MD027\" # Multiple spaces after blockquote symbol\nexclude \"MD029\" # Ordered list item prefix\nexclude \"MD031\" # Fenced code blocks should be surrounded by blank lines\nexclude \"MD032\" # Lists should be surrounded by blank lines\nexclude \"MD033\" # Inline HTML\nexclude \"MD034\" # Bare URL used\nexclude \"MD036\" # Emphasis used instead of a header\nexclude \"MD039\" # Spaces inside link text\n"
},
{
"path": "LICENSE.md",
"content": "MIT License\n\nCopyright (c) [2025] [Christopher James]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "# Learn Go with Tests\n\n
\n \n
\n\n[Art by Denise](https://twitter.com/deniseyu21)\n\n[](https://goreportcard.com/report/github.com/quii/learn-go-with-tests)\n\n## Formats\n\n- [Gitbook](https://quii.gitbook.io/learn-go-with-tests)\n- [EPUB or PDF](https://github.com/quii/learn-go-with-tests/releases)\n\n## Translations\n\n- [中文](https://studygolang.gitbook.io/learn-go-with-tests)\n- [Português](https://larien.gitbook.io/aprenda-go-com-testes/)\n- [日本語](https://andmorefine.gitbook.io/learn-go-with-tests/)\n- [Français](https://goosegeesejeez.gitbook.io/apprendre-go-par-les-tests)\n- [한국어](https://miryang.gitbook.io/learn-go-with-tests/)\n- [Türkçe](https://halilkocaoz.gitbook.io/go-programlama-dilini-ogren/)\n- [فارسی](https://go-yaad-begir.gitbook.io/go-ba-test/)\n- [Nederlands](https://bobkosse.gitbook.io/leer-go-met-tests/)\n\n## Support me\n\nI am proud to offer this resource for free, but if you wish to give some appreciation:\n\n- [Tweet me @quii](https://twitter.com/quii)\n- Mastodon\n- [Buy me a coffee :coffee:](https://www.buymeacoffee.com/quii)\n- [Sponsor me on GitHub](https://github.com/sponsors/quii)\n\n## Why\n\n* Explore the Go language by writing tests\n* **Get a grounding with TDD**. Go is a good language for learning TDD because it is a simple language to learn and testing is built-in\n* Be confident that you'll be able to start writing robust, well-tested systems in Go\n* [Watch a video, or read about why unit testing and TDD is important](why.md)\n\n## Table of contents\n\n### Go fundamentals\n\n1. [Install Go](install-go.md) - Set up environment for productivity.\n2. [Hello, world](hello-world.md) - Declaring variables, constants, if/else statements, switch, write your first go program and write your first test. Sub-test syntax and closures.\n3. [Integers](integers.md) - Further Explore function declaration syntax and learn new ways to improve the documentation of your code.\n4. [Iteration](iteration.md) - Learn about `for` and benchmarking.\n5. [Arrays and slices](arrays-and-slices.md) - Learn about arrays, slices, `len`, varargs, `range` and test coverage.\n6. [Structs, methods & interfaces](structs-methods-and-interfaces.md) - Learn about `struct`, methods, `interface` and table driven tests.\n7. [Pointers & errors](pointers-and-errors.md) - Learn about pointers and errors.\n8. [Maps](maps.md) - Learn about storing values in the map data structure.\n9. [Dependency Injection](dependency-injection.md) - Learn about dependency injection, how it relates to using interfaces and a primer on io.\n10. [Mocking](mocking.md) - Take some existing untested code and use DI with mocking to test it.\n11. [Concurrency](concurrency.md) - Learn how to write concurrent code to make your software faster.\n12. [Select](select.md) - Learn how to synchronise asynchronous processes elegantly.\n13. [Reflection](reflection.md) - Learn about reflection\n14. [Sync](sync.md) - Learn some functionality from the sync package including `WaitGroup` and `Mutex`\n15. [Context](context.md) - Use the context package to manage and cancel long-running processes\n16. [Intro to property based tests](roman-numerals.md) - Practice some TDD with the Roman Numerals kata and get a brief intro to property based tests\n17. [Maths](math.md) - Use the `math` package to draw an SVG clock\n18. [Reading files](reading-files.md) - Read files and process them\n19. [Templating](html-templates.md) - Use Go's html/template package to render html from data, and also learn about approval testing\n20. [Generics](generics.md) - Learn how to write functions that take generic arguments and make your own generic data-structure\n21. [Revisiting arrays and slices with generics](revisiting-arrays-and-slices-with-generics.md) - Generics are very useful when working with collections. Learn how to write your own `Reduce` function and tidy up some common patterns.\n\n### Build an application\n\nNow that you have hopefully digested the _Go Fundamentals_ section you have a solid grounding of a majority of Go's language features and how to do TDD.\n\nThis next section will involve building an application.\n\nEach chapter will iterate on the previous one, expanding the application's functionality as our product owner dictates.\n\nNew concepts will be introduced to help facilitate writing great code but most of the new material will be learning what can be accomplished from Go's standard library.\n\nBy the end of this, you should have a strong grasp as to how to iteratively write an application in Go, backed by tests.\n\n* [HTTP server](http-server.md) - We will create an application which listens to HTTP requests and responds to them.\n* [JSON, routing and embedding](json.md) - We will make our endpoints return JSON and explore how to do routing.\n* [IO and sorting](io.md) - We will persist and read our data from disk and we'll cover sorting data.\n* [Command line & project structure](command-line.md) - Support multiple applications from one code base and read input from command line.\n* [Time](time.md) - using the `time` package to schedule activities.\n* [WebSockets](websockets.md) - learn how to write and test a server that uses WebSockets.\n\n### Testing fundamentals\n\nCovering other subjects around testing.\n\n* [Introduction to acceptance tests](intro-to-acceptance-tests.md) - Learn how to write acceptance tests for your code, with a real-world example for gracefully shutting down a HTTP server\n* [Scaling acceptance tests](scaling-acceptance-tests.md) - Learn techniques to manage the complexity of writing acceptance tests for non-trivial systems.\n* [Working without mocks, stubs and spies](working-without-mocks.md) - Learn about how to use fakes and contracts to create more realistic and maintainable tests.\n* [Refactoring Checklist](refactoring-checklist.md) - Some discussion on what refactoring is, and some basic tips on how to do it.\n\n### Questions and answers\n\nI often run in to questions on the internets like\n\n> How do I test my amazing function that does x, y and z\n\nIf you have such a question raise it as an issue on github and I'll try and find time to write a short chapter to tackle the issue. I feel like content like this is valuable as it is tackling people's _real_ questions around testing.\n\n* [OS exec](os-exec.md) - An example of how we can reach out to the OS to execute commands to fetch data and keep our business logic testable/\n* [Error types](error-types.md) - Example of creating your own error types to improve your tests and make your code easier to work with.\n* [Context-aware Reader](context-aware-reader.md) - Learn how to TDD augmenting `io.Reader` with cancellation. Based on [Context-aware io.Reader for Go](https://pace.dev/blog/2020/02/03/context-aware-ioreader-for-golang-by-mat-ryer)\n* [Revisiting HTTP Handlers](http-handlers-revisited.md) - Testing HTTP handlers seems to be the bane of many a developer's existence. This chapter explores the issues around designing handlers correctly.\n\n### Meta / Discussion\n\n* [Why unit tests and how to make them work for you](why.md) - Watch a video, or read about why unit testing and TDD is important\n* [Anti-patterns](anti-patterns.md) - A short chapter on TDD and unit testing anti-patterns\n\n## Contributing\n\n* _This project is work in progress_ If you would like to contribute, please do get in touch.\n* Read [contributing.md](https://github.com/quii/learn-go-with-tests/tree/842f4f24d1f1c20ba3bb23cbc376c7ca6f7ca79a/contributing.md) for guidelines\n* Any ideas? Create an issue\n\n## Background\n\nI have some experience introducing Go to development teams and have tried different approaches as to how to grow a team from some people curious about Go into highly effective writers of Go systems.\n\n### What didn't work\n\n#### Read _the_ book\n\nAn approach we tried was to take [the blue book](https://www.amazon.co.uk/Programming-Language-Addison-Wesley-Professional-Computing/dp/0134190440) and every week discuss the next chapter along with the exercises.\n\nI love this book but it requires a high level of commitment. The book is very detailed in explaining concepts, which is obviously great but it means that the progress is slow and steady - this is not for everyone.\n\nI found that whilst a small number of people would read chapter X and do the exercises, many people didn't.\n\n#### Solve some problems\n\nKatas are fun but they are usually limited in their scope for learning a language; you're unlikely to use goroutines to solve a kata.\n\nAnother problem is when you have varying levels of enthusiasm. Some people just learn way more of the language than others and when demonstrating what they have done end up confusing people with features the others are not familiar with.\n\nThis ends up making the learning feel quite _unstructured_ and _ad hoc_.\n\n### What did work\n\nBy far the most effective way was by slowly introducing the fundamentals of the language by reading through [go by example](https://gobyexample.com/), exploring them with examples and discussing them as a group. This was a more interactive approach than \"read chapter x for homework\".\n\nOver time the team gained a solid foundation of the _grammar_ of the language so we could then start to build systems.\n\nThis to me seems analogous to practicing scales when trying to learn guitar.\n\nIt doesn't matter how artistic you think you are, you are unlikely to write good music without understanding the fundamentals and practicing the mechanics.\n\n### What works for me\n\nWhen _I_ learn a new programming language I usually start by messing around in a REPL but eventually, I need more structure.\n\nWhat I like to do is explore concepts and then solidify the ideas with tests. Tests verify the code I write is correct and documents the feature I have learned.\n\nTaking my experience of learning with a group and my own personal way I am going to try and create something that hopefully proves useful to other teams. Learning the fundamentals by writing small tests so that you can then take your existing software design skills and ship some great systems.\n\n## Who this is for\n\n* People who are interested in picking up Go.\n* People who already know some Go, but want to explore testing with TDD.\n\n## What you'll need\n\n* A computer!\n* [Installed Go](https://golang.org/)\n* A text editor\n* Some experience with programming. Understanding of concepts like `if`, variables, functions etc.\n* Comfortable using the terminal\n\n## Feedback\n\n* Add issues/submit PRs [here](https://github.com/quii/learn-go-with-tests) or [tweet me @quii](https://twitter.com/quii)\n\n[MIT license](LICENSE.md)\n\n[Logo is by egonelbre](https://github.com/egonelbre) What a star!\n"
},
{
"path": "SUMMARY.md",
"content": "# Table of contents\n\n* [Learn Go with Tests](gb-readme.md)\n\n## Go fundamentals\n\n* [Install Go](install-go.md)\n* [Hello, World](hello-world.md)\n* [Integers](integers.md)\n* [Iteration](iteration.md)\n* [Arrays and slices](arrays-and-slices.md)\n* [Structs, methods & interfaces](structs-methods-and-interfaces.md)\n* [Pointers & errors](pointers-and-errors.md)\n* [Maps](maps.md)\n* [Dependency Injection](dependency-injection.md)\n* [Mocking](mocking.md)\n* [Concurrency](concurrency.md)\n* [Select](select.md)\n* [Reflection](reflection.md)\n* [Sync](sync.md)\n* [Context](context.md)\n* [Intro to property based tests](roman-numerals.md)\n* [Maths](math.md)\n* [Reading files](reading-files.md)\n* [Templating](html-templates.md)\n* [Generics](generics.md)\n* [Revisiting arrays and slices with generics](revisiting-arrays-and-slices-with-generics.md)\n\n## Testing fundamentals\n\n* [Introduction to acceptance tests](intro-to-acceptance-tests.md)\n* [Scaling acceptance tests](scaling-acceptance-tests.md)\n* [Working without mocks](working-without-mocks.md)\n* [Refactoring Checklist](refactoring-checklist.md)\n\n## Build an application\n\n* [Intro](app-intro.md)\n* [HTTP server](http-server.md)\n* [JSON, routing and embedding](json.md)\n* [IO and sorting](io.md)\n* [Command line & package structure](command-line.md)\n* [Time](time.md)\n* [WebSockets](websockets.md)\n\n## Questions and answers\n\n* [OS Exec](os-exec.md)\n* [Error types](error-types.md)\n* [Context-aware Reader](context-aware-reader.md)\n* [Revisiting HTTP Handlers](http-handlers-revisited.md)\n\n## Meta\n\n* [Why unit tests and how to make them work for you](why.md)\n* [Anti-patterns](anti-patterns.md)\n* [Contributing](contributing.md)\n* [Chapter Template](template.md)\n"
},
{
"path": "anti-patterns.md",
"content": "# TDD Anti-patterns\n\nFrom time to time it's necessary to review your TDD techniques and remind yourself of behaviours to avoid.\n\nThe TDD process is conceptually simple to follow, but as you do it you'll find it challenging your design skills. **Don't mistake this for TDD being hard, it's design that's hard!**\n\nThis chapter lists a number of TDD and testing anti-patterns, and how to remedy them.\n\n## Not doing TDD at all\n\nOf course, it is possible to write great software without TDD but, a lot of problems I've seen with the design of code and the quality of tests would be very difficult to arrive at if a disciplined approach to TDD had been used.\n\nOne of the strengths of TDD is that it gives you a formal process to break down problems, understand what you're trying to achieve (red), get it done (green), then have a good think about how to make it right (blue/refactor).\n\nWithout this, the process is often ad-hoc and loose, which _can_ make engineering more difficult than it _could_ be.\n\n## Misunderstanding the constraints of the refactoring step\n\nI have been in a number of workshops, mobbing or pairing sessions where someone has made a test pass and is in the refactoring stage. After some thought, they think it would be good to abstract away some code into a new struct; a budding pedant yells:\n\n> You're not allowed to do this! You should write a test for this first, we're doing TDD!\n\nThis seems to be a common misunderstanding. **You can do whatever you like to the code when the tests are green**, the only thing you're not allowed to do is **add or change behaviour**.\n\nThe point of these tests are to give you the _freedom to refactor_, find the right abstractions and make the code easier to change and understand.\n\n## Having tests that won't fail (or, evergreen tests)\n\nIt's astonishing how often this comes up. You start debugging or changing some tests and realise: there are no scenarios where this test can fail. Or at least, it won't fail in the way the test is _supposed_ to be protecting against.\n\nThis is _next to impossible_ with TDD if you're following **the first step**,\n\n> Write a test, see it fail\n\nThis is almost always done when developers write tests _after_ code is written, and/or chasing test coverage rather than creating a useful test suite.\n\n## Useless assertions\n\nEver worked on a system, and you've broken a test, then you see this?\n\n> `false was not equal to true`\n\nI know that false is not equal to true. This is not a helpful message; it doesn't tell me what I've broken. This is a symptom of not following the TDD process and not reading the failure error message.\n\nGoing back to the drawing board,\n\n> Write a test, see it fail (and don't be ashamed of the error message)\n\n## Asserting on irrelevant detail\n\nAn example of this is making an assertion on a complex object, when in practice all you care about in the test is the value of one of the fields.\n\n```go\n// not this, now your test is tightly coupled to the whole object\nif !cmp.Equal(complexObject, want) {\n\tt.Error(\"got %+v, want %+v\", complexObject, want)\n}\n\n// be specific, and loosen the coupling\ngot := complexObject.fieldYouCareAboutForThisTest\nif got != want {\n\tt.Error(\"got %q, want %q\", got, want)\n}\n```\n\nAdditional assertions not only make your test more difficult to read by creating 'noise' in your documentation, but also needlessly couples the test with data it doesn't care about. This means if you happen to change the fields for your object, or the way they behave you may get unexpected compilation problems or failures with your tests.\n\nThis is an example of not following the red stage strictly enough.\n\n- Letting an existing design influence how you write your test **rather than thinking of the desired behaviour**\n- Not giving enough consideration to the failing test's error message\n\n## Lots of assertions within a single scenario for unit tests\n\nMany assertions can make tests difficult to read and challenging to debug when they fail.\n\nThey often creep in gradually, especially if test setup is complicated because you're reluctant to replicate the same horrible setup to assert on something else. Instead of this you should fix the problems in your design which are making it difficult to assert on new things.\n\nA helpful rule of thumb is to aim to make one assertion per test. In Go, take advantage of subtests to clearly delineate between assertions on the occasions where you need to. This is also a handy technique to separate assertions on behaviour vs implementation detail.\n\nFor other tests where setup or execution time may be a constraint (e.g an acceptance test driving a web browser), you need to weigh up the pros and cons of slightly trickier to debug tests against test execution time.\n\n## Not listening to your tests\n\n[Dave Farley in his video \"When TDD goes wrong\"](https://www.youtube.com/watch?v=UWtEVKVPBQ0&feature=youtu.be) points out,\n\n> TDD gives you the fastest feedback possible on your design\n\nFrom my own experience, a lot of developers are trying to practice TDD but frequently ignore the signals coming back to them from the TDD process. So they're still stuck with fragile, annoying systems, with a poor test suite.\n\nSimply put, if testing your code is difficult, then _using_ your code is difficult too. Treat your tests as the first user of your code and then you'll see if your code is pleasant to work with or not.\n\nI've emphasised this a lot in the book, and I'll say it again **listen to your tests**.\n\n### Excessive setup, too many test doubles, etc.\n\nEver looked at a test with 20, 50, 100, 200 lines of setup code before anything interesting in the test happens? Do you then have to change the code and revisit the mess and wish you had a different career?\n\nWhat are the signals here? _Listen_, complicated tests `==` complicated code. Why is your code complicated? Does it have to be?\n\n- When you have lots of test doubles in your tests, that means the code you're testing has lots of dependencies - which means your design needs work.\n- If your test is reliant on setting up various interactions with mocks, that means your code is making lots of interactions with its dependencies. Ask yourself whether these interactions could be simpler.\n\n#### Leaky interfaces\n\nIf you have declared an `interface` that has many methods, that points to a leaky abstraction. Think about how you could define that collaboration with a more consolidated set of methods, ideally one.\n\n#### Interface pollution\n\nAs a Go proverb says, *the bigger the interface, the weaker the abstraction*. If you expose a huge interface to the users of your package, you force them to create in their tests a stub/mock that matches the entire API, providing an implementation also for methods they do not use (sometimes, they just panic to make clear that they should not be used). This situation is an anti-pattern known as [interface pollution](https://rakyll.org/interface-pollution/) and this is the reason why the standard library offers you just tiny little interfaces. \n\nInstead, you should expose from your package a bare struct with all relevant methods exported, leaving to the clients of your API the freedom to declare their own interfaces abstracting over the subset of the methods they need: e.g [go-redis](https://github.com/redis/go-redis) exposes a struct (`redis.Client`) to the API clients.\n\nGenerally speaking, you should expose an interface to the clients only when:\n- the interface consists of a small and coherent set of functions.\n- the interface and its implementation need to be decoupled (e.g. because users can choose among multiple implementations or they need to mock an external dependency).\n\n#### Think about the types of test doubles you use\n\n- Mocks are sometimes helpful, but they're extremely powerful and therefore easy to misuse. Try giving yourself the constraint of using stubs instead.\n- Verifying implementation detail with spies is sometimes helpful, but try to avoid it. Remember your implementation detail is usually not important, and you don't want your tests coupled to them if possible. Look to couple your tests to **useful behaviour rather than incidental details**.\n- [Read my posts on naming test doubles](https://quii.dev/Start_naming_your_test_doubles_correctly) if the taxonomy of test doubles is a little unclear\n\n#### Consolidate dependencies\n\nHere is some code for a `http.HandlerFunc` to handle new user registrations for a website.\n\n```go\ntype User struct {\n\t// Some user fields\n}\n\ntype UserStore interface {\n\tCheckEmailExists(email string) (bool, error)\n\tStoreUser(newUser User) error\n}\n\ntype Emailer interface {\n\tSendEmail(to User, body string, subject string) error\n}\n\nfunc NewRegistrationHandler(userStore UserStore, emailer Emailer) http.HandlerFunc {\n\treturn func(writer http.ResponseWriter, request *http.Request) {\n\t\t// extract out the user from the request body (handle error)\n\t\t// check user exists (handle duplicates, errors)\n\t\t// store user (handle errors)\n\t\t// compose and send confirmation email (handle error)\n\t\t// if we got this far, return 2xx response\n\t}\n}\n```\n\nAt first pass it's reasonable to say the design isn't so bad. It only has 2 dependencies!\n\nRe-evaluate the design by considering the handler's responsibilities:\n\n- Parse the request body into a `User` :white_check_mark:\n- Use `UserStore` to check if the user exists :question:\n- Use `UserStore` to store the user :question:\n- Compose an email :question:\n- Use `Emailer` to send the email :question:\n- Return an appropriate http response, depending on success, errors, etc :white_check_mark:\n\nTo exercise this code, you're going to have to write many tests with varying degrees of test double setups, spies, etc\n\n- What if the requirements expand? Translations for the emails? Sending an SMS confirmation too? Does it make sense to you that you have to change a HTTP handler to accommodate this change?\n- Does it feel right that the important rule of \"we should send an email\" resides within a HTTP handler?\n - Why do you have to go through the ceremony of creating HTTP requests and reading responses to verify that rule?\n\n**Listen to your tests**. Writing tests for this code in a TDD fashion should quickly make you feel uncomfortable (or at least, make the lazy developer in you be annoyed). If it feels painful, stop and think.\n\nWhat if the design was like this instead?\n\n```go\ntype UserService interface {\n\tRegister(newUser User) error\n}\n\nfunc NewRegistrationHandler(userService UserService) http.HandlerFunc {\n\treturn func(writer http.ResponseWriter, request *http.Request) {\n\t\t// parse user\n\t\t// register user\n\t\t// check error, send response\n\t}\n}\n```\n\n- Simple to test the handler ✅\n- Changes to the rules around registration are isolated away from HTTP, so they are also simpler to test ✅\n\n## Violating encapsulation\n\nEncapsulation is very important. There's a reason we don't make everything in a package exported (or public). We want coherent APIs with a small surface area to avoid tight coupling.\n\nPeople will sometimes be tempted to make a function or method public in order to test something. By doing this you make your design worse and send confusing messages to maintainers and users of your code.\n\nA result of this can be developers trying to debug a test and then eventually realising the function being tested is _only called from tests_. Which is obviously **a terrible outcome, and a waste of time**.\n\nIn Go, consider your default position for writing tests as _from the perspective of a consumer of your package_. You can make this a compile-time constraint by having your tests live in a test package e.g `package gocoin_test`. If you do this, you'll only have access to the exported members of the package so it won't be possible to couple yourself to implementation detail.\n\n## Complicated table tests\n\nTable tests are a great way of exercising a number of different scenarios when the test setup is the same, and you only wish to vary the inputs.\n\n_But_ they can be messy to read and understand when you try to shoehorn other kinds of tests under the name of having one, glorious table.\n\n```go\ncases := []struct {\n\tX int\n\tY int\n\tZ int\n\terr error\n\tIsFullMoon bool\n\tIsLeapYear bool\n\tAtWarWithEurasia bool\n}{}\n```\n\n**Don't be afraid to break out of your table and write new tests** rather than adding new fields and booleans to the table `struct`.\n\nA thing to bear in mind when writing software is,\n\n> [Simple is not easy](https://www.infoq.com/presentations/Simple-Made-Easy/)\n\n\"Just\" adding a field to a table might be easy, but it can make things far from simple.\n\n## Summary\n\nMost problems with unit tests can normally be traced to:\n\n- Developers not following the TDD process\n- Poor design\n\nSo, learn about good software design!\n\nThe good news is TDD can help you _improve your design skills_ because as stated in the beginning:\n\n**TDD's main purpose is to provide feedback on your design.** For the millionth time, listen to your tests, they are reflecting your design back at you.\n\nBe honest about the quality of your tests by listening to the feedback they give you, and you'll become a better developer for it.\n"
},
{
"path": "app-intro.md",
"content": "# Build an application\n\nNow that you have hopefully digested the _Go Fundamentals_ section you have a solid grounding of a majority of Go's language features and how to do TDD.\n\nThis next section will involve building an application.\n\nEach chapter will iterate on the previous one, expanding the application's functionality as our product owner dictates.\n\nNew concepts will be introduced to help facilitate writing great code but most of the new material will be learning what can be accomplished from Go's standard library.\n\nBy the end of this, you should have a strong grasp as to how to iteratively write an application in Go, backed by tests.\n\n- [HTTP server](http-server.md) - We will create an application which listens to HTTP requests and responds to them.\n- [JSON, routing and embedding](json.md) - We will make our endpoints return JSON and explore how to do routing.\n- [IO and sorting](io.md) - We will persist and read our data from disk and we'll cover sorting data.\n- [Command line & project structure](command-line.md) - Support multiple applications from one code base and read input from command line.\n- [Time](time.md) - using the `time` package to schedule activities.\n- [WebSockets](websockets.md) - learn how to write and test a server that uses WebSockets.\n"
},
{
"path": "arrays/v1/sum.go",
"content": "package main\n\n// Sum calculates the total from an array of numbers.\nfunc Sum(numbers [5]int) int {\n\tsum := 0\n\tfor i := 0; i < 5; i++ {\n\t\tsum += numbers[i]\n\t}\n\treturn sum\n}\n"
},
{
"path": "arrays/v1/sum_test.go",
"content": "package main\n\nimport \"testing\"\n\nfunc TestSum(t *testing.T) {\n\n\tnumbers := [5]int{1, 2, 3, 4, 5}\n\n\tgot := Sum(numbers)\n\twant := 15\n\n\tif want != got {\n\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t}\n}\n"
},
{
"path": "arrays/v2/sum.go",
"content": "package main\n\n// Sum calculates the total from an array of numbers.\nfunc Sum(numbers [5]int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n"
},
{
"path": "arrays/v2/sum_test.go",
"content": "package main\n\nimport \"testing\"\n\nfunc TestSum(t *testing.T) {\n\n\tnumbers := [5]int{1, 2, 3, 4, 5}\n\n\tgot := Sum(numbers)\n\twant := 15\n\n\tif got != want {\n\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t}\n}\n"
},
{
"path": "arrays/v3/sum.go",
"content": "package main\n\n// Sum calculates the total from a slice of numbers.\nfunc Sum(numbers []int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n"
},
{
"path": "arrays/v3/sum_test.go",
"content": "package main\n\nimport \"testing\"\n\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collections of any size\", func(t *testing.T) {\n\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n}\n"
},
{
"path": "arrays/v4/sum.go",
"content": "package main\n\n// Sum calculates the total from a slice of numbers.\nfunc Sum(numbers []int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n\n// SumAll calculates the respective sums of every slice passed in.\nfunc SumAll(numbersToSum ...[]int) []int {\n\tlengthOfNumbers := len(numbersToSum)\n\tsums := make([]int, lengthOfNumbers)\n\n\tfor i, numbers := range numbersToSum {\n\t\tsums[i] = Sum(numbers)\n\t}\n\n\treturn sums\n}\n"
},
{
"path": "arrays/v4/sum_test.go",
"content": "package main\n\nimport (\n\t\"slices\"\n\t\"testing\"\n)\n\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collections of any size\", func(t *testing.T) {\n\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n}\n\nfunc TestSumAll(t *testing.T) {\n\n\tgot := SumAll([]int{1, 2}, []int{0, 9})\n\twant := []int{3, 9}\n\n\tif !slices.Equal(got, want) {\n\t\tt.Errorf(\"got %v want %v\", got, want)\n\t}\n}\n"
},
{
"path": "arrays/v5/sum.go",
"content": "package main\n\n// Sum calculates the total from a slice of numbers.\nfunc Sum(numbers []int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n\n// SumAll calculates the respective sums of every slice passed in.\nfunc SumAll(numbersToSum ...[]int) []int {\n\tvar sums []int\n\tfor _, numbers := range numbersToSum {\n\t\tsums = append(sums, Sum(numbers))\n\t}\n\n\treturn sums\n}\n"
},
{
"path": "arrays/v5/sum_test.go",
"content": "package main\n\nimport (\n\t\"slices\"\n\t\"testing\"\n)\n\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collections of any size\", func(t *testing.T) {\n\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n}\n\nfunc TestSumAll(t *testing.T) {\n\n\tgot := SumAll([]int{1, 2}, []int{0, 9})\n\twant := []int{3, 9}\n\n\tif !slices.Equal(got, want) {\n\t\tt.Errorf(\"got %v want %v\", got, want)\n\t}\n}\n"
},
{
"path": "arrays/v6/sum.go",
"content": "package main\n\n// Sum calculates the total from a slice of numbers.\nfunc Sum(numbers []int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n\n// SumAllTails calculates the respective sums of every slice passed in.\nfunc SumAllTails(numbersToSum ...[]int) []int {\n\tvar sums []int\n\tfor _, numbers := range numbersToSum {\n\t\ttail := numbers[1:]\n\t\tsums = append(sums, Sum(tail))\n\t}\n\n\treturn sums\n}\n"
},
{
"path": "arrays/v6/sum_test.go",
"content": "package main\n\nimport (\n\t\"slices\"\n\t\"testing\"\n)\n\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collections of any size\", func(t *testing.T) {\n\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n}\n\nfunc TestSumAllTails(t *testing.T) {\n\n\tgot := SumAllTails([]int{1, 2}, []int{0, 9})\n\twant := []int{2, 9}\n\n\tif !slices.Equal(got, want) {\n\t\tt.Errorf(\"got %v want %v\", got, want)\n\t}\n}\n"
},
{
"path": "arrays/v7/sum.go",
"content": "package main\n\n// Sum calculates the total from a slice of numbers.\nfunc Sum(numbers []int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n\n// SumAllTails calculates the sums of all but the first number given a collection of slices.\nfunc SumAllTails(numbersToSum ...[]int) []int {\n\tvar sums []int\n\tfor _, numbers := range numbersToSum {\n\t\tif len(numbers) == 0 {\n\t\t\tsums = append(sums, 0)\n\t\t} else {\n\t\t\ttail := numbers[1:]\n\t\t\tsums = append(sums, Sum(tail))\n\t\t}\n\t}\n\n\treturn sums\n}\n"
},
{
"path": "arrays/v7/sum_test.go",
"content": "package main\n\nimport (\n\t\"slices\"\n\t\"testing\"\n)\n\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collections of any size\", func(t *testing.T) {\n\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n}\n\nfunc TestSumAllTails(t *testing.T) {\n\n\tcheckSums := func(t *testing.T, got, want []int) {\n\t\tif !slices.Equal(got, want) {\n\t\t\tt.Errorf(\"got %v want %v\", got, want)\n\t\t}\n\t}\n\n\tt.Run(\"make the sums of tails of\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{1, 2}, []int{0, 9})\n\t\twant := []int{2, 9}\n\t\tcheckSums(t, got, want)\n\t})\n\n\tt.Run(\"safely sum empty slices\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{}, []int{3, 4, 5})\n\t\twant := []int{0, 9}\n\t\tcheckSums(t, got, want)\n\t})\n\n}\n"
},
{
"path": "arrays/v8/assert.go",
"content": "package main\n\nimport \"testing\"\n\nfunc AssertEqual[T comparable](t *testing.T, got, want T) {\n\tt.Helper()\n\tif got != want {\n\t\tt.Errorf(\"got %v, want %v\", got, want)\n\t}\n}\n\nfunc AssertNotEqual[T comparable](t *testing.T, got, want T) {\n\tt.Helper()\n\tif got == want {\n\t\tt.Errorf(\"didn't want %v\", got)\n\t}\n}\n\nfunc AssertTrue(t *testing.T, got bool) {\n\tt.Helper()\n\tif !got {\n\t\tt.Errorf(\"got %v, want true\", got)\n\t}\n}\n\nfunc AssertFalse(t *testing.T, got bool) {\n\tt.Helper()\n\tif got {\n\t\tt.Errorf(\"got %v, want false\", got)\n\t}\n}\n"
},
{
"path": "arrays/v8/bad_bank.go",
"content": "package main\n\ntype Transaction struct {\n\tFrom string\n\tTo string\n\tSum float64\n}\n\nfunc NewTransaction(from, to Account, sum float64) Transaction {\n\treturn Transaction{From: from.Name, To: to.Name, Sum: sum}\n}\n\ntype Account struct {\n\tName string\n\tBalance float64\n}\n\nfunc NewBalanceFor(account Account, transactions []Transaction) Account {\n\treturn Reduce(\n\t\ttransactions,\n\t\tapplyTransaction,\n\t\taccount,\n\t)\n}\n\nfunc applyTransaction(a Account, transaction Transaction) Account {\n\tif transaction.From == a.Name {\n\t\ta.Balance -= transaction.Sum\n\t}\n\tif transaction.To == a.Name {\n\t\ta.Balance += transaction.Sum\n\t}\n\treturn a\n}\n"
},
{
"path": "arrays/v8/bad_bank_test.go",
"content": "package main\n\nimport \"testing\"\n\nfunc TestBadBank(t *testing.T) {\n\tvar (\n\t\triya = Account{Name: \"Riya\", Balance: 100}\n\t\tchris = Account{Name: \"Chris\", Balance: 75}\n\t\tadil = Account{Name: \"Adil\", Balance: 200}\n\n\t\ttransactions = []Transaction{\n\t\t\tNewTransaction(chris, riya, 100),\n\t\t\tNewTransaction(adil, chris, 25),\n\t\t}\n\t)\n\n\tnewBalanceFor := func(account Account) float64 {\n\t\treturn NewBalanceFor(account, transactions).Balance\n\t}\n\n\tAssertEqual(t, newBalanceFor(riya), 200)\n\tAssertEqual(t, newBalanceFor(chris), 0)\n\tAssertEqual(t, newBalanceFor(adil), 175)\n}\n"
},
{
"path": "arrays/v8/collection_fun.go",
"content": "package main\n\nfunc Find[A any](items []A, predicate func(A) bool) (value A, found bool) {\n\tfor _, v := range items {\n\t\tif predicate(v) {\n\t\t\treturn v, true\n\t\t}\n\t}\n\treturn\n}\n\nfunc Reduce[A, B any](collection []A, f func(B, A) B, initialValue B) B {\n\tvar result = initialValue\n\tfor _, x := range collection {\n\t\tresult = f(result, x)\n\t}\n\treturn result\n}\n"
},
{
"path": "arrays/v8/sum.go",
"content": "package main\n\n// Sum calculates the total from a slice of numbers.\nfunc Sum(numbers []int) int {\n\tadd := func(acc, x int) int { return acc + x }\n\treturn Reduce(numbers, add, 0)\n}\n\n// SumAllTails calculates the sums of all but the first number given a collection of slices.\nfunc SumAllTails(numbers ...[]int) []int {\n\tsumTail := func(acc, x []int) []int {\n\t\tif len(x) == 0 {\n\t\t\treturn append(acc, 0)\n\t\t} else {\n\t\t\ttail := x[1:]\n\t\t\treturn append(acc, Sum(tail))\n\t\t}\n\t}\n\n\treturn Reduce(numbers, sumTail, []int{})\n}\n"
},
{
"path": "arrays/v8/sum_test.go",
"content": "package main\n\nimport (\n\t\"slices\"\n\t\"strings\"\n\t\"testing\"\n)\n\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collections of any size\", func(t *testing.T) {\n\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n}\n\nfunc TestSumAllTails(t *testing.T) {\n\n\tcheckSums := func(t *testing.T, got, want []int) {\n\t\tif !slices.Equal(got, want) {\n\t\t\tt.Errorf(\"got %v want %v\", got, want)\n\t\t}\n\t}\n\n\tt.Run(\"make the sums of tails of\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{1, 2}, []int{0, 9})\n\t\twant := []int{2, 9}\n\t\tcheckSums(t, got, want)\n\t})\n\n\tt.Run(\"safely sum empty slices\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{}, []int{3, 4, 5})\n\t\twant := []int{0, 9}\n\t\tcheckSums(t, got, want)\n\t})\n\n}\n\nfunc TestReduce(t *testing.T) {\n\tt.Run(\"multiplication of all elements\", func(t *testing.T) {\n\t\tmultiply := func(x, y int) int {\n\t\t\treturn x * y\n\t\t}\n\n\t\tAssertEqual(t, Reduce([]int{1, 2, 3}, multiply, 1), 6)\n\t})\n\n\tt.Run(\"concatenate strings\", func(t *testing.T) {\n\t\tconcatenate := func(x, y string) string {\n\t\t\treturn x + y\n\t\t}\n\n\t\tAssertEqual(t, Reduce([]string{\"a\", \"b\", \"c\"}, concatenate, \"\"), \"abc\")\n\t})\n}\n\nfunc TestFind(t *testing.T) {\n\tt.Run(\"find first even number\", func(t *testing.T) {\n\t\tnumbers := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}\n\n\t\tfirstEvenNumber, found := Find(numbers, func(x int) bool {\n\t\t\treturn x%2 == 0\n\t\t})\n\t\tAssertTrue(t, found)\n\t\tAssertEqual(t, firstEvenNumber, 2)\n\t})\n\n\ttype Person struct {\n\t\tName string\n\t}\n\n\tt.Run(\"Find the best programmer\", func(t *testing.T) {\n\t\tpeople := []Person{\n\t\t\tPerson{Name: \"Kent Beck\"},\n\t\t\tPerson{Name: \"Martin Fowler\"},\n\t\t\tPerson{Name: \"Chris James\"},\n\t\t}\n\n\t\tking, found := Find(people, func(p Person) bool {\n\t\t\treturn strings.Contains(p.Name, \"Chris\")\n\t\t})\n\n\t\tAssertTrue(t, found)\n\t\tAssertEqual(t, king, Person{Name: \"Chris James\"})\n\t})\n}\n"
},
{
"path": "arrays-and-slices.md",
"content": "# Arrays and slices\n\n**[You can find all the code for this chapter here](https://github.com/quii/learn-go-with-tests/tree/main/arrays)**\n\nArrays allow you to store multiple elements of the same type in a variable in\na particular order.\n\nWhen you have arrays, it is very common to have to iterate over them. So let's\nuse [our new-found knowledge of `for`](iteration.md) to make a `Sum` function. `Sum` will\ntake an array of numbers and return the total.\n\nLet's use our TDD skills\n\n## Write the test first\n\nCreate a new folder to work in. Create a new file called `sum_test.go` and insert the following:\n\n```go\npackage main\n\nimport \"testing\"\n\nfunc TestSum(t *testing.T) {\n\n\tnumbers := [5]int{1, 2, 3, 4, 5}\n\n\tgot := Sum(numbers)\n\twant := 15\n\n\tif got != want {\n\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t}\n}\n```\n\nArrays have a _fixed capacity_ which you define when you declare the variable.\nWe can initialize an array in two ways:\n\n* \\[N\\]type{value1, value2, ..., valueN} e.g. `numbers := [5]int{1, 2, 3, 4, 5}`\n* \\[...\\]type{value1, value2, ..., valueN} e.g. `numbers := [...]int{1, 2, 3, 4, 5}`\n\nIt is sometimes useful to also print the inputs to the function in the error message.\nHere, we are using the `%v` placeholder to print the \"default\" format, which works well for arrays.\n\n[Read more about the format strings](https://golang.org/pkg/fmt/)\n\n## Try to run the test\n\nIf you had initialized go mod with `go mod init main` you will be presented with an error\n`_testmain.go:13:2: cannot import \"main\"`. This is because according to common practice,\npackage main will only contain integration of other packages and not unit-testable code and\nhence Go will not allow you to import a package with name `main`.\n\nTo fix this, you can rename the main module in `go.mod` to any other name.\n\nOnce the above error is fixed, if you run `go test` the compiler will fail with the familiar\n`./sum_test.go:10:15: undefined: Sum` error. Now we can proceed with writing the actual method\nto be tested.\n\n## Write the minimal amount of code for the test to run and check the failing test output\n\nIn `sum.go`\n\n```go\npackage main\n\nfunc Sum(numbers [5]int) int {\n\treturn 0\n}\n```\n\nYour test should now fail with _a clear error message_\n\n`sum_test.go:13: got 0 want 15 given, [1 2 3 4 5]`\n\n## Write enough code to make it pass\n\n```go\nfunc Sum(numbers [5]int) int {\n\tsum := 0\n\tfor i := 0; i < 5; i++ {\n\t\tsum += numbers[i]\n\t}\n\treturn sum\n}\n```\n\nTo get the value out of an array at a particular index, just use `array[index]`\nsyntax. In this case, we are using `for` to iterate 5 times to work through the\narray and add each item onto `sum`.\n\n## Refactor\n\nLet's introduce [`range`](https://gobyexample.com/range) to help clean up our code\n\n```go\nfunc Sum(numbers [5]int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n```\n\n`range` lets you iterate over an array. On each iteration, `range` returns two values - the index and the value.\nWe are choosing to ignore the index value by using `_` [blank identifier](https://golang.org/doc/effective_go.html#blank).\n\n### Arrays and their type\n\nAn interesting property of arrays is that the size is encoded in its type. If you try\nto pass an `[4]int` into a function that expects `[5]int`, it won't compile.\nThey are different types so it's just the same as trying to pass a `string` into\na function that wants an `int`.\n\nYou may be thinking it's quite cumbersome that arrays have a fixed length, and most\nof the time you probably won't be using them!\n\nGo has _slices_ which do not encode the size of the collection and instead can\nhave any size.\n\nThe next requirement will be to sum collections of varying sizes.\n\n## Write the test first\n\nWe will now use the [slice type][slice] which allows us to have collections of\nany size. The syntax is very similar to arrays, you just omit the size when\ndeclaring them\n\n`mySlice := []int{1,2,3}` rather than `myArray := [3]int{1,2,3}`\n\n```go\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collection of 5 numbers\", func(t *testing.T) {\n\t\tnumbers := [5]int{1, 2, 3, 4, 5}\n\n\t\tgot := Sum(numbers)\n\t\twant := 15\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n\tt.Run(\"collection of any size\", func(t *testing.T) {\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n}\n```\n\n## Try and run the test\n\nThis does not compile\n\n`./sum_test.go:22:13: cannot use numbers (type []int) as type [5]int in argument to Sum`\n\n## Write the minimal amount of code for the test to run and check the failing test output\n\nThe problem here is we can either\n\n* Break the existing API by changing the argument to `Sum` to be a slice rather\n than an array. When we do this, we will potentially ruin\n someone's day because our _other_ test will no longer compile!\n* Create a new function\n\nIn our case, no one else is using our function, so rather than having two functions to maintain, let's have just one.\n\n```go\nfunc Sum(numbers []int) int {\n\tsum := 0\n\tfor _, number := range numbers {\n\t\tsum += number\n\t}\n\treturn sum\n}\n```\n\nIf you try to run the tests they will still not compile, you will have to change the first test to pass in a slice rather than an array.\n\n## Write enough code to make it pass\n\nIt turns out that fixing the compiler problems were all we need to do here and the tests pass!\n\n## Refactor\n\nWe already refactored `Sum` - all we did was replace arrays with slices, so no extra changes are required.\nRemember that we must not neglect our test code in the refactoring stage - we can further improve our `Sum` tests.\n\n```go\nfunc TestSum(t *testing.T) {\n\n\tt.Run(\"collection of 5 numbers\", func(t *testing.T) {\n\t\tnumbers := []int{1, 2, 3, 4, 5}\n\n\t\tgot := Sum(numbers)\n\t\twant := 15\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n\tt.Run(\"collection of any size\", func(t *testing.T) {\n\t\tnumbers := []int{1, 2, 3}\n\n\t\tgot := Sum(numbers)\n\t\twant := 6\n\n\t\tif got != want {\n\t\t\tt.Errorf(\"got %d want %d given, %v\", got, want, numbers)\n\t\t}\n\t})\n\n}\n```\n\nIt is important to question the value of your tests. It should not be a goal to\nhave as many tests as possible, but rather to have as much _confidence_ as\npossible in your code base. Having too many tests can turn in to a real problem\nand it just adds more overhead in maintenance. **Every test has a cost**.\n\nIn our case, you can see that having two tests for this function is redundant.\nIf it works for a slice of one size it's very likely it'll work for a slice of\nany size \\(within reason\\).\n\nGo's built-in testing toolkit features a [coverage tool](https://blog.golang.org/cover).\nWhilst striving for 100% coverage should not be your end goal, the coverage tool can help\nidentify areas of your code not covered by tests. If you have been strict with TDD,\nit's quite likely you'll have close to 100% coverage anyway.\n\nTry running\n\n`go test -cover`\n\nYou should see\n\n```bash\nPASS\ncoverage: 100.0% of statements\n```\n\nNow delete one of the tests and check the coverage again.\n\nNow that we are happy we have a well-tested function you should commit your\ngreat work before taking on the next challenge.\n\nWe need a new function called `SumAll` which will take a varying number of\nslices, returning a new slice containing the totals for each slice passed in.\n\nFor example\n\n`SumAll([]int{1,2}, []int{0,9})` would return `[]int{3, 9}`\n\nor\n\n`SumAll([]int{1,1,1})` would return `[]int{3}`\n\n## Write the test first\n\n```go\nfunc TestSumAll(t *testing.T) {\n\n\tgot := SumAll([]int{1, 2}, []int{0, 9})\n\twant := []int{3, 9}\n\n\tif got != want {\n\t\tt.Errorf(\"got %v want %v\", got, want)\n\t}\n}\n```\n\n## Try and run the test\n\n`./sum_test.go:23:9: undefined: SumAll`\n\n## Write the minimal amount of code for the test to run and check the failing test output\n\nWe need to define `SumAll` according to what our test wants.\n\nGo can let you write [_variadic functions_](https://gobyexample.com/variadic-functions) that can take a variable number of arguments.\n\n```go\nfunc SumAll(numbersToSum ...[]int) []int {\n\treturn nil\n}\n```\n\nThis is valid, but our tests still won't compile!\n\n`./sum_test.go:26:9: invalid operation: got != want (slice can only be compared to nil)`\n\nGo does not let you use equality operators with slices. You _could_ write\na function to iterate over each `got` and `want` slice and check their values,\nbut what if we had a more convenient way to do this?\n\nFrom Go 1.21, [slices](https://pkg.go.dev/slices#pkg-overview) standard package is available, which has [slices.Equal](https://pkg.go.dev/slices#Equal) function to do a simple shallow compare on slices, where you don't need to worry about the types like the above case.\nNote that this function expects the elements to be [comparable](https://pkg.go.dev/builtin#comparable).\nSo, it can't be applied to slices with non-comparable elements like 2D slices.\n\nLet's go ahead and put this into practice!\n\n```go\nfunc TestSumAll(t *testing.T) {\n\n\tgot := SumAll([]int{1, 2}, []int{0, 9})\n\twant := []int{3, 9}\n\n\tif !slices.Equal(got, want) {\n\t\tt.Errorf(\"got %v want %v\", got, want)\n\t}\n}\n```\n\nYou should have test output like the following:\n`sum_test.go:30: got [] want [3 9]`\n\n## Write enough code to make it pass\n\nWhat we need to do is iterate over the varargs, calculate the sum using our\nexisting `Sum` function, then add it to the slice we will return\n\n```go\nfunc SumAll(numbersToSum ...[]int) []int {\n\tlengthOfNumbers := len(numbersToSum)\n\tsums := make([]int, lengthOfNumbers)\n\n\tfor i, numbers := range numbersToSum {\n\t\tsums[i] = Sum(numbers)\n\t}\n\n\treturn sums\n}\n```\n\nLots of new things to learn!\n\nThere's a new way to create a slice. `make` allows you to create a slice with\na starting capacity of the `len` of the `numbersToSum` we need to work through. The length of a slice is the number of elements it holds `len(mySlice)`, while the capacity is the number of elements it can hold in the underlying array `cap(mySlice)`, e.g., `make([]int, 0, 5)` creates a slice with length 0 and capacity 5.\n\nYou can index slices like arrays with `mySlice[N]` to get the value out or\nassign it a new value with `=`\n\nThe tests should now pass.\n\n## Refactor\n\nAs mentioned, slices have a capacity. If you have a slice with a capacity of\n2 and try to do `mySlice[10] = 1` you will get a _runtime_ error.\n\nHowever, you can use the `append` function which takes a slice and a new value,\nthen returns a new slice with all the items in it.\n\n```go\nfunc SumAll(numbersToSum ...[]int) []int {\n\tvar sums []int\n\tfor _, numbers := range numbersToSum {\n\t\tsums = append(sums, Sum(numbers))\n\t}\n\n\treturn sums\n}\n```\n\nIn this implementation, we are worrying less about capacity. We start with an\nempty slice `sums` and append to it the result of `Sum` as we work through the varargs.\n\nOur next requirement is to change `SumAll` to `SumAllTails`, where it will\ncalculate the totals of the \"tails\" of each slice. The tail of a collection is\nall items in the collection except the first one \\(the \"head\"\\).\n\n## Write the test first\n\n```go\nfunc TestSumAllTails(t *testing.T) {\n\tgot := SumAllTails([]int{1, 2}, []int{0, 9})\n\twant := []int{2, 9}\n\n\tif !reflect.DeepEqual(got, want) {\n\t\tt.Errorf(\"got %v want %v\", got, want)\n\t}\n}\n```\n\n## Try and run the test\n\n`./sum_test.go:26:9: undefined: SumAllTails`\n\n## Write the minimal amount of code for the test to run and check the failing test output\n\nRename the function to `SumAllTails` and re-run the test\n\n`sum_test.go:30: got [3 9] want [2 9]`\n\n## Write enough code to make it pass\n\n```go\nfunc SumAllTails(numbersToSum ...[]int) []int {\n\tvar sums []int\n\tfor _, numbers := range numbersToSum {\n\t\ttail := numbers[1:]\n\t\tsums = append(sums, Sum(tail))\n\t}\n\n\treturn sums\n}\n```\n\nSlices can be sliced! The syntax is `slice[low:high]`. If you omit the value on\none of the sides of the `:` it captures everything to that side of it. In our\ncase, we are saying \"take from 1 to the end\" with `numbers[1:]`. You may wish to\nspend some time writing other tests around slices and experiment with the\nslice operator to get more familiar with it.\n\n## Refactor\n\nNot a lot to refactor this time.\n\nWhat do you think would happen if you passed in an empty slice into our\nfunction? What is the \"tail\" of an empty slice? What happens when you tell Go to\ncapture all elements from `myEmptySlice[1:]`?\n\n## Write the test first\n\n```go\nfunc TestSumAllTails(t *testing.T) {\n\n\tt.Run(\"make the sums of some slices\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{1, 2}, []int{0, 9})\n\t\twant := []int{2, 9}\n\n\t\tif !reflect.DeepEqual(got, want) {\n\t\t\tt.Errorf(\"got %v want %v\", got, want)\n\t\t}\n\t})\n\n\tt.Run(\"safely sum empty slices\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{}, []int{3, 4, 5})\n\t\twant := []int{0, 9}\n\n\t\tif !reflect.DeepEqual(got, want) {\n\t\t\tt.Errorf(\"got %v want %v\", got, want)\n\t\t}\n\t})\n\n}\n```\n\n## Try and run the test\n\n```text\npanic: runtime error: slice bounds out of range [recovered]\n panic: runtime error: slice bounds out of range\n```\n\nOh no! It's important to note that while the test _has compiled_, it _has a runtime error_.\n\nCompile time errors are our friend because they help us write software that works,\nruntime errors are our enemies because they affect our users.\n\n## Write enough code to make it pass\n\n```go\nfunc SumAllTails(numbersToSum ...[]int) []int {\n\tvar sums []int\n\tfor _, numbers := range numbersToSum {\n\t\tif len(numbers) == 0 {\n\t\t\tsums = append(sums, 0)\n\t\t} else {\n\t\t\ttail := numbers[1:]\n\t\t\tsums = append(sums, Sum(tail))\n\t\t}\n\t}\n\n\treturn sums\n}\n```\n\n## Refactor\n\nOur tests have some repeated code around the assertions again, so let's extract those into a function.\n\n```go\nfunc TestSumAllTails(t *testing.T) {\n\n\tcheckSums := func(t testing.TB, got, want []int) {\n\t\tt.Helper()\n\t\tif !reflect.DeepEqual(got, want) {\n\t\t\tt.Errorf(\"got %v want %v\", got, want)\n\t\t}\n\t}\n\n\tt.Run(\"make the sums of tails of\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{1, 2}, []int{0, 9})\n\t\twant := []int{2, 9}\n\t\tcheckSums(t, got, want)\n\t})\n\n\tt.Run(\"safely sum empty slices\", func(t *testing.T) {\n\t\tgot := SumAllTails([]int{}, []int{3, 4, 5})\n\t\twant := []int{0, 9}\n\t\tcheckSums(t, got, want)\n\t})\n\n}\n```\n\nWe could've created a new function `checkSums` like we normally do, but in this case, we're showing a new technique, assigning a function to a variable. It might look strange but, it's no different to assigning a variable to a `string`, or an `int`, functions in effect are values too.\n\nIt's not shown here, but this technique can be useful when you want to bind a function to other local variables in \"scope\" (e.g between some `{}`). It also allows you to reduce the surface area of your API.\n\nBy defining this function inside the test, it cannot be used by other functions in this package. Hiding variables and functions that don't need to be exported is an important design consideration.\n\nA handy side-effect of this is this adds a little type-safety to our code. If\na developer mistakenly adds a new test with `checkSums(t, got, \"dave\")` the compiler\nwill stop them in their tracks.\n\n```bash\n$ go test\n./sum_test.go:52:21: cannot use \"dave\" (type string) as type []int in argument to checkSums\n```\n\n## Wrapping up\n\nWe have covered\n\n* Arrays\n* Slices\n * The various ways to make them\n * How they have a _fixed_ capacity but you can create new slices from old ones\n using `append`\n * How to slice, slices!\n* `len` to get the length of an array or slice\n* Test coverage tool\n* `reflect.DeepEqual` and why it's useful but can reduce the type-safety of your code\n\nWe've used slices and arrays with integers but they work with any other type\ntoo, including arrays/slices themselves. So you can declare a variable of\n`[][]string` if you need to.\n\n[Check out the Go blog post on slices][blog-slice] for an in-depth look into\nslices. Try writing more tests to solidify what you learn from reading it.\n\nAnother handy way to experiment with Go other than writing tests is the Go\nplayground. You can try most things out and you can easily share your code if\nyou need to ask questions. [I have made a go playground with a slice in it for you to experiment with.](https://play.golang.org/p/ICCWcRGIO68)\n\n[Here is an example](https://play.golang.org/p/bTrRmYfNYCp) of slicing an array\nand how changing the slice affects the original array; but a \"copy\" of the slice\nwill not affect the original array.\n[Another example](https://play.golang.org/p/Poth8JS28sc) of why it's a good idea\nto make a copy of a slice after slicing a very large slice.\n\n[for]: ../iteration.md#\n[blog-slice]: https://blog.golang.org/go-slices-usage-and-internals\n[deepEqual]: https://golang.org/pkg/reflect/#DeepEqual\n[slice]: https://golang.org/doc/effective_go.html#slices\n"
},
{
"path": "blogrenderer/post.go",
"content": "package blogrenderer\n\nimport \"strings\"\n\n// Post is a representation of a post\ntype Post struct {\n\tTitle, Description, Body string\n\tTags []string\n}\n\n// SanitisedTitle returns the title of the post with spaces replaced by dashes for pleasant URLs\nfunc (p Post) SanitisedTitle() string {\n\treturn strings.ToLower(strings.Replace(p.Title, \" \", \"-\", -1))\n}\n"
},
{
"path": "blogrenderer/renderer.go",
"content": "package blogrenderer\n\nimport (\n\t\"embed\"\n\t\"github.com/gomarkdown/markdown\"\n\t\"github.com/gomarkdown/markdown/parser\"\n\t\"html/template\"\n\t\"io\"\n)\n\nvar (\n\t//go:embed \"templates/*\"\n\tpostTemplates embed.FS\n)\n\n// PostRenderer renders data into HTML\ntype PostRenderer struct {\n\ttempl *template.Template\n\tmdParser *parser.Parser\n}\n\n// NewPostRenderer creates a new PostRenderer\nfunc NewPostRenderer() (*PostRenderer, error) {\n\ttempl, err := template.ParseFS(postTemplates, \"templates/*.gohtml\")\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\textensions := parser.CommonExtensions | parser.AutoHeadingIDs\n\tparser := parser.NewWithExtensions(extensions)\n\n\treturn &PostRenderer{templ: templ, mdParser: parser}, nil\n}\n\n// Render renders post into HTML\nfunc (r *PostRenderer) Render(w io.Writer, p Post) error {\n\treturn r.templ.ExecuteTemplate(w, \"blog.gohtml\", newPostVM(p, r))\n}\n\n// RenderIndex creates an HTML index page given a collection of posts\nfunc (r *PostRenderer) RenderIndex(w io.Writer, posts []Post) error {\n\treturn r.templ.ExecuteTemplate(w, \"index.gohtml\", posts)\n}\n\ntype postViewModel struct {\n\tPost\n\tHTMLBody template.HTML\n}\n\nfunc newPostVM(p Post, r *PostRenderer) postViewModel {\n\tvm := postViewModel{Post: p}\n\tvm.HTMLBody = template.HTML(markdown.ToHTML([]byte(p.Body), r.mdParser, nil))\n\treturn vm\n}\n"
},
{
"path": "blogrenderer/renderer_test.TestRender.it_converts_a_single_post_into_HTML.approved.txt",
"content": "\n\n\n My amazing blog!\n \n \n\n\n\n\n\n
hello world
\n\n
This is a description
\n\nTags:
go
tdd
\n
First recipe!
\n\n
Welcome to my amazing blog. I am going to write about my family recipes, and make sure I write a long, irrelevant and boring story about my family before you get to the actual instructions.
\n\n\n\n\n\n\n"
},
{
"path": "blogrenderer/renderer_test.go",
"content": "package blogrenderer_test\n\nimport (\n\t\"bytes\"\n\tapprovals \"github.com/approvals/go-approval-tests\"\n\t\"github.com/quii/learn-go-with-tests/blogrenderer\"\n\t\"io\"\n\t\"testing\"\n)\n\nfunc TestRender(t *testing.T) {\n\tvar (\n\t\taPost = blogrenderer.Post{\n\t\t\tTitle: \"hello world\",\n\t\t\tBody: `# First recipe!\nWelcome to my **amazing blog**. I am going to write about my family recipes, and make sure I write a long, irrelevant and boring story about my family before you get to the actual instructions.`,\n\t\t\tDescription: \"This is a description\",\n\t\t\tTags: []string{\"go\", \"tdd\"},\n\t\t}\n\t)\n\n\tpostRenderer, err := blogrenderer.NewPostRenderer()\n\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\n\tt.Run(\"it converts a single post into HTML\", func(t *testing.T) {\n\t\tbuf := bytes.Buffer{}\n\n\t\tif err := postRenderer.Render(&buf, aPost); err != nil {\n\t\t\tt.Fatal(err)\n\t\t}\n\n\t\tapprovals.VerifyString(t, buf.String())\n\t})\n\n\tt.Run(\"it renders an index of posts\", func(t *testing.T) {\n\t\tbuf := bytes.Buffer{}\n\t\tposts := []blogrenderer.Post{{Title: \"Hello World\"}, {Title: \"Hello World 2\"}}\n\n\t\tif err := postRenderer.RenderIndex(&buf, posts); err != nil {\n\t\t\tt.Fatal(err)\n\t\t}\n\n\t\tapprovals.VerifyString(t, buf.String())\n\t})\n}\n\nfunc BenchmarkRender(b *testing.B) {\n\tvar (\n\t\taPost = blogrenderer.Post{\n\t\t\tTitle: \"hello world\",\n\t\t\tBody: \"This is a post\",\n\t\t\tDescription: \"This is a description\",\n\t\t\tTags: []string{\"go\", \"tdd\"},\n\t\t}\n\t)\n\n\tpostRenderer, err := blogrenderer.NewPostRenderer()\n\n\tif err != nil {\n\t\tb.Fatal(err)\n\t}\n\n\tfor b.Loop() {\n\t\tpostRenderer.Render(io.Discard, aPost)\n\t}\n}\n"
},
{
"path": "blogrenderer/templates/blog.gohtml",
"content": "{{template \"top\" .}}\n
![](\"red-green-blue-gophers-smaller.png\")
\n