<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Jolyon Direnko-Smith on Medium]]></title>
        <description><![CDATA[Stories by Jolyon Direnko-Smith on Medium]]></description>
        <link>https://medium.com/@delticsnz?source=rss-0dd174fd7d69------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*dN_cDwZmus_NijQ-SwtqSg.png</url>
            <title>Stories by Jolyon Direnko-Smith on Medium</title>
            <link>https://medium.com/@delticsnz?source=rss-0dd174fd7d69------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 05:46:13 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@delticsnz/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Write Beautiful Tests in Go]]></title>
            <link>https://medium.com/@delticsnz/write-beautiful-tests-in-go-c0a3fa7b084c?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/c0a3fa7b084c</guid>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[go]]></category>
            <category><![CDATA[testing]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Sun, 01 Jun 2025 03:49:28 GMT</pubDate>
            <atom:updated>2025-08-16T00:43:03.329Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gtUa_-49z6gV8qFy6cgS8A.png" /></figure><p>I am pleased to announce the release of a significant update to <a href="https://github.com/blugnu/test">blugnu/test</a> which introduces a new approach for writing Go tests that builds on, and is fully compatible with, the standard library testingpackage.</p><blockquote>This article was updated on 16th August 2025 to reflect changes in the API that introduced a test runners framework with a revised approach to table-driven tests and the introduction of FlakyTest() support.</blockquote><p>The package was first released around 18 months ago, with the modest aim of providing test helpers to reduce the drudgery of writing Go tests. For example, instead of:</p><pre>got := GetResult()<br><br>expected := 42<br>if got != expected {<br>    t.Errorf(&quot;expected %d, got %d&quot;, expected, got)<br>}</pre><p>You could instead use:</p><pre>got := GetResult()<br><br>test.That(t, got).Equals(42)</pre><p>Over time, the number of helpers grew, but I was always unhappy with several aspects of the implementation.</p><ol><li>*testing.T values were still prevalent in tests;</li><li>Type-specific helpers, to promote type-safety of tests, meant an ever-growing number of helper functions, specialised to specific type constraints;</li><li>The package was not extensible without adding to the package itself.</li></ol><p>I always had a feeling that it could be better, so I did not publicise the package. I found it helpful myself, but was acutely aware of its problems.</p><p>I’m happy to say that all of these concerns are addressed in the revised implementation, though unfortunately at the expense of backwards compatibility.</p><p>The previous simple example would now be written as:</p><pre>got := GetResult()<br><br>Expect(got).To(Equal(42)</pre><p>This is still completely type-safe, i.e. the following will not compile:</p><pre>got := len(someSlice)<br><br>Expect(got).To(Equal(&quot;2&quot;))</pre><h4>Where Did the *testing.T Go?</h4><p>A bit of magic is used to eliminate the *testing.T values, or rather to <strong><em>hide</em></strong> them.</p><p>First of all, the package is now intended to be used via a dot-import, removing the need to use the test package name everywhere. This isn’t directly connected to the disappearance of *testing.T , but is similarly aimed at reducing noise in tests.</p><p>Secondly, every test must start with a call to capture the initial *testing.T:</p><pre>func TestGetResult(t *testing.T) {<br>    With(t)<br><br>    ...<br>}</pre><blockquote>A test might also use Parallel(t) to simultaneously capture the t and mark the test for parallel execution.</blockquote><p>The test package maintains a per-goroutine stack of *testing.T values. This may be maintained explicitly if required, calling With again as necessary. So you could run a sub-test by doing this:</p><pre>t.Run(&quot;subtest&quot;, func(st *testing.T) {<br>    With(st)<br><br>    ...<br>})</pre><p>Or, you can instead use the Run() function provided by the blugnu/test package, which will execute a test runner.</p><p>The simplest test runner is Test(), which runs a named subtest:</p><pre>Run(Test(&quot;subtest&quot;, func() {<br>  ...<br>})</pre><p>Other test runners are provided for table-driven tests and flaky tests. In all cases, the runner pushes the <em>new</em> T onto the stack for you automatically when required, so you don’t have to.</p><p>If you stick to using the test package functions for running subtests, you only need to add the initial With(t) to the top of each test to adopt it into the framework.</p><blockquote>If your test code needs the current *testing.T it can be accessed by calling the provided T() function. This returns an interface, providing a subset of *testing.Tmethods; if you need the capabilities of a full *testing.T value, coerce it using T().(*testing.T)</blockquote><h4>Type Safe Tests</h4><p>Type-safety is achieved through the use of generics and constraints.</p><p>Since Go does not support overloading functions (<em>an observation, not a complaint</em>), some specialisation of matcher factory functions is still needed, in some cases.</p><p>For example, slices are not comparable, so this is not legal:</p><pre>slice := []int{1,2}<br>Expect(slice).To(Equal([]int{1,2}))   // ERROR: []int does not satisfy comparable  </pre><p>For comparing slices, an EqualSlice matcher must be used instead:</p><pre>Expect(slice).To(EqualSlice([]int{1,2}))   // this is a valid test</pre><p>Worth noting is that an <strong><em>array</em></strong><em> of int</em> <strong><em>is</em></strong> comparable, so this <strong><em>is</em></strong> a legal and valid test without requiring any specialised matcher:</p><pre>arr := [2]int{1,2}<br>Expect(arr).To(Equal([2]int{1,2}))</pre><h4>Extensible: Custom Matchers</h4><p>To ensure that the framework supports custom matchers as first-class citizens, almost all of the built-in matchers are implemented in separate packages.</p><blockquote>The exceptions are the specialised tests built-in to the Expect() result type itself, such as IsNil(), IsEmpty(), DidOccur(), etc. Any test that involves passing a matcher to To() or ToNot() is technically a custom matcher, there just happen to be a bunch of them provided “in the box”.</blockquote><p>This not only verifies that custom matchers are supported, but also provides useful reference implementations for anyone wishing or needing to extend the framework.</p><p>Furthermore, the implementation of a custom matcher is trivial; a minimal matcher implementation requires only one method:</p><pre>type Matcher[T] interface {<br>   Match(got T, opts ...any) bool<br>}</pre><p>A matcher does not have to be a generic type, but the type of the first argument to the Match() method determines the compatibility of the matcher with Expect() values. A non-generic matcher is constrained to the formal type of the got argument; a generic matcher may be used more flexibly with types that satisfy appropriate constraints.</p><h4>To() vs ToNot()</h4><p>A matcher does not have to implement any specific support for inverse matching. If a matcher does need to perform differently when testing a ToNot() case, it can inspect the options passed to the matcher for the presence of opt.ToNotMatch(true).</p><pre>if opt.IsSet(opts, opt.ToNotMatch(true)) {<br>   ...<br>}</pre><p>This option is set internally by the framework when ToNot() is used with a matcher.</p><p>This is most often needed to adjust the language in a test failure report to be appropriate to the nature of the test, rather than using a vague and possibly ambiguous error report that attempts to cater to both.</p><h4>Match Failure Reports</h4><p>A matcher implementation may provide a test failure report by implementing one of several optional methods, according to the needs of the report. Methods are supported for returning a single string or a slice of strings (for multi-line reports) with or without a got value.</p><p>Alternatively, if the matcher is implemented as a struct type, it may provide an Expected field in that struct. Without any specific failure report implementation, the framework will then use this value to provide a default expected &lt;x&gt;, got &lt;y&gt; type report, which may be all that is needed in some cases.</p><h3>What Else and What Next?</h3><p>I have been using blugnu/test in all my Go projects and will be transitioning them all to this new implementation.</p><p>I would appreciate feedback from anyone interested in using the framework, as well as contributions in the form of ideas or pull requests for new features or documentation. There is a fairly extensive README, but I’d love to create proper documentation, perhaps in the form of GitHub pages, for which some help would be appreciated.</p><p>The framework has 100% test coverage, and <a href="https://sonarcloud.io/summary/overall?id=blugnu%3Atest&amp;branch=master">full SonarCloud analysis is available</a>.</p><p>To whet your appetite, a brief mention of some other features offered by the framework….</p><h4>Testing Tests</h4><p>If you write your own test helpers, it can be difficult to test them. blugnu/test provides a Test() function which runs a test in an isolated test runner, capturing the outcome and output for testing in your tests.</p><p>blugnu/test extensively uses itself to test itself, providing a helpful reference.</p><h4>Table-Driven Tests</h4><p>While it is possible to write traditional Go table-driven tests using this package, a test runner is provided to simplify this.</p><p>Instead of:</p><pre>testcases := []struct{<br>   input: int<br>   expected: int<br>}{<br>   {input: 1, expected: 2}<br>   {input: 2, expected: 4}<br>}<br>for i, tc := range testcases {<br>   t.Run(fmt.Sprintf(&quot;testcase %d&quot;, i), func(t *testing.T) {<br>      result := DoubleIt(tc.input)<br>      if result != tc.expected {<br>         t.Errorf(&quot;expected %d, got %d&quot;, tc.expected, result)<br>      }<br>   })<br>}</pre><p>You can use:</p><pre>With(t)<br><br>type testcase struct {<br>   input    int<br>   expected int<br>}<br>Run(Testcases(<br>   ForEach(func(tc testcase) {<br>      result := DoubleIt(tc.input)<br>      Expect(result).To(Equal(tc.expected))<br>   }),<br>   Case(&quot;input 1&quot;, testcase{input: 1, expected: 2}),<br>   Case(&quot;input 2&quot;, testcase{input: 2, expected: 4}),<br>))</pre><p>This has two main advantages:</p><ol><li>Boilerplate looping code is eliminated</li><li>The test function is given prominence over the test cases</li></ol><p>Testcases returns a table-driven test runner. The first argument to Testcasesprovides the test function to be performed for each test case.</p><p>Where this function is identical for each test case, ForEach is used to supply a function accepting each test case. If the function implements minor variations for specific test cases, For may be used instead, to supply a function accepting the name of each test case in addition to the test case:</p><pre>Run(Testcases(<br>   For(func(tcn string, tc testcase) {<br>      ...<br>   }),<br>   Case(...),<br>   Case(...),<br>))</pre><p>Test cases may be specified individually using the Case function, also specifying the name of each test case explicitly.</p><p>Alternatively, test cases may be added from a slice using Cases:</p><pre>Run(Testcases(<br>   ForEach(func(tc testcase) {<br>      ...<br>   }),<br>   Cases([]testcase{<br>      {input: 1, expected: 2},<br>      {input: 2, expected: 4},<br>   })...<br>))</pre><p>When adding test cases in this way, individual test case names may be provided in the test case struct itself as a field named <strong>Scenario</strong>, <strong>scenario</strong>, <strong>Name</strong> or <strong>name</strong>. If no suitable name field is provided, a default, unique name is generated using the index of each test case in the overall set of test cases.</p><h4>Other Test Runners</h4><p>Additional test runners are provided.</p><p>ParallelTest() is similar to Test but runs a subtest as a parallel test, as an alternative to using Run(Test())and calling Parallel() in the subtest function.</p><p>FlakyTest() is also similar to Test but is used for tests which may occasionally fail due to sensitive timing issues or other reasons. The FlakyTest runner will perform a test repeatedly until it passes, subject to a maximum number of attempts or a time limit.</p><p>HelperTests() is used to run a table-driven test that exercises a test helper function, with a predefined test case struct.</p><p>Again, use the source as a reference, since this is used throughout to test the blugnu/test framework itself.</p><h4>Testing Errors</h4><p>Testing for errors can be done in several ways.</p><p>To test that an error did (or did not) occur without caring about the specific error (not recommended), you can use these tests:</p><pre>Expect(err).DidOccur()    // ensure that an error occurred (any error)<br>Expect(err).DidNotOccur() // ensure that no error occurred<br>Expect(err).IsNil()       // ensure that no error occurred <br>Expect(err).IsNotNil()    // ensure that an error occurred (any error)</pre><p>For a more specific test (recommended), you can use :</p><pre>Expect(err).Is(expected)   // passes if errors.Is(err, expected) is true</pre><p>If expected is nil then this is equivalent to an IsNil() test, which can be useful in a table-driven test where each test case may have an expected error or none.</p><h4>Testing Panics</h4><p>The DidOccur/DidNotOccur tests may also be used to test for panics. In this case, the test must be deferred and the value that is expected to be recovered is determined by calling the provided Panic function:</p><pre>defer Expect(Panic(r)).DidOccur()<br><br>... code which is expected to panic and provide &#39;r&#39; to be recovered</pre><p>If the value recovered from the panic is not significant (i.e. the test is simply that some panic occurred, regardless of recovered value), use:</p><pre>defer Expect(Panic()).DidOccur()</pre><h4>NilPanic() vs Panic(nil)</h4><p>Prior to go 1.21 a panic(nil)was indistinguishable from no panic occurring, since it would provide nil as the value to be recovered. From go 1.21 onward, a panic(nil) now provides a specific error when recovered.</p><p>As a result, and to simplify table-driven tests as for testing errors, Panic(nil) is a special case, equivalent to no panic . That is, these two tests are equivalent:</p><pre>/* either */ defer Expect(Panic()).DidNotOccur()<br>/* or     */ defer Expect(Panic(nil)).DidOccur()</pre><p>In the unlikely event that you need to test specifically for a panic(nil) occurring, you can use either of the following:</p><pre>/* either */ defer Expect(NilPanic()).DidOccur()<br>/* or     */ defer Expect(Panic(&amp;runtime.PanicNilError{}).DidOccur()</pre><blockquote>NOTE: Panic testing relies on the recover()mechanism and multiple deferred calls which recover will not function correctly. As a result, there must be only ONE deferred panic test in a function, and no other recover calls.</blockquote><h3>And More…</h3><p>This is more functionality provided by the framework than can be covered in a single article such as this, including:</p><ul><li>Emptiness checks, supporting any len() compatible type and types that implement a Count(), Len(), or Length() method</li><li>Map Key/Value helpers</li><li>Context Key/Value matchers</li><li>Slice equality with/without order significance</li><li>Function timer</li><li>Mocking toolkit (not an extensive mocking framework, but a type to simplify the explicit implementation of simple mocks)</li></ul><h3>In Conclusion</h3><p>I hope this introduction has piqued your interest.</p><p>The more people use this framework, the better it will hopefully get, and I look forward to seeing issues and PR’s coming in soon!</p><p>Please let me know what you think in the comments below.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c0a3fa7b084c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[GoLang Test Output as Markdown]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://medium.com/@delticsnz/golang-test-output-as-markdown-653c624f2a33?source=rss-0dd174fd7d69------2"><img src="https://cdn-images-1.medium.com/max/1800/1*ZPXelFc6xOuON9_06GaS_Q.png" width="1800"></a></p><p class="medium-feed-snippet">Some time ago, I created a tool to transform JSON output from go test into Github Flavor Markdown, enabling test reports to be&#x2026;</p><p class="medium-feed-link"><a href="https://medium.com/@delticsnz/golang-test-output-as-markdown-653c624f2a33?source=rss-0dd174fd7d69------2">Continue reading on Medium »</a></p></div>]]></description>
            <link>https://medium.com/@delticsnz/golang-test-output-as-markdown-653c624f2a33?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/653c624f2a33</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[ci-cd-pipeline]]></category>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[github]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Mon, 18 Nov 2024 06:23:58 GMT</pubDate>
            <atom:updated>2024-11-18T06:23:58.340Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[100% Is The Only Meaningful Test Coverage Target; Hear Me out]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://medium.com/@delticsnz/100-is-the-only-meaningful-test-coverage-target-hear-me-out-6aa8e5416428?source=rss-0dd174fd7d69------2"><img src="https://cdn-images-1.medium.com/max/1019/1*hg8uhjUQ0ols1_HTWDCAsw.jpeg" width="1019"></a></p><p class="medium-feed-snippet">It is a truth, universally acknowledged, that code coverage metrics say nothing about the quality of the tests.</p><p class="medium-feed-link"><a href="https://medium.com/@delticsnz/100-is-the-only-meaningful-test-coverage-target-hear-me-out-6aa8e5416428?source=rss-0dd174fd7d69------2">Continue reading on Medium »</a></p></div>]]></description>
            <link>https://medium.com/@delticsnz/100-is-the-only-meaningful-test-coverage-target-hear-me-out-6aa8e5416428?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/6aa8e5416428</guid>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[unit-testing]]></category>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-testing]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Tue, 12 Nov 2024 17:40:25 GMT</pubDate>
            <atom:updated>2024-11-12T20:52:41.433Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[Mutexes in GoLang Are Different]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://medium.com/@delticsnz/mutexes-in-golang-are-different-d1fd5a8793bb?source=rss-0dd174fd7d69------2"><img src="https://cdn-images-1.medium.com/max/1258/1*Zu10CRLsR74-TDpAjDIaVw.png" width="1258"></a></p><p class="medium-feed-snippet">The GoLang&apos;s Mutex type works in a way that may surprise engineers familiar with mutexes in other languages.</p><p class="medium-feed-link"><a href="https://medium.com/@delticsnz/mutexes-in-golang-are-different-d1fd5a8793bb?source=rss-0dd174fd7d69------2">Continue reading on Medium »</a></p></div>]]></description>
            <link>https://medium.com/@delticsnz/mutexes-in-golang-are-different-d1fd5a8793bb?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/d1fd5a8793bb</guid>
            <category><![CDATA[concurrency]]></category>
            <category><![CDATA[mutex]]></category>
            <category><![CDATA[golang]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Thu, 12 Sep 2024 09:09:18 GMT</pubDate>
            <atom:updated>2024-09-12T09:09:18.751Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[AI Code Reviews with CodeRabbit]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://medium.com/@delticsnz/ai-code-reviews-with-coderabbit-86d240db5793?source=rss-0dd174fd7d69------2"><img src="https://cdn-images-1.medium.com/max/2058/1*60zPd-RtsjGw17CGBuMQoQ.png" width="2058"></a></p><p class="medium-feed-snippet">An overview and initial impressions of the CodeRabbit AI PR Review-bot</p><p class="medium-feed-link"><a href="https://medium.com/@delticsnz/ai-code-reviews-with-coderabbit-86d240db5793?source=rss-0dd174fd7d69------2">Continue reading on Medium »</a></p></div>]]></description>
            <link>https://medium.com/@delticsnz/ai-code-reviews-with-coderabbit-86d240db5793?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/86d240db5793</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[code-review]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Wed, 19 Jun 2024 07:41:18 GMT</pubDate>
            <atom:updated>2024-06-19T07:41:18.457Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[Error Handling in Go: Custom Error Types]]></title>
            <link>https://blog.stackademic.com/error-handling-in-go-custom-error-types-072d22465a15?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/072d22465a15</guid>
            <category><![CDATA[go]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Fri, 10 Nov 2023 03:48:20 GMT</pubDate>
            <atom:updated>2023-11-10T04:50:07.857Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/878/1*bpjTZn51eFiSJBMR540UMw.png" /></figure><p>In previous articles in this series, we have covered <a href="https://medium.com/@delticsnz/error-handling-in-go-beyond-the-basics-e5b90d1d7be1">the fundamentals of error handling in Go</a> and looked at how we can <a href="https://medium.com/@delticsnz/error-handling-in-go-first-steps-with-wrapping-3a6952a00cd4">use wrapping to provide additional context to an error, or “tag” some arbitrary error with a sentinel</a> to enable us to test error handling while avoiding coupling tests to implementation details.</p><p>But what if we want or need to provide more information in an <strong>error</strong> than can be conveyed in the <strong>Error()</strong> string alone, or need to perform more nuanced comparisons when evaluating errors, particularly in tests?</p><p>This <strong><em>may</em></strong> be the time to implement your own <strong>error</strong> <em>type</em>.</p><p>But beware…</p><h3>Custom Errors vs Custom Error Types</h3><p>We’ve already seen how simple errors can be declared in the form of sentinels using <strong>errors.New()</strong>, and how we can construct errors with potentially complex messages using <strong>fmt.Errorsf()</strong>.</p><p>How is this different from a custom <em>type</em>?</p><p>First, it might be useful to examine exactly what <strong>errors.New()</strong> and <strong>fmt.Errorsf()</strong> give us, which is illustrated in <a href="https://go.dev/play/p/F3dM-quf-ac">this simple playground</a>:</p><pre>package main<br><br>import (<br>   &quot;errors&quot;<br>   &quot;fmt&quot;<br>)<br><br>func main() {<br>   fmt.Printf(&quot;errors.New()      : %T\n&quot;, errors.New(&quot;sentinel&quot;))<br>   fmt.Printf(&quot;fmt.Errorf(%%s)    : %T\n&quot;, fmt.Errorf(&quot;%s&quot;, &quot;sentinel&quot;))<br>   fmt.Printf(&quot;fmt.Errorf(%%w:%%s) : %T\n&quot;, fmt.Errorf(&quot;%w: %s&quot;, errors.New(&quot;wrapped error&quot;), &quot;message&quot;))<br>   fmt.Printf(&quot;fmt.Errorf(%%w:%%w) : %T\n&quot;, fmt.Errorf(&quot;%w: %w&quot;, errors.New(&quot;wrapped&quot;), errors.New(&quot;error&quot;)))<br>}</pre><p>The <strong>%T</strong> format specification yields the <em>type</em> of the argument, rather than its value, allowing us to see that <strong>fmt.Errorf()</strong> returns a value of a different type, depending on how it is used:</p><pre>errors.New()      : *errors.errorString<br>fmt.Errorf(%s)    : *errors.errorString<br>fmt.Errorf(%w:%s) : *fmt.wrapError<br>fmt.Errorf(%w:%w) : *fmt.wrapErrors</pre><p>As we covered in the <a href="https://medium.com/@delticsnz/error-handling-in-go-beyond-the-basics-e5b90d1d7be1">very first instalment</a>, the <strong>error</strong> type itself is an interface, requiring the implementation of a single method:</p><pre>type error interface {<br>   Error() string<br>}</pre><p>Just as <strong>fmt.Errorf()</strong> is supported by different types, all implementing the <strong>error</strong> interface to meet different needs, we can implement this function on our own types and instantly make them available for use as an <strong>error</strong>.</p><blockquote>We’ll come back to why <strong>fmt.Errorf()</strong> returns a variety of types shortly.</blockquote><p>We might do this when we need more structured information in an error so that we do not have to test the contents of the <strong>Error() string</strong> result in tests (or, worse, in production error handling code).</p><p>One example comes from a real-world scenario in the configuration code of microservices that I have worked on.</p><p>Before implementing a new error type though, we will first look at what an implementation might look like if relying only on what we’ve covered so far.</p><h3>Wrapping with a String</h3><p>The example we will be considering is a simplified version of a function that loads values from the environment to be stored in variables.</p><blockquote>This is not a complete reproduction of the original use case, being reduced and simplified to provide an illustration of the points relevant to error handling.</blockquote><pre>var (<br>  DB_HOSTNAME string<br>  DB_HOSTNAME_STANDBY string<br><br>  ErrEnvironmentVariableNotSet = errors.New(&quot;env var not set&quot;)<br>)<br><br>func Load() error {<br>   errs := []error{}<br>   errs = append(errs, loadvar(&quot;DB_HOSTNAME&quot;, &amp;DB_HOSTNAME))<br>   errs = append(errs, loadvar(&quot;DB_HOSTNAME_STANDBY&quot;, &amp;DB_HOSTNAME_STANDBY)<br>   return errors.Join(errs...)<br>}<br><br>func loadvar(nm string, va *string) error {<br>   if v, ok := os.LookupEnv(nm); ok {<br>      *va = v<br>      return nil<br>   }<br>   return fmt.Errorf(&quot;%w: %s&quot;, ErrEnvironmentVariableNotSet, nm)<br>}</pre><p>This is not too bad.</p><p>If any environment variables are not set, an error is returned from the <strong>Load()</strong> function which wraps <em>all</em> of the errors identifying the missing configuration values. If we deploy a misconfigured service, the logs will tell us <em>all</em> the variables we forgot so we can fix them all for the next deployment.</p><p>But how can we write a test for the <strong>Load()</strong> function?</p><p>It is easy enough to test that the returned <strong>error</strong> <strong>Is()</strong> an <strong>ErrEnvironmentVariableNotSet</strong>:</p><pre>if !errors.Is(got, ErrEnvironmentVariableNotSet) {<br>   t.Errorf(&quot;\nwanted : %v\ngot    : %v\n&quot;, ErrEnvironmentVariableNotSet, got)<br>}</pre><p>To test that <em>each required environment variable has been identified as missing</em> is problematic.</p><p>We would need to unwrap the errors and range over them performing a string <em>contains</em> or <em>suffix</em> test to identify which variables were reported as missing compared with the ones we were expecting, coupling the test very tightly to the specific mechanics of the error implementation, embedding knowledge of the structure (the wrapping) and formatting of each error.</p><p>This might result in something similar to:</p><pre>func TestLoad(t *testing.T) {<br>   got := Load()<br><br>   if err, ok := got.(interface{ Unwrap() []error }); ok {<br>      vars := map[string]bool{<br>         &quot;DB_HOSTNAME&quot;:         false,<br>         &quot;DB_HOSTNAME_STANDBY&quot;: false,<br>      }<br>      for _, got := range err.Unwrap() {<br>         if !errors.Is(got, ErrEnvironmentVariableNotSet) {<br>            t.Errorf(&quot;\nwanted : %v\ngot    : %v\n&quot;, ErrEnvironmentVariableNotSet, got)<br>         }<br><br>         s := got.Error()<br>         for v, _ := range vars {<br>            if strings.Contains(s, v) {<br>               delete(vars, v)<br>            }<br>         }<br>       }<br><br>       if len(vars) &gt; 0 {<br>          t.Errorf(&quot;failed to identify missing variables: %v&quot;, vars)<br>       }<br>    }<br>}</pre><p>Not only is this ugly such tests would be <em>very</em> fragile.</p><p>Using the <em>contains</em> test, if a test for <strong>DB_HOSTNAME</strong> might report a false negative when <strong>DB_HOSTNAME_STANDBY</strong> is not set, given that <strong>DB_HOSTNAME</strong> is contained in <strong>DB_HOSTNAME_STANDBY</strong>.</p><p>To avoid that we might use a <em>suffix</em> test instead, in which case the test would break if it was decided in the future to refactor the error formatting as “<em>&lt;name&gt; variable not set</em>”, necessitating a <em>prefix</em> test, rather than suffix.</p><blockquote>If you want to explore this example further it is <a href="https://go.dev/play/p/Pl_wBAfJ_hI">available in this playground</a>. Note that the playground includes a slight modification to the test to deliberately trigger an illustrative test failure.</blockquote><p>To avoid these problems, we need (among other things) a mechanism for the error to provide the specific name of the variable that the error relates to, independent of and more reliably than relying on the formatting of the <strong>Error()</strong> string.</p><p>This is one of the things that a custom error type allows us to do.</p><h3>A Custom Error Type!</h3><p>There are two requirements we need to satisfy with a customer error type, one imposed by Go, the other stemming from our particular needs in this case:</p><ol><li>Go requires that, to be used as an <strong>error</strong>, a type must implement an <strong>Error() string</strong> function; and</li><li>we need an error that signifies a particular error condition, reliably identifying a variable name to which it relates. (<em>you could argue this is two requirements</em>)</li></ol><p>Whether you consider this 2, or 3 requirements, they are all met by declaring a type similar to:</p><pre>type VariableNotSetError struct {<br>   V string<br>}<br><br>func (err VariableNotSetError) Error() string {<br>   return fmt.Sprintf(&quot;env var not set: %s&quot;, err.V)<br>}</pre><p>The <strong>VariableNotSetError</strong> struct implements the <strong>Error() string</strong> function, enabling a value of this type to be used as an <strong>error</strong>.</p><blockquote>By convention in Go, error types are named with an <strong>Error</strong> suffix. We have already seen the naming convention for sentinel errors: an <strong>Err</strong> <strong>prefix</strong>.</blockquote><p>The string returned by the <strong>VariableNotSetError.Error()</strong> function replicates the formatting of the previous wrapped sentinel approach, but the name of the variable involved is also now held as a separate field (<strong>V</strong>) on the error itself.</p><p>Modifying the <strong>loadvar()</strong> function in our illustration to return this error instead of the wrapped sentinel is very simple. The <strong>Load()</strong> function is not affected:</p><pre>func loadvar(nm string, va *string) error {<br>   if v, ok := os.Lookupenv(nm); ok {<br>      *va = v<br>      return nil<br>   }<br>   return VariableNotSetError{nm}<br>}</pre><p>And we can clean up our test <em>significantly</em>:</p><pre>func TestLoad(t *testing.T) {<br>   got := Load()<br><br>   if !errors.Is(got, VariableNotSetError{&quot;DB_HOSTNAME&quot;}) {<br>      t.Errorf(&quot;\nwanted : %v\ngot    : %v\n&quot;, VariableNotSetError{&quot;DB_HOSTNAME&quot;}, got)<br>   }<br>   if !errors.Is(got, VariableNotSetError{&quot;DB_HOSTNAME_STANDBY&quot;}) {<br>      t.Errorf(&quot;\nwanted : %v\ngot    : %v\n&quot;, VariableNotSetError{&quot;DB_HOSTNAME_STANDBY&quot;}, got)<br>   }<br>}</pre><p>Our test is no longer coupled to the precise mechanism by which the errors of interest are organised within the returned error. There is also no longer any dependency on how the errors present themselves as strings.</p><blockquote>Again, if you wish to explore, <a href="https://go.dev/play/p/9PQn-pVShQa">there’s a playground for this too</a>.</blockquote><p>But what if we have a situation where we don’t care about which specific variable was set, and are only concerned that <em>some</em> variable (or variables) were not set?</p><blockquote>This is a somewhat artificial requirement in this case but is useful as an illustration, so play along…</blockquote><p>If we modify our test to simply check that the error is a <strong>VariableNotSetError</strong> we run into a problem:</p><pre>func TestLoad(t *testing.T) {<br>   got := Load()<br><br>   if !errors.Is(got, VariableNotSetError{}) {<br>      t.Errorf(&quot;\nwanted : %T\ngot    : \n%T\n&quot;, VariableNotSetError{}, got)<br>   }<br>}</pre><blockquote>Notice that now that the test is concerned with the error <strong>type</strong> rather than a specific <strong>value</strong>, the <strong>t.Errorf()</strong> report now uses <strong>%T</strong> to report type information.</blockquote><p>Ignoring the fact that this test does not provide complete coverage (<em>regardless of what the line coverage metric might suggest</em>), the problem we are concerned with here is that <strong><em>this test now fails</em></strong>.</p><p>The error definitely contains the same errors as before. Why does <strong>errors.Is()</strong> no longer think that it does?</p><p>There are two different ways we can tackle this problem.</p><p>First, there is an alternative to <strong>errors.Is()</strong> that will work in this case. <strong>errors.As()</strong>.</p><h3>errors.As()</h3><p>Where <strong>errors.Is()</strong> checks to see if an <strong>error</strong> (or an <strong>error</strong> that it wraps) may be considered equal to some other <strong>error</strong>, <strong>errors.As()</strong> is concerned with whether an <strong>error</strong> (or an <strong>error</strong> that it wraps) is of a particular <em>type</em>.</p><p>Better yet, if <strong>errors.As()</strong> <em>does</em> find an error of the required type, it will copy it into a variable of the required type. The variable provides the destination to receive any matching error and also dictates the type that the matching error must be.</p><p>We can refine our test to use this as follows:</p><pre>func TestLoad(t *testing.T) {<br>   got := Load()<br><br>   wanted := VariableNotSetError{} <br>   if !errors.Is(got, &amp;wanted) {<br>      t.Errorf(&quot;\nwanted : %T\ngot    : \n%T\n&quot;, wanted, got)<br>   }<br>}</pre><p>Our test once again passes. Great!</p><p>But in a more complicated scenario, we may be faced with an <strong>error</strong> that has <em>multiple</em> fields and may have a test that depends on some, but not all of them.</p><p><strong>errors.As()</strong> places a copy of the error it found in our target variable, so we could examine it for certain values; but this will be only the <em>first</em> <strong>error</strong> that was found of the required type. If there are <em>multiple</em> errors, this may not be the one we are interested in; <strong>errors.As()</strong> does not provide a way to find <em>all</em> matches.</p><p>We can use a different approach which solves this problem using <strong>errors.Is()</strong>.</p><h3>Changing What Is() Means</h3><p>When you call <strong>errors.Is()</strong> the first thing it does it test whether the two errors it is given are comparable and, if they are, compare them for equality.</p><blockquote>This is not quite the first thing. The <strong>very</strong> first thing it checks is whether they are are both <strong>nil</strong>.</blockquote><p>If they are not <strong>nil</strong> and not equal, the next thing <strong>errors.Is()</strong> then does is check the error being tested to see if it implements an interface that provides an <strong>Is(error) bool</strong> function. If it does then this is called, and if that returns <strong>true</strong> then the two errors are considered a match:</p><pre>  if x, ok := err.(interface{ Is(error) bool }); ok &amp;&amp; x.Is(target) {<br>   return true<br>  }</pre><blockquote>from <a href="https://cs.opensource.google/go/go/+/refs/tags/go1.21.4:src/errors/wrap.go">wrap.go in the source of the errors package</a></blockquote><p>Only if this function returns <strong>false</strong> (<em>or is not implemented</em>) does <strong>errors.Is()</strong> proceed to test any wrapped errors.</p><p>This means that we can implement an <strong>Is(error) bool</strong> function for <strong>VariableNotSetError</strong> to give the behaviour we would like.</p><p>In this case, we would like <strong>errors.Is()</strong> to consider a <strong>VariableNotSetError</strong> with no variable name to be a match for <em>any</em> <strong>VariableNotSetError</strong>, which might look similar to this:</p><pre>func (err VariableNotSetError) Is(target error) bool {<br>   if target, ok := target.(VariableNotSetError); ok {<br>      return target.V == &quot;&quot; || target.V == err.V<br>   }<br>   return false<br>}</pre><p>This simple function creates a <strong>target</strong> variable of type <strong>VariableNotSetError</strong> which will only be non-<strong>nil</strong> if the original <strong>target error</strong> is of that type.</p><blockquote>The example shadows the original <strong>target</strong>, but that’s fine and actually desirable in this case, signalling that if the value is successfully coerced to the required type the original parameter is no longer of interest.</blockquote><p>If the <strong>target</strong> is a <strong>VariableNotSetError</strong> we then return <strong>true</strong> if the <strong>target</strong> either has <em>no variable name set</em> <strong>or</strong> <em>has a variable name that equals the receiver variable name</em>.</p><p>With this in place, we can revert our test to the use of <strong>errors.Is()</strong> and it will now pass:</p><pre>func TestLoad(t *testing.T) {<br>   got := Load()<br><br>   if !errors.Is(got, VariableNotSetError{}) {<br>      t.Errorf(&quot;\nwanted : %T\ngot    : \n%T\n&quot;, VariableNotSetError{}, got)<br>   }<br>}</pre><blockquote><a href="https://go.dev/play/p/C1N4gIxEAer">Playground here</a>.</blockquote><p>This is not to say that <strong>errors.As()</strong> does not have valid uses in other situations, and understanding how that works should inform when it may be appropriate.</p><h3>Wrapping Up</h3><p>This is not the first time that we have seen how we can extend the capabilities of a custom error type by implementing specific, optional functions.</p><p>In <a href="https://medium.com/@delticsnz/error-handling-in-go-first-steps-with-wrapping-3a6952a00cd4">the previous article</a> we saw that when <strong>errors.Is()</strong> does not find a match between two errors, it tests to see whether there may be any wrapped errors by testing for the presence of either one of two different forms of an <strong>Unwrap()</strong> function:</p><pre>switch x := err.(type) {<br>case interface{ Unwrap() error }:<br>   err = x.Unwrap()<br>   if err == nil {<br>      return false<br>   }<br>case interface{ Unwrap() []error }:<br>   for _, err := range x.Unwrap() {<br>      if Is(err, target) {<br>         return true<br>      }<br>   }<br>   return false<br>}</pre><p>It follows of course, that as well as wrapping errors using <strong>fmt.Errorf(%w)</strong> or <strong>errors.Join()</strong>, we can also wrap errors <em>within a custom error type of our own</em>.</p><p>All that is required for that is to implement an error type that has some means of storing the wrapped error (or errors) and implements either one of the two variants of the <strong>Unwrap()</strong> function that the functions in the errors package work with. It is not possible for a single type to implement <em>both</em>, since Go does not support function overloads.</p><blockquote>This is why, as we saw right at the start of this article, <strong>fmt.Errorf()</strong> returns values of <em>different types</em>, depending on whether it is used to wrap 0, 1 or 2 (or more) errors.</blockquote><h3>Keep Calm and Wrap</h3><p>Once it has been realised that creating custom errors is both possible and easy, it can be tempting to go mad, creating custom errors for all sorts of different scenarios.</p><p>It is seductive as it feels <em>very</em> productive and who could ever say that catering for good error handling is not useful work, right?</p><p>But the shine will quickly fade as the tedium of writing tests for your custom errors grows and you review code that never takes advantage of the rich error handling capabilities so carefully crafted… because they aren’t actually needed.</p><p>Which is the time to move on to the next stage of error handling maturity with the realisation that many, if not the vast majority, of cases can be more than adequately handled with a sentinel and a <strong>fmt.Errorf(%w: %w) </strong>or similarly rich formatting.</p><p>Consider this example:</p><pre>return fmt.Errorf(&quot;Encoder: %d: %w: %d..%d&quot;, i, ErrValueOutOfRange, min, max)</pre><p>Previously I might have have created (and in one early project <strong><em>did</em></strong> create) an <strong>OutOfRangeError</strong>, with fields for the value that was out of range and the upper and lower bounds, necessitating an <strong>Error()</strong> function, an <strong>Is()</strong> function that optionally compared value and/or the bounds and tests for both covering a range of scenarios, none of which turned out to be of much use (i.e. no use at all) in actual, production error handling scenarios.</p><p>It felt <em>really</em> useful at the time, but the <strong>fmt.Errorf()</strong> approach is simpler, requiring only that the function returning it have test coverage (which it needs anyway, in addition to coverage of any custom errors).</p><p>The important signal in the error is carried by the <strong>ErrValueOutOfRange</strong> sentinel. The rest is noise (to production error handling code, though it may be useful in logs, hence retaining it in the error string).</p><p>Keep those complex custom error types in your back pocket, for only when you really, <em>really</em> need them.</p><h3>Conclusion</h3><p>This has been something of a whistle-stop tour of error handling in go, introducing a lot of ideas and techniques.</p><p>As I mentioned, in <a href="https://medium.com/@delticsnz/error-handling-in-go-beyond-the-basics-e5b90d1d7be1">the first article in this series</a>, when I first started working with Go error handling was something I hated, <em>vehemently</em>. But it quickly became one of my favorite aspects of working with the language.</p><p>It is an area that illustrates how things may be kept simple while still providing great flexibility. The additions and extensions in this area that have been added to the standard library over the years have demonstrated how the language can develop whilst preserving <a href="https://thenewstack.io/how-golang-evolves-without-breaking-programs/">the “no breaking changes” ethos that guides the Go team</a>.</p><p>In addition, it has been by exploring and developing my own error handling and testing practices and striving to understand the mechanisms that enable functions such as <strong>errors.Is()</strong> and <strong>errors.Unwrap()</strong> to work, that I have discovered the power of anonymous interfaces, providing a step-change in the sophistication of the Go code I am comfortable working with.</p><p>I hope there has been something in these articles to provide a similar experience for you.</p><h3>Stackademic</h3><p><em>Thank you for reading until the end. Before you go:</em></p><ul><li><em>Please consider </em><strong><em>clapping</em></strong><em> and </em><strong><em>following</em></strong><em> the writer! 👏</em></li><li><em>Follow us on </em><a href="https://twitter.com/stackademichq"><strong><em>Twitter(X)</em></strong></a><em>, </em><a href="https://www.linkedin.com/company/stackademic"><strong><em>LinkedIn</em></strong></a><em>, and </em><a href="https://www.youtube.com/c/stackademic"><strong><em>YouTube</em></strong></a><strong><em>.</em></strong></li><li><em>Visit </em><a href="http://stackademic.com/"><strong><em>Stackademic.com</em></strong></a><em> to find out more about how we are democratizing free programming education around the world.</em></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=072d22465a15" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/error-handling-in-go-custom-error-types-072d22465a15">Error Handling in Go: Custom Error Types</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Error Handling in Go: First Steps with Wrapping]]></title>
            <link>https://blog.stackademic.com/error-handling-in-go-first-steps-with-wrapping-3a6952a00cd4?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/3a6952a00cd4</guid>
            <category><![CDATA[golang-tutorial]]></category>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[go]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Wed, 01 Nov 2023 07:33:20 GMT</pubDate>
            <atom:updated>2023-11-10T04:49:55.152Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/878/1*bpjTZn51eFiSJBMR540UMw.png" /></figure><p>In <a href="https://medium.com/@delticsnz/error-handling-in-go-beyond-the-basics-e5b90d1d7be1">the first instalment of this series</a>, we looked at the fundamentals of error handling in Go.</p><p>We identified that an <strong>error</strong> is any type that implements an <strong>Error()</strong> function that returns a <strong>string</strong> to describe the <strong>error</strong> and discovered that we could use sentinels to identify conditions that may need special handling.</p><p>We identified the error handling patterns of returning errors from functions and checking any <strong>error</strong> returned by functions we may call, and we saw that it is quite common for a function that receives an error from a function it calls, to return that error back up the call stack.</p><p>But in more complex scenarios it is often helpful to have some idea of <em>where</em> an error occurred; if an error is returned by a function, did the error occur in <em>that function</em> or in some other function that was called?</p><p>When all we have is a string to describe an error, how can we get this information?</p><p>One answer is ‘wrapping’.</p><h3>Illustrating the Problem</h3><p>Returning to our <strong>Calc()</strong> / <strong>Remainder()</strong> illustration, let’s simplify the <strong>Calc()</strong> function to remove any special handling for any errors and just return them back up the call stack:</p><pre>func Calc() error {<br>   // .. some processing that produce a numerator (n) and divisor (d) from<br>   // which we need a remainder (r)<br><br>   r, err := Remainder(n, d)<br>   if err != nil {<br>      return err<br>   }<br>   <br>   // .. proceed with the calculation, which at some later point passes r<br>   // to a function which will use it as a divisor and therefore also guards<br>   // against division by zero panics ...<br><br>   m, err := WeightedAvg(foo, r)<br>   if err != nil {<br>      return err  // could be ErrDivisionByZero<br>   }<br>}</pre><p>This highlights the problem with simply passing errors back up the call stack: a caller that receives an <strong>error</strong> result may know <em>what</em> went wrong, but not necessarily <em>where</em> it went wrong or <em>why:</em></p><pre>// month end calculations<br>func main() {<br><br>   // .. load some data from some files/db/etc on which calculations will<br>   // be performed<br><br>   if err := Calc(); err != nil {<br>      log.Fatal(err)<br>   }<br><br>   // .. send results of successful calculation to data lake (e.g.)<br>} <br></pre><p>If this process terminates with a final log entry of “<em>division by zero</em>”, there is no way to determine whether that was due to a zero-divisor passed to the <strong>Remainder()</strong> function, or because the remainder result was itself zero, which was then passed to the <strong>WeightedAvg()</strong> function by <strong>Calc()</strong>.</p><p>This business of passing received errors up to callers is essentially the Go equivalent [in languages that use exceptions for errors] of re-throwing (or not handling) an exception. A key difference however is that with exceptions you typically have access to stack information to provide some “point of origin” for the exception.</p><h3>Call Stacks and Errors</h3><p>Stack information is not available for an <strong>error</strong> in Go and if you <em>really</em> need it then what you have is not an <strong>error</strong> but a <strong>panic</strong>. Stack information <em>is</em> available for a <strong>panic</strong>, which — unlike errors — are the equivalent in Go to an exception. Which leads us to a key insight:</p><blockquote>a <strong>panic</strong> is an error condition, but a panic is not an <strong>error</strong>; the two different things are represented and handled very differently.</blockquote><p>For an <strong>error</strong>, any “point of origin” information has to be conveyed in the one piece of information that an error <em>can</em> provide about itself: the <strong>string</strong> result of its <strong>Error()</strong> function.</p><p>But we need to <em>add</em> some information to an existing <strong>error</strong>, to indicate where it occurred. How can the result of a function be manipulated without altering the value on which that function is called?</p><p>The simple answer is: <em>It can’t</em>. What we <em>can</em> do is create a <em>new</em> <strong>error</strong> which adds the information we want.</p><p>This starts where we return <strong>ErrDivisionByZero</strong> itself, for example in the <strong>Remainder()</strong> function. But before we go modifying that function again, let’s take a look at a unit test for the <strong>Remainder()</strong> function, covering the division by zero case:</p><pre>func TestRemainderWhenDivisorIsZero(t *testing.T) {<br>   r, err := Remainder(1, 0)<br><br>   if r != -1 {<br>      t.Errorf(&quot;wanted result -1, got %d&quot;, r)<br>   }<br><br>   if err != ErrDivisionByZero {<br>      t.Errorf(&quot;wanted err ErrDivisionByZero, got %s&quot;, err)<br>   }<br>}</pre><p>With this in place, let’s see if we can add some point of origin information to the error.</p><p>A first attempt might look similar to this:</p><pre>func Remainder(n, d int) (int, error) {<br>   if d == 0 {<br>      return -1, errors.New(fmt.Sprintf(&quot;Remainder: %s&quot;, ErrDivisionByZero))<br>   }<br>   return n%d, nil<br>}</pre><p>It does the job, adding the fact that the error occurred in the <strong>Remainder()</strong> function to the string of the <strong>ErrDivisionByZero</strong> error. Unfortunately, this breaks our test and, by extension, will break any code that calls <strong>Remainder()</strong> and then checks for the<strong>ErrDivisionByZero</strong> sentinel.</p><p>The reason is quite simple: as we saw previously, every error returned by <strong>errors.New()</strong> is a unique <strong>error</strong>, even if it has the same string as another.</p><p><strong>Remainder()</strong> is now returning an entirely <em>new</em> <strong>error</strong> which happens to incorporate the string representation of <strong>ErrDivisionByZero</strong> but has no other relationship to it. Hence the <strong>err != ErrDivisionByZero</strong> test is now failing.</p><p>There are a couple of things we need to do to address this.</p><p>But first, let’s clean up that ugly <strong>errors.New(fmt.Sprintf())</strong> combination.</p><h3>errors.New() and fmt.Errorf()</h3><p>When someone first encounters <strong>errors.New()</strong>, often they are frustrated at the lack of an <strong>errors.Newf()</strong>. That is, until they also discover <strong>fmt.Errorf()</strong>.</p><p>This function supports all the formatting options of <strong>fmt.Sprintf()</strong> but returns an <strong>error</strong> rather than a <strong>string</strong>. Using this, we can simplify our <strong>Remainder()</strong> function a little:</p><pre>return -1, fmt.Errorf(&quot;Remainder: %s&quot;, ErrDivisionByZero)</pre><p>This is a lot cleaner than the <strong>errors.New()</strong> / <strong>fmt.Sprintf()</strong> combination, but the unit test is still failing, and this should not be surprising. We’ve tightened up the code, but it is still returning a <em>new</em> <strong>error</strong> unconnected to the <strong>ErrDivisionByZero</strong> error.</p><p>Worth mentioning at this stage is that <strong>fmt.Errorf()</strong> returns unique errors, just like <strong>errors.New()</strong>, even if the resulting formatted string is the same, as demonstrated <a href="https://go.dev/play/p/TI31yRE8B-u">in this playground</a>:</p><pre>func main() {<br>   a := fmt.Errorf(&quot;%s&quot;, &quot;error&quot;)<br>   b := fmt.Errorf(&quot;%s&quot;, &quot;error&quot;)<br><br>   fmt.Printf(&quot;a == b: %v\n&quot;, a == b) // prints: false<br>}</pre><p>So how can we return a new <strong>error</strong> that describes where the division by zero occurred <strong><em>and</em></strong> retain the fact that this error represents an <strong>ErrDivisionByZero</strong> ?</p><p>Fortunately, <strong>fmt.Errorf()</strong> has another trick up its sleeve that can help.</p><p>As well as supporting all of the other formatting options of <strong>fmt.Sprintf()</strong>, <strong>fmt.Errorf()</strong> supports an additional formatting specification: <strong>%w</strong>.</p><p>The <strong>%w</strong> specification expects an <strong>error</strong> value in the arguments list which is then “wrapped” (hence <strong>%w</strong>: for <strong><em>w</em></strong><em>rap</em>) inside the <strong>error</strong> that the function returns.</p><p>When <strong>fmt.Errorf()</strong> is provided with an <strong>error</strong> to wrap, the returned <strong>error</strong> will include the <strong>Error()</strong>result of the wrapped error in place of the <strong>%w</strong> option in the string <strong><em>and</em></strong> will also <em>contain a reference to the wrapped </em><strong>error</strong>itself.</p><blockquote>This is more-or-less equivalent to the <strong>InnerException </strong>reference found in many languages that use exceptions for dealing with errors.</blockquote><p>Applying this to the <strong>Remainder()</strong> function, we can use:</p><pre>return -1, fmt.Errorf(&quot;Remainder: %w&quot;, ErrDivisionByZero)</pre><p>But the test is still failing!</p><p>The error returned by <strong>Remainder()</strong> is now wrapping the <strong>ErrDivisionByZero</strong> but it still is not an <strong>ErrDivisionByZero</strong> itself; checking for <strong>ErrDivisionByZero</strong> equality is not going to work.</p><p>We need to check the error <em>in a way that takes account of any wrapped error</em>.</p><h3>Unwrapping Errors</h3><p>When an error wraps another error, it is expected to implement an <strong>Unwrap()</strong> function to return the wrapped <strong>error</strong>, or <strong>nil</strong> if there is no wrapped error.</p><p>We could therefore modify our error handling code to do something similar to this:</p><pre>err := Calc()<br>for err != nil {<br>   switch err {<br>      case ErrDivisionByZero:<br>         // handle the division by zero scenario then set err = nil<br>         // to exit the for loop<br>         err = nil<br>      default:<br>         if w, ok := err.(interface { Unwrap() error }); ok {<br>            err = w.Unwrap()<br>         }<br>   }<br>}</pre><p>There are other ways of achieving the same outcome, but nobody wants to have to write error handling code like this.</p><p>We’ve already used the <strong>errors</strong> package for creating errors. But it also contains functions for working with errors, including testing their identity and dealing with wrapped errors.</p><p>To solve this first problem, we can use just one of the functions provided: <strong>errors.Is()</strong>.</p><h3>errors.Is()</h3><p>The <strong>errors.Is()</strong> function tests a supplied <strong>error</strong> to determine whether it is a match for a specified target error. This could be a match based on equality or some more complex criteria.</p><p>When dealing with sentinels, the equality test is all that we are concerned with so we shall focus on that for now.</p><p>Just as illustrated in the code above, if the error does not match the target, <strong>errors.Is()</strong> tries to unwrap the error and proceeds to test any wrapped errors until it finds a match for the target or there are no more errors to unwrap.</p><p>Rather than modify the <strong>Remainder()</strong> function, this time we need to update the test. Specifically we need to replace:</p><pre>if err != ErrDivisionByZero {<br>   t.Errorf(&quot;wanted err ErrDivisionByZero, got %s&quot;, err)<br>}</pre><p>with:</p><pre>if !errors.Is(err, ErrDivisionByZero) {<br>   t.Errorf(&quot;wanted err ErrDivisionByZero, got %s&quot;, err)<br>}</pre><p>With that, the test should now pass once again.</p><blockquote>If you are following along and coding these examples, you could change the <strong>%w</strong> back to a <strong>%s</strong> in the <strong>Remainder()</strong> function and observe that this will once again break the test because the <strong>ErrDivisionByZero</strong> error is not wrapped when using<strong>%s</strong>; only <strong>%w</strong> results in a wrapped error.</blockquote><p>But there’s more to this <strong>fmt.Errorf()</strong> feature than wrapping an error. You can use it to wrap <em>multiple</em> errors!</p><h3>Wrapping Multiple Errors</h3><p>We will use an example to demonstrate this, but first, you may be wondering why you would ever want or need to wrap multiple errors?</p><p>There are at least two scenarios where this is useful, one of which <strong>fmt.Errorf()</strong> is particularly well suited to (<em>the other one not so much, but we’ll get to that in a minute…</em>).</p><p>Where <strong>fmt.Errorf()</strong> <em>can</em> help is when dealing with an <strong>error</strong> from a package which does not provide a sentinel that we can test for, or if we wish to avoid coupling tests to an implementation dependency.</p><p>Consider a JSON unmarshalling error:</p><pre>func HandleMessage(msg any) error {<br>   msg, err := ReadMessage()<br>   if err != nil {<br>      return fmt.Errorf(&quot;HandleMessage: %w&quot;, err)<br>   }<br>}<br><br>func ReadMessage() (*msg, err) {<br><br>   // .. some code that obtains a []byte (b), which is expected<br>   // to contain the JSON representation of a msg struct ...<br><br>   m := new(msg)<br>   if err := json.Unmarshal(b, m); err != nil {<br>      return nil, fmt.Errorf(&quot;ReadMessage: %w&quot;, err)<br>   }<br>   return m, nil<br>}</pre><p>A unit test for the <strong>ReadMessage()</strong> function will need to include coverage for a scenario in which a message is read which cannot successfully unmarshal as a <strong>msg.</strong></p><p>An error returned by <strong>json.Unmarshal()</strong> could be one of at least two types: <strong>json.SyntaxError</strong> or <strong>json.UnmarshalTypeError</strong>. Or, if the project switches to some other <strong>json</strong> encoder, of an entirely different type altogether.</p><p>Ideally a <strong>ReadMessage()</strong> unit test would have some way to determine that the function behaves correctly when encountering an incorrectly formatted (i.e. invalid) message, without relying on an implementation detail of any particular dependency, i.e. errors defined by the <strong>json</strong> package.</p><p>But we may have other code in the project which legitimately deals with specific <strong>json</strong> errors, so we don’t want to lose the original <strong>json</strong> error entirely.</p><blockquote>Any such code will be covered by its own tests; right now we are concerned with <strong>ReadMessage()</strong> and in this case we don’t care about the specific error.</blockquote><p>We can achieve both goals using <strong>fmt.Errorf()</strong> by including not one but <strong><em>two</em></strong> <strong>%w</strong> specifications in the format string, and supplying both the <em>original</em> unmarshalling <strong>error</strong> and a new sentinel <strong>error</strong> defined by the package containing the <strong>ReadMessage()</strong> function:</p><pre>var ErrInvalidMessage = errors.New(&quot;invalid message&quot;)<br><br>func ReadMessage() (*msg, err) {<br><br>   // .. some code that obtains a []byte (b), which is expected<br>   // to contain the JSON representation of a msg struct ...<br><br>   m := new(msg)<br>   if err := json.Unmarshal(b, m); err != nil {<br>      return nil, fmt.Errorf(&quot;ReadMessage: %w: %w&quot;, ErrInvalidMessage, err)<br>   }<br>   return m, nil<br>}</pre><p>Not only does the error returned contain both the original error and the sentinel, but the <strong>string</strong> of the error provides useful context which might be similar to:</p><pre>ReadMessage: invalid message: expected { or [ but got &quot;foo&quot;</pre><p>Our unit test can now use <strong>errors.Is()</strong> to verify that <strong>ReadMessage()</strong> returns an <strong>ErrInvalidMessage</strong> error in this scenario:</p><pre>if !errors.Is(err, ErrInvalidMessage) {<br>   t.Errorf(&quot;wanted err ErrInvalidMessage, got %s&quot;, err)<br>}</pre><p>But how do we ensure that the original, implementation specific error is also returned?</p><p>One possible approach can be identified if we take a look at <a href="https://cs.opensource.google/go/go/+/refs/tags/go1.21.3:src/errors/wrap.go">the source for the </a><a href="https://cs.opensource.google/go/go/+/refs/tags/go1.21.3:src/errors/wrap.go"><strong>errors.Is()</strong> function</a>, which contains this <strong>switch</strong> statement:</p><pre>  switch x := err.(type) {<br>  case interface{ Unwrap() error }:<br>     err = x.Unwrap()<br>     if err == nil {<br>        return false<br>     }<br>  case interface{ Unwrap() []error }:<br>     for _, err := range x.Unwrap() {<br>        if Is(err, target) {<br>           return true<br>        }<br>     }<br>     return false<br>  default:<br>     return false<br>  }</pre><p>From this we determine that <strong>errors.Is()</strong> identifies whether an <strong>error</strong> wraps a single <strong>error</strong> or <em>multiple</em> errors by testing for the implementation of <em>two different forms</em> of an <strong>Unwrap()</strong> function, one which returns <strong>error</strong> or another which returns <strong>[]error</strong>.</p><p>We can use this ourselves in our test, producing something similar to:</p><pre>err := ReadMessage()<br>if !errors.Is(err, ErrInvalidMessage) {<br>   t.Errorf(&quot;wanted err ErrInvalidMessage, got %s&quot;, err)<br>}<br><br>wanted := 2<br>got := 1<br>if errs, ok := err.(interface{ Unwrap() []error }); ok {<br>   got = len(errs.Unwrap())<br>}<br>if wanted != got {<br>   t.Errorf(&quot;wanted %d errors, got %d&quot;, wanted, got)<br>}</pre><p>The test uses a cast to an anonymous interface implementing the version of <strong>Unwrap()</strong> that returns a slice of errors. If this is successful then the <strong>error</strong> is unwrapped using that <strong>Unwrap()</strong> method and the number of errors in the slice determined.</p><p>Since the test expects an <strong>ErrInvalidMessage</strong> error plus the implementation specific unmarshalling <strong>error</strong>, the slice must contain 2 errors for the test to pass.</p><h3>2’s Company…</h3><p>What if you need to wrap <em>more</em> than 2 errors? Again, before looking at <em>how</em>, let’s first consider <em>why</em> you might want or need to since, although not a common requirement, it can come up.</p><p>Imagine you are developing a microservice to be deployed onto Kubernetes, with a number of environment variables defined to provide configuration for various dependencies in the service, a database perhaps or details of a Kafka client configuration.</p><p>You might have a function similar to this somewhere, called during startup, to load and validate those environment variables:</p><pre>func LoadEnvironment() error {<br>   KafkaBrokerlist = os.Getenv(&quot;KAFKA_BROKER&quot;)<br>   if KafkaBrokerList == &quot;&quot; {<br>      return ErrKafkaBrokerNotConfigured<br>   }<br><br>   DatabaseHostname = os.Getenv(&quot;DB_HOSTNAME&quot;)<br>   if DatabaseHostname == &quot;&quot; {<br>      return ErrDBHostnameNotConfigured<br>   }<br>   DatabaseSSLCALocation = os.Getenv(&quot;DB_SSLCA&quot;)<br>   if DatabaseSSLCALocation == &quot;&quot; {<br>      return ErrDBSSLCANotConfigured<br>   } else if _, err := os.Stat(DatabaseSSLCALocation); os.IsNotExist(err) {<br>      return fmt.Errorf(&quot;%w: %q&quot;, ErrDBSSLCALocationDoesNotExist, DatabaseSSLCALocation)<br>   }<br>}</pre><p>Ignoring any issues with the approach and looking just at the error handling, this is fine as far as it goes: errors are being returned as expected, sentinels are used for specific error conditions and/or wrapped with additional information so that the function can be tested easily reliably.</p><p>But if there are multiple configuration errors only the <em>first</em> will be returned, potentially leading to a frustrating and time-consuming exercise fixing one error only to get a different error the next time the service tries to startup.</p><p>In the case of this function, and potentially others like it, it would be far better if we could get <strong><em>all</em></strong> of the errors returned.</p><p>It is possible to use <strong>fmt.Errorf()</strong>, but this is where it is less than helpful. You’d need to figure out how many errors you had, build a format string with the right number of <strong>%w</strong> specifiers and then pass in those errors.</p><p>Possible, but messy and error-prone itself.</p><p>Fortunately, as of <strong>Go 1.20</strong>, the <strong>errors</strong> package has another useful function that can help: <strong>errors.Join()</strong></p><h3><strong>errors.Join()</strong></h3><p>The <strong>errors.Join()</strong> function seems to exist for precisely this use case.</p><p>The function is variadic; that is, it accepts an arbitrary number of arguments, similar to <strong>fmt.Sprintf()</strong>, for example. But in the case of <strong>errors.Join()</strong> it is specifically an <em>arbitrary number of </em><strong><em>error</em></strong><em> arguments</em>.</p><p>If any of the arguments are non-<strong>nil</strong>, then an <strong>error</strong> is returned that wraps <em>all</em> of those non-<strong>nil</strong> errors (and <em>only</em> those errors).</p><p>If there are no arguments or all of the arguments are <strong>nil</strong>, then <strong>nil</strong> is returned.</p><p>Using this in our <strong>LoadEnvironment()</strong> example could result in something similar to this:</p><pre>func LoadEnvironment() error {<br>   errs := []error{}<br> <br>   KafkaBrokerlist = os.Getenv(&quot;KAFKA_BROKER&quot;)<br>   if KafkaBrokerList == &quot;&quot; {<br>      errs = append(errs, ErrKafkaBrokerNotConfigured)<br>   }<br><br>   DatabaseHostname = os.Getenv(&quot;DB_HOSTNAME&quot;)<br>   if DatabaseHostname == &quot;&quot; {<br>      errs = append(errs, ErrDBHostnameNotConfigured)<br>   }<br>   DatabaseSSLCALocation = os.Getenv(&quot;DB_SSLCA&quot;)<br>   if DatabaseSSLCALocation == &quot;&quot; {<br>      errs = append(errs, ErrDBSSLCANotConfigured)<br>   } else if _, err := os.Stat(DatabaseSSLCALocation); os.IsNotExist(err) {<br>      errs = append(errs, fmt.Errorf(&quot;%w: %q&quot;, ErrDBSSLCALocationDoesNotExist, DatabaseSSLCALocation))<br>   }<br><br>   return errors.Join(errs...)<br>}</pre><p>First, an empty slice of errors is initialised.</p><blockquote>If you really need to maximise performance and/or avoid reallocations you could initialise this with a capacity equal to or greater than the maximum possible number of errors.</blockquote><p>As each condition is evaluated, instead of <em>returning</em> an <strong>error</strong> the appropriate <strong>error</strong> is appended to the slice.</p><p>Finally, the function returns the result of <strong>errors.Join()</strong>, using the spread operator to pass all of the items in the slice as arguments.</p><p>If there were no errors, then the slice is empty and <strong>errors.Join()</strong> returns <strong>nil</strong>. But if there one or more errors, then an <strong>error</strong> is returned which wraps all of them.</p><p>The logs produced by our service from this error (<em>because you are logging your errors, right?</em>) will be able to identify <em>all</em> of the configuration issues, enabling us to quickly address them and get our service back on its feet!</p><p>We’ve seen how we can create errors that consist of other errors, whether adding a sentinel to “tag” another error to help us write tests that are not coupled to implementation details, or collecting up a number of closely related errors that might occur in a single operation, to enable us to more quickly diagnose and resolve related issues effectively.</p><p>And in <a href="https://medium.com/@delticsnz/error-handling-in-go-beyond-the-basics-e5b90d1d7be1">the first instalment of this series</a> we saw that an <strong>error</strong> can be any type that implements an <strong>Error() string</strong> function but, so far, we have relied on errors created for us by <strong>errors.New()</strong>, <strong>fmt.Errorf()</strong> or <strong>errors.Join()</strong>.</p><p>In the next instalment we’ll look at how we can implement our own <strong>error</strong> types and why we might choose to do that.</p><h3>Stackademic</h3><p><em>Thank you for reading until the end. Before you go:</em></p><ul><li><em>Please consider </em><strong><em>clapping</em></strong><em> and </em><strong><em>following</em></strong><em> the writer! 👏</em></li><li><em>Follow us on </em><a href="https://twitter.com/stackademichq"><strong><em>Twitter(X)</em></strong></a><em>, </em><a href="https://www.linkedin.com/company/stackademic"><strong><em>LinkedIn</em></strong></a><em>, and </em><a href="https://www.youtube.com/c/stackademic"><strong><em>YouTube</em></strong></a><strong><em>.</em></strong></li><li><em>Visit </em><a href="http://stackademic.com/"><strong><em>Stackademic.com</em></strong></a><em> to find out more about how we are democratizing free programming education around the world.</em></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3a6952a00cd4" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/error-handling-in-go-first-steps-with-wrapping-3a6952a00cd4">Error Handling in Go: First Steps with Wrapping</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Error Handling in Go: Beyond the Basics]]></title>
            <link>https://blog.stackademic.com/error-handling-in-go-beyond-the-basics-e5b90d1d7be1?source=rss-0dd174fd7d69------2</link>
            <guid isPermaLink="false">https://medium.com/p/e5b90d1d7be1</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[golang]]></category>
            <category><![CDATA[go]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[error-handling]]></category>
            <dc:creator><![CDATA[Jolyon Direnko-Smith]]></dc:creator>
            <pubDate>Tue, 24 Oct 2023 19:24:51 GMT</pubDate>
            <atom:updated>2023-11-10T04:49:41.229Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/878/1*bpjTZn51eFiSJBMR540UMw.png" /></figure><h3>Error Handling in Go: The Basics</h3><p>When I first started learning Go error handling was an area that caused me a great deal of frustration. Having started with BASIC before my teens then progressing to languages with structured exception handling, returning error values and having to write ‘if’ statements to handle errors everywhere felt like a return to <em>The Bad Old Days</em>, not to mention a violation of <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY</a>.</p><p>Roll the clock forward to today however, and Go’s approach to error handling is among my favourite features of the language. This transformation came about as the language and runtime evolved but also as I learned to make the approach work to my benefit and advantage.</p><p>Before diving into more advanced areas, a recap of the basics may be in order.</p><h3>The Basics</h3><p>Everyone starting out in Go will quickly become familiar with two patterns:</p><ol><li>If a function can return an error then it will return an error. Thanks to the support for multiple return values, a function can return an error in addition to any “happy path” results; and</li><li>If a function is called that can return an error then any error should be checked and handled by the caller.</li></ol><p>As an example, consider this hypothetical implementation of a function to return the remainder result of the division of two <strong>int</strong>s:</p><pre>func Remainder(n, d int) (int, error) {<br>   if d == 0 {<br>      return -1, errors.New(&quot;division by zero&quot;)<br>   }<br>   return n%d, nil<br>}</pre><p>If the divisor argument is 0 (zero) then the division operation is undefined. To avoid a panic the function returns an error, using the convenience function <strong>errors.New()</strong> to create the error that is returned (<em>more on that shortly</em>).</p><p>Since the <strong>Remainder()</strong> function may return an error, any call to this function must check for an error, and handle it. At a minimum this might look similar to:</p><pre>func Calc() error {<br>   // some calculation producing a numerator (n) and divisor (d)<br>   // for which the calculation requires the remainder (r) ...<br><br>   r, err := Remainder(n, d)<br>   if err != nil {<br>      return err<br>   }<br><br>   // ... and potentially other calculations ...<br>}</pre><p>In this case, the <strong>Calc()</strong> function itself can return an error so, when it receives an <strong>error</strong> from the <strong>Remainder()</strong> function, it returns that (or any other error that might arise in the calculation).</p><p>Before we consider how an error might be handled differently in different circumstance, let’s dig a little more into what exactly an <strong>error</strong> is and that <strong>errors.New()</strong> function.</p><h3>The error Type and Errors.New()</h3><p>The <strong>error</strong> type in Go is an interface with a single method:</p><pre>type error interface {<br>   Error() string<br>}</pre><p>Interfaces in Go do not require a formal declaration of an implementation, instead using <a href="https://en.wikipedia.org/wiki/Duck_typing">duck-typing</a>, to paraphrase:</p><blockquote><strong>duck-typing:</strong> if it looks like a duck, waddles like a duck, swims like a duck, flies like a duck and quacks like a duck then it is, to all intents and purposes, a duck</blockquote><p>That is, <em>any</em> type that implements a function <strong>Error()</strong> returning a <strong>string</strong> can be used as an <strong>error</strong>.</p><p>The Go definition of an <strong>error</strong> captures a fundamental principle: an <strong>error</strong> is something that describes itself [<em>with a string value</em>].</p><p><strong>An </strong><strong>error, in Go, is required and expected <em>by definition (literally) </em>to be <em>more</em> than just an error code, or a mere success/failure indicator</strong>.</p><p>This immediately elevates this business of returning errors from functions from <em>superficially</em> similar patterns in days past.</p><p>But it also creates a problem: if an <strong>error</strong> is defined in terms of an interface, what <em>types</em> exist that <em>implement</em> this interface that I can return from my functions when I need to return an <strong>error</strong>? An <strong>error</strong> needs to describe itself with a <strong>string</strong>, but you cannot just <em>return</em> a <strong>string</strong>, because the <strong>string</strong> type does not implement the <strong>Error()</strong> function.</p><p>You <em>could</em> create your own string-based type that implements the <strong>error</strong> interface:</p><pre>type MyError string<br><br>func (err MyError) Error() string { return string(err) }</pre><p>Being based on string, the <strong>Remainder()</strong> function could be modified to return an error of this type by simply casting a string:</p><pre>func Remainder(n, d int) (int, error) {<br>   if d == 0 {<br>      return -1, MyError(&quot;division by zero&quot;)<br>   }<br>   return n%d, nil<br>}</pre><p>This seems to be a good way to go. Once we’ve declared the <strong>MyError</strong> type, using it appears to avoid a function call and involves less typing than using <strong>errors.New()</strong>.</p><p>But beyond avoiding the need to create a custom error type, the use of <strong>errors.New()</strong> in the original implementation also addresses a potentially significant flaw in that custom error, which only becomes apparent when we look at <em>handling</em> errors rather than creating and returning them.</p><h3>Error Handling</h3><p>In the <strong>Calc()</strong> function above, when an error is returned from the <strong>Remainder()</strong> function, the <strong>Calc()</strong> function simply returns that error back to its caller.</p><p>But what if the <strong>Calc()</strong> function were reading some data from a file as part of the processing? When reading from a file, <strong>io.EOF</strong> is returned as an error when the end of the file is reached. In that scenario,<strong>Calc()</strong> would likely not want to treat this as an error but simply move on to the next step of the calculation:</p><pre>func Calc() error {<br><br>   // ... load some data from a file (f) (the file has already been opened)<br>   for {<br>        data = data[:cap(data)]<br>        n, err := f.Read(data)<br>        if err != nil {<br>           // ?<br>        }<br>        // .. process the data just read<br>   }<br><br>   // .. further calc processing<br>}</pre><p>When <strong>f.Read(data)</strong> returns an error, that error might simply be signalling the end of the file, i.e. <strong>io.EOF</strong>. How can we determine whether the <strong>error</strong> is <em>that specific error</em>?</p><p>If we check <a href="https://pkg.go.dev/io#pkg-variables">the definition of </a><a href="https://pkg.go.dev/io#pkg-variables"><strong>io.EOF</strong> itself</a>, we find that:</p><pre>var EOF = errors.New(&quot;EOF&quot;)</pre><p>Knowing that all error values have an <strong>Error()</strong> function that return a string, we could use a test similar to this:</p><pre>if err.Error() == &quot;EOF&quot; {<br>   // no more data<br>}</pre><p>This does work, but is problematic. There is no way to tell if this <em>really is</em> the <strong>io.EOF</strong> error or simply <em>some other error that also returns the string “EOF” from its </em><strong><em>Error()</em></strong><em> function</em>.</p><p>Fortunately, <strong>io.EOF</strong> is a <em>sentinel</em> error.</p><h3>Sentinel Errors</h3><p>Sentinels are a special <em>category</em> of error that is specifically intended to be identifiable using a straight-forward equality test:</p><pre>if err == io.EOF {<br>   // no more data to process<br>}</pre><p>This means that a sentinel error must have two basic characteristics:</p><ol><li>a unique, public identity</li><li>a constant value (in the sense of consistent and non-varying)</li></ol><p>To explore the first of these characteristics, let’s see how the <strong>io.EOF</strong> error differs from the <strong>MyError</strong> type created above by comparing various <strong>error</strong> values, using <a href="https://go.dev/play/p/iUFA6pgv9_r">this playground</a>:</p><pre>package main<br><br>import (<br>   &quot;errors&quot;<br>   &quot;fmt&quot;<br>   &quot;io&quot;<br>)<br><br>type MyError string<br><br>func (err MyError) Error() string { return string(err) }<br><br>func main() {<br>   erra := MyError(&quot;EOF&quot;)<br>   errb := errors.New(&quot;EOF&quot;)<br>   errc := io.EOF<br><br>   fmt.Printf(&quot;erra   == MyError(\&quot;EOF\&quot;)    // %v\n&quot;, erra == MyError(&quot;EOF&quot;))<br>   fmt.Printf(&quot;errb   == errors.New(\&quot;EOF\&quot;) // %v\n&quot;, errb == errors.New(&quot;EOF&quot;))<br>   fmt.Printf(&quot;io.EOF == errors.New(\&quot;EOF\&quot;) // %v\n&quot;, io.EOF == errors.New(&quot;EOF&quot;))<br>   fmt.Printf(&quot;errc   == io.EOF            // %v\n&quot;, errc == io.EOF)<br>}</pre><p>That <strong>erra</strong> and <strong>errb</strong> are not equal to <strong>io.EOF</strong> is probably not a surprise. What <em>may</em> be a little surprising is that:</p><ol><li>a <strong>MyError(str)</strong> <em>is</em> equal to any other <strong>MyError(str)</strong> for the same str</li><li>an <strong>errors.New(str)</strong> is <em>not</em> equal to another <strong>errors.New(str)</strong> even for the same str</li></ol><p>As well as being a convenient way to create errors from strings, <strong>errors.New()</strong> goes further <em>to ensure that all errors it returns are unique</em>, even if defined from the same string.</p><p>With all that in mind, our <strong>io.EOF</strong>-aware implementation of that <strong>Calc()</strong> function might look similar to this:</p><pre>func Calc() error {<br><br>   // ... load some data from a file (f) (the file has already been opened)<br>readData:<br>   for {<br>      data = data[:cap(data)]<br>      n, err := f.Read(data)<br>      switch err {<br>         case nil:<br>            // .. process the data just read<br>         case io.EOF:<br>            break readData<br>         default:<br>            return err <br>      }<br>   }<br><br>   // .. further calc processing<br>}</pre><p>So <strong>errors.New()</strong> provides errors with a unique identity and these can be made public by holding them in an exported reference, satisfying the first basic requirement of a sentinel:</p><ol><li>a unique, public identity</li></ol><p>But what of the second characteristic: <em>a constant value</em>?</p><h3>Caveat Error</h3><p>The Go compiler will not accept a function result as a constant expression so any error defined using <strong>errors.New()</strong> must be held in a <strong>var</strong> and, since sentinel errors are intended to be used in equality tests, they <em>must</em> be exported from your package.</p><p>As any fool knows, if a variable is exported from a package, then it is mutable by code in any <em>other</em> package.</p><p>In other words, you (or <em>someone in another package that your code imports</em>) could maliciously (or inadvertently) redefine <strong>io.EOF</strong> to hold some other error value:</p><pre>// my cunning and devious design...<br>func init() {<br>   io.EOF = MyError(&quot;end of file was reached&quot;)<br>}</pre><p>This is decidedly not good and is at least one argument for the Go language to adopt immutable/write-once variables (<em>which, as of Oct 2023, it does not</em>). But it is not perhaps as bad as you might initially think.</p><ol><li>any code in the <strong>io</strong> package that returns <strong>io.EOF</strong> will still return <strong>io.EOF</strong>, just not the value initially defined by the <strong>io</strong> package; <em>and</em></li><li>code that tests for <strong>err == io.EOF</strong> will still evaluate correctly if testing an error returned by a function that returns <strong>io.EOF</strong>; <em>but</em></li><li>code that tests for <strong>err == MyError(“EOF”)</strong> will now also start evaluating true if <strong>err</strong> is an <strong>io.EOF</strong>. This <em>might</em> be correct/desirable behaviour but if so, it is a happy coincidence; it is certainly not the <em>intended/expected</em> behaviour; <em>and</em></li><li>any code that tests for <strong>err.Error() == “EOF”</strong> would no longer work as expected. But this is not a reliable or correct way to test for <strong>io.EOF</strong> (or any error for that matter); correct <em>that</em> problem and #2 above applies.</li></ol><p>Which leaves only one <em>real</em> problem: If the error is logged, it will not be described as expected, outputting <strong>“end of file was reached”</strong> instead of <strong>“EOF”</strong>. Any log analytics/alerts may be configured to identify<strong>“EOF”</strong> log entries, not <strong>“end of file was reached”</strong>. Having said that, such analytics/alerts would in any event be unable to distinguish between <strong>io.EOF</strong> and any other error that returned <strong>&quot;EOF”</strong> from the <strong>Error()</strong> function; this problem is perhaps one of log/analytics/alert design as much as, or perhaps instead of, the mutability of <strong>io.EOF</strong>.</p><blockquote>Worth noting is that there would be a MUCH bigger and very real problem if <strong>io.EOF</strong> were re-assigned the value <strong>nil</strong> ! In that case pretty much everything breaks!</blockquote><p>But you have unit tests in place that would pick up any such issues, even if unwittingly introduced by some malicious 3rd-party package. Right?</p><p><strong><em>Right?</em></strong></p><h3>Const Errors</h3><p>There have been various efforts to address the issue of mutable sentinel errors. One simple approach is to use a string-based error type, values of which can be declared <strong>const</strong> so, using the <strong>MyError</strong> example above, we could declare a <strong>const</strong> sentinel thus:</p><pre>const ErrDivisionByZero = MyError(&quot;division by zero&quot;)</pre><p>However, this suffers from the problem outlined above, that two <strong>MyError</strong> values having the same underlying string are considered equal; this is not good since a fundamental property of a sentinel error is that it should have a <em>unique</em> identity.</p><p>I have explored various other approaches to <strong>const</strong> errors and come to the following conclusion: <em>it’s not worth it</em>.</p><p>The complications and contortions involved risk making errors in your code harder to understand. All to address a <em>potential</em> problem that is unlikely to ever be a <em>real</em> problem and can be mitigated in any case with suitable test coverage, if desired.</p><p>I am also hopeful that Go will adopt write-once variables, at which point the problem disappears entirely.</p><blockquote>A quick call-out: as mentioned at the outset, “<em>sentinels are a special </em><strong><em>category</em></strong><em> of error</em>”. A sentinel is not a special <strong><em>type</em></strong><em> just </em>a regular error like any other in Go. What sets sentinels apart is the way they are <strong><em>used</em></strong>.</blockquote><h3>Applying the Basics</h3><p>We have now learned enough about errors and error handling to be able to provide a <strong>Remainder()</strong> function that returns a reliable error that can be used to reliably identify a specific error condition in calculations.</p><p>We declare a sentinel error that we will use for our <em>division by zero</em> condition and return this specific error from the <strong>Remainder()</strong> function when that condition is identified:</p><pre>var ErrDivisionByZero = errors.New(&quot;division by zero&quot;)<br><br>func Remainder(n, d int) (int, error) {<br>   if d == 0 {<br>      return -1, ErrDivisionByZero<br>   }<br>   return n%d, nil<br>}</pre><p>The <strong>Calc()</strong> function can test for this sentinel to adopt a suitable response to a division by zero, if required:</p><pre>func Calc() error {<br>   // some calculation producing a numerator (n) and divisor (d)<br>   // for which the calculation requires the remainder (r) ...<br><br>   r, err := Remainder(n, d)<br>   switch err {<br>      case nil:<br>         // NO-OP<br>      case ErrDivisionByZero:<br>         r = 0<br>      default:<br>         return err<br>   }<br><br>   // ... and potentially other calculations ...<br>}</pre><p>This is purely an illustration; the <strong>Calc()</strong> function in this instance could obviously pre-empt and avoid the division by zero error by testing the value of <strong>d</strong> itself and calling <strong>Remainder()</strong>only for non-zero values <em>(not to mention that the </em><strong><em>Remainder()</em></strong><em> function is an entirely unnecessary complication — this is </em><strong><em>just</em></strong><em> an illustration</em>).</p><p>In this initial article we have reviewed the fundamentals of errors and error handling in Go. In future installments we will explore more complex, custom error types and some of the changes and additional features introduced to the standard library over time that have made working with errors in Go such fun.<br><br>Yes, you read that right: <em>error handling can be fun</em>!</p><h3>Stackademic</h3><p><em>Thank you for reading until the end. Before you go:</em></p><ul><li><em>Please consider </em><strong><em>clapping</em></strong><em> and </em><strong><em>following</em></strong><em> the writer! 👏</em></li><li><em>Follow us on </em><a href="https://twitter.com/stackademichq"><strong><em>Twitter(X)</em></strong></a><em>, </em><a href="https://www.linkedin.com/company/stackademic"><strong><em>LinkedIn</em></strong></a><em>, and </em><a href="https://www.youtube.com/c/stackademic"><strong><em>YouTube</em></strong></a><strong><em>.</em></strong></li><li><em>Visit </em><a href="http://stackademic.com/"><strong><em>Stackademic.com</em></strong></a><em> to find out more about how we are democratizing free programming education around the world.</em></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e5b90d1d7be1" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/error-handling-in-go-beyond-the-basics-e5b90d1d7be1">Error Handling in Go: Beyond the Basics</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>