DEV Community: Rafal Zajac

Crafting Go Testing Module: Step 4 - Goldy and Must

Rafal Zajac — Fri, 16 May 2025 20:18:57 +0000

This is the fourth chapter in my blog series about building a Go Testing Module from scratch. If you’re new here, I recommend checking out the previous post for some context. In this post, I’m diving into two new packages I’ve created — goldy and must. These tools tackle problems you’ve probably faced in writing tests, making your test code cleaner, more readable, and a lot more enjoyable to work with. Let me walk you through how I built these packages to solve those familiar testing headaches.

The `goldy` Package

You’ve likely faced the frustration of testing a function that generates a complex, multi-line string — like a JSON response or a formatted report. Hardcoding that string in your test code turns it into a cluttered mess that’s tough to read and even harder to maintain. I’ve been there, staring at a test file bloated with string literals. That’s why I created the goldy package, a lightweight tool that uses golden files to store expected outputs, keeping test code tidy and manageable.

What’s a Golden File?

A golden file is like a reference sheet for tests. It stores the expected output in a separate file, making it easy to compare against actual results. In goldy, I designed golden files to be clear and contextual. They include comments to explain their purpose, followed by the expected content. Here’s an example of a golden file, typically saved with a .gld extension:

This comment explains the golden file's purpose.
It can span multiple lines for clarity.
---
Content line #1.
Content line #2.

The format is simple:

Optional comment lines at the top to describe the file’s intent.
A mandatory --- separator line to mark the start of the content.
The expected content (the "golden" output).

This structure keeps things organized and makes golden files easy to read and update.

Using `goldy` in Tests

Here’s how you use goldy to test a function that generates a multi-line string:

func TestSomething(t *testing.T) {
    // --- Given ---
    gld := goldy.Open(t, "testdata/test_case123.gld") 

    // --- When ---
    have := Something(123)

    // --- Then ---
    affirm.Equal(t, gld.String(), have) // Use content as string.
    affirm.Equal(t, gld.Bytes(), have) // Use content as bytes.
}

The goldy.Open function loads the golden file and returns a Goldy struct with fields I find useful during testing:

// Goldy represents golden file.
type Goldy struct {
    Path    string // Path to the golden file.
    Comment string // Comments from the file.
    Content []byte // Content after the --- marker.
}

When the expected output changes, I can update the golden file by calling gld.Save(). This makes it simple to keep golden files in sync as the code evolves.

Why `goldy` Matters

Building goldy was my answer to the chaos of managing large outputs in tests. It’s not just about cleaner code — it’s about making tests easier to maintain and understand. When a test fails, I can quickly check the golden file’s comments to grasp the context of the expected output. Storing large outputs in separate files also keeps test files focused on logic, not data.

The `must` Package

You’ve probably dealt with the annoyance of repetitive error handling in a test setup section. I know I have — writing a setup section full of if err != nil checks that clutter the code and distract from the test’s purpose. It’s functional, but it feels like wading through noise. The must package is my solution: a set of helper functions that panic on errors, letting me focus on the test logic instead of boilerplate or setup code.

Here is an example of a test setup I used to write before must:

func TestSomething(t *testing.T) {
    // --- Given ---
    wd, err := os.Getwd()
    if err != nil {
        t.Fatal(err)
    }

    fil, err := os.Open("/data")
    if err != nil {
        t.Fatal(err)
    }

    // --- When ---
    have := Something(wd, fil, 123)

    // --- Then ---
    affirm.Equal(t, true, have)
}

This is of course very simple example yet the Given section is noisy, with error checks drowning out the test’s purpose. It works, but it’s far from elegant, in my opinion. Here’s the same test using must:

func TestSomething(t *testing.T) {
    // --- Given ---
    wd := must.Value(os.Getwd()) 
    fil := must.Value(os.Open("/data"))

    // --- When ---
    have := Something(wd, fil, 123)

    // --- Then ---
    affirm.Equal(t, true, have)
}

This is so much cleaner! The setup is concise, readable, and keeps the focus on preparing the test state. The must functions handle errors by panicking if something goes wrong, which Go’s testing framework catches and reports as a test failure. I find this approach perfect for test setup, where I want to fail fast if preconditions aren’t met.

Exploring `must` Functions

I built the must package using generics to make it flexible and type-safe. Here are the key functions:

func Value[T any](val T, err error) T- Returns the value or panics on error.
func Values[T, TT any](val0 T, val1 TT, err error) (T, TT) - Returns two values or panics.
func Nil(err error) - Panics if the error is non-nil.
func First[T any](s []T, err error) T - Returns the first element of a slice or panics.
func Single[T any](s []T, err error) T - Returns a single element or panics.

These functions work with any type, so I can use them in all sorts of testing scenarios. They’re especially useful in the Given section, where I’m setting up dependencies and want to avoid error-handling clutter.

A Word of Caution

While must is great for test setup, I use it carefully. Panicking is a strong choice, so I save must for cases where an error means the test can’t go on. For assertions or checks in the Then section, I use affirm package to give clear failure messages.

Closing Thoughts

Building goldy and must has been a solid step in making my Go Testing Module more practical and user-friendly. These packages come from my own struggles with test code, addressing the clutter and complexity you’ve probably faced too. They help me write tests that are not just functional but also clear and easy to maintain, letting me focus on catching bugs and ensuring code works as expected.

It’s hard to believe this is already the fourth post in the series, and I haven’t even started on the assert package yet. It’s a reminder of how many pieces need to come together before diving into assertions. Tools like goldy and must lay the groundwork, handling setup and comparison tasks so the assert package can focus on clear, expressive checks. Building a testing module is like assembling a puzzle — each piece, has to fit just right before the assertion package can take shape.

I’d love for you to check out the code for goldy and must in the GitHub repository. Give them a try, poke around, and let me know what you think. If you have feedback or ideas, open an issue or drop a note on X. Your thoughts help improve this project, and I’m looking forward to the next steps.

Thanks for reading. Until the next post, happy testing!

Crafting Go Testing Module: Step 3 - Testing the Test Helpers

Rafal Zajac — Mon, 14 Apr 2025 14:01:05 +0000

In my previous post, I introduced the core and affirm packages, laying the groundwork for a dependency-free Go testing module focused on readable, intuitive tests. Now, in this third installment, I’m diving into testing the affirm package - specifically, how to verify its assertion helpers. I’ll share my thought process, the challenges I faced, and how I solved them. Let’s get started!

Follow Testing Module development on GitHub

Why Test Testing Tools?

You might ask: why go through the trouble of testing tools meant for testing? It’s a valid question, and the answer boils down to trust. If an assertion like does not work properly or misreports a crash, every test relying on it risks silent failures or false positives. That undermines reliability. By thoroughly testing, I ensure packages I create are dependable - it's like calibrating a ruler, you just created, before measuring with it. Plus, these tests serve as living examples, showing how the pieces fit together as the module grows.

The Challenge of Testing Affirmations

Testing the core package was relatively straightforward, as its utilities (IsNil, WillPanic, Same) don’t interact directly with *testing.T. The affirm package, on the other hand, poses a challenge. Its helpers - such as Equal, Nil, and Panic - rely on *testing.T to log errors and failures, among other tasks, making them harder to test without affecting the actual test runner.

Consider the Equal helper:

func Equal[T comparable](t *testing.T, want, have T) bool {
    t.Helper()
    if want != have {
        const format = "expected %T to be equal:\n  want: %#v\n  have: %#v"
        t.Errorf(format, want, want, have)
        return false
    }
    return true
}

Testing the success case is simple enough. We can use the test’s own *testing.T instance:

func Test_Equal_success(t *testing.T) {
    // --- When ---
    have := Equal(t, 42, 42)

    // --- Then ---
    if !have {
        t.Error("expected true")
    }
}

This works because when want equals have, Equal doesn’t call t.Errorf, and the test passes quietly. But testing the failure case is problematic:

func Test_Equal_failure(t *testing.T) {
    // --- When ---
    have := Equal(t, 42, 44)

    // --- Then ---
    if have {
        t.Error("expected false")
    }
}

Here’s the catch: when want doesn't equal have, Equal calls t.Errorf, which marks the test as failed in the real test runner. Even though Equal behaved correctly (logging the error and returning false), the test itself fails, masking the fact that we’re verifying the right behavior. This is a classic testing conundrum: how do we test a function that triggers test failures without failing the test?

A Solution

At this stage, my Go testing module doesn’t yet have a full-fledged mocking library (that’s coming later - stay tuned!). To test affirm helpers, I needed a way to intercept *testing.T calls without affecting the actual test runner. That’s where the core package’s T interface and Spy struct come in. I introduced the T interface to capture a subset of testing.TB methods used by affirm helpers:

// errors or failures.
type T interface {
    Error(args ...any)
    Errorf(format string, args ...any)
    Failed() bool
    Fatal(args ...any)
    Fatalf(format string, args ...any)
    Helper()
}

The Spy struct implements this interface, acting as a mock *testing.T:

type Spy struct {
    HelperCalled     bool          // Tracks if Helper was called.
    ReportedError    bool          // Tracks if Error or Errorf was called.
    TriggeredFailure bool          // Tracks if Fatal or Fatalf was called.
    Messages         *bytes.Buffer // Log messages if set.
}

With Spy, I can track whether an assertion helper called Error, Errorf, or other methods, and inspect the logged messages when needed — all without failing the actual test.

Adapting Affirm Helpers

To use Spy, I updated affirm helpers to accept core.T instead of *testing.T. For example, here’s the revised Nil helper:

func Nil(t core.T, have any) bool {
    t.Helper()
    if core.IsNil(have) {
        return true
    }
    t.Errorf(expected, nil, have)
    return false
}

This change is subtle but powerful: by using the core.T interface, helpers become testable with Spy while still working with *testing.T in real tests (since *testing.T implements core.T).

Writing Tests with Spy

Now, testing both success and failure cases becomes straightforward. Here’s how I test the Nil helper:

func Test_Nil(t *testing.T) {
    t.Run("success", func(t *testing.T) {
        // --- Given ---
        spy := core.NewSpy()

        // --- When ---
        have := Nil(spy, nil)

        // --- Then ---
        if !have || spy.Failed() {
            t.Error("expected passed test")
        }
    })

    t.Run("error", func(t *testing.T) {
        // --- Given ---
        spy := core.NewSpy()
        err := errors.New("m0")

        // --- When ---
        have := Nil(spy, err)

        // --- Then ---
        if have || !spy.Failed() {
            t.Error("expected test error")
        }
        if !spy.ReportedError {
            t.Error("expected test error")
        }
    })
}

The success case verifies that Nil returns true for a nil input and doesn’t mark the test as failed. The failure case confirms Nil returns false for a non-nil input, and uses Errorf to mark the test as failed. The Spy lets me inspect the helper’s behavior - return values, error states, and log output - without interfering with the real test runner.

Another benefit is that helpers can call t.Fatal or t.Fatalf without causing the real test to panic or exit the goroutine, making Spy a versatile tool for testing all kinds of assertions.

Trade-Offs and Reflections

Switching affirm helpers to use core.T instead of *testing.T is a pragmatic choice, but it’s not without trade-offs. On one hand, it makes testing possible without a full mocking framework. On the other, it slightly increases the package’s complexity by introducing an interface. I’m okay with this for now - it’s a small price for testability, and T is narrowly scoped to internal packages only.
Another consideration is Spy’s design. It’s minimal, capturing only the essentials (errors, failures, messages), but it’s flexible enough to grow if I add more assertion helpers later. For example, if I introduce helpers that call Fatal or FailNow, Spy’s TriggeredFailure field will already handle them.

Closing Thoughts

Testing the affirm package pushed me to think creatively about mocking *testing.T, and I’m thrilled with how Spy and T turned out. They’re not just tools for testing affirm — they’re building blocks for a module that’s as reliable as it is intuitive. This step reinforced my belief that trustworthy tests start with trustworthy tools.

As always, I’d love for you to check out the progress on the GitHub repository. The code and early docs are there - feel free to explore, test it out, or share feedback via an issue. You can also follow updates on X. Your thoughts help shape this journey, so don’t hold back!

Crafting Go Testing Module: Step 2 - Core

Rafal Zajac — Wed, 09 Apr 2025 20:43:44 +0000

Welcome back to my series on building a Go Testing Module from scratch! In the first post, I shared my vision for this project: a dependency-free, developer-friendly toolkit designed to make writing tests in Go more readable and intuitive. I laid out the key requirements - like robust assertions, clear log messages, and mocking support - and explained why I’m tackling this, from my gripes with the standard library to my passion for great developer experience (DX). If you haven’t checked it out yet, I’d recommend giving it a read to see where this journey started. Now, in this second part, we’re rolling up our sleeves and diving into the actual work. I’ll walk you through where I’m starting the implementation, breaking down the first steps and the thinking behind them. Let’s get into it!

Follow Testing Module development on GitHub

The Chicken-and-Egg Problem

In the last post, I argued that test cases riddled with conditional statements - like if want != have {} - can be a readability headache in my opinion. But here’s the catch: how do we write clean, readable tests for a Testing Module when the assertion library we’re building doesn’t exist yet? It’s a classic chicken-and-egg dilemma, and like most challenges in software engineering, it calls for a compromise. My solution is to bootstrap the project with two very small internal packages: core and affirm. These will provide just enough functionality to write readable tests for the rest of the module, even if their own tests lean on the standard library for now.

The trade-off? The internal packages will rely on those clunky if statements in their tests. But since they’re small, self-contained, and tucked away as internal tools, I’m fine with that compromise. It’s a practical move to kick things off, freeing us to craft the broader, user-facing features - like the assert package - with the readability I’m chasing. Think of it as laying a foundation below ground: it’s not pretty, and no one will see it, but it’s sturdy and reliable to support the real beautiful construction above.

The `core` Package

The core package is the bedrock of this module, a minimalist set of utilities that everything else will build on. It’s lean by design, with just couple of functions:

func IsNil(have any) bool
func WillPanic(fn func()) (val any, stack string)
func Same(want, have any) bool

Let’s break these down and see why they’re essential.

IsNil

Checking for nil in Go isn’t as simple as want == nil. Sure, that works for basic types like pointers or interfaces, but Go’s type system throws curveballs. An interface with a nil value and a non-nil type isn’t considered nil by a direct comparison - it’s a subtle gotcha that trips up even seasoned developers. IsNil handles this properly by inspecting the underlying value and type, giving us a reliable way to test for "nil-ness" across the board. In tests, this is critical: you need to know definitively whether something’s truly absent or just masquerading as nil. It will be a basis for all assertions that need to check for nil - like assert.NoError. For a deeper dive into the quirks of nil checking in Go, check out this great article:
Why Golang Nil Is Not Always Nil? Nil Explained.

WillPanic

Panics are a big deal in testing - you often want to verify that a function does panic under certain conditions (like invalid input) or doesn’t when it shouldn’t. Writing this check by hand with recover() is tedious and error-prone, so WillPanic wraps it up neatly. It runs the provided function, catches any panic, and returns what value was panicked, and a stack trace for context. This makes it a breeze to assert panic behavior - like ensuring a some call blows up as expected - without cluttering test code with boilerplate. Plus, that stack trace? Gold for debugging when things go sideways.

Same

While equality checks (==) compare values, Same answers a different question: do want and have point to the exact same memory address? This is handy for testing pointer-heavy code, like when you’re verifying that a function returns an existing object rather than a new copy. It’s a niche but powerful tool, particularly useful when you’re verifying pointer behavior or ensuring object identity in tests. By using Go’s any type, it stays flexible enough to handle any pointer type we throw at it.

These three functions may seem straightforward, but they play a crucial role in driving the testing module’s development forward.

The `affirm` Package

Next up is affirm, a stepping stone to the full-blown assert package I’ll build later. It’s deliberately minimalist, focusing on basic assertions with clean, readable log messages for a narrow set of common cases. Think of it as a starting point: it gives us usable assertions to work with while we build out the full version. Here’s what it includes:

func True(t *testing.T, have bool) bool
func False(t *testing.T, have bool) bool
func Equal[T comparable](t *testing.T, want, have T) bool
func DeepEqual(t *testing.T, want, have any) bool
func Nil(t *testing.T, have any) bool
func NotNil(t *testing.T, have any) bool
func Panic(t *testing.T, fn func()) *string

Most of the functions return a bool to indicate success (allowing you to evaluate or act on results if needed) and logs a clear, formatted failure message using t.Error when things go wrong. For instance, Equal generates a log message when values don’t match, such as:

expected values to be equal:
  want: 42
  have: 43

This keeps it simple but effective. Unlike the eventual assert package, affirm doesn’t handle fancy edge cases - like recursive types or trails mentioned in the previous article - yet. It’s just enough to make tests for the rest of the module readable, leaning on core for the heavy lifting (e.g., IsNil or WillPanic). The real assert package will take this further, adding the robustness and polish I outlined in the first post.

Closing Thoughts

This post marks the first real step into coding my Go Testing Module. Starting with core and affirm packages solves the chicken-and-egg problem, giving me a foothold to write readable tests for the bigger features ahead - like the assert package, mocking, and golden files. It’s not glamorous, but it’s foundational, and I’m excited to see it take shape. In the next post, I’ll dive into how I plan to test the affirm package, ensuring it’s a solid stepping stone before we expand it further.

I’d love for you to check out the progress on Go Testing Module - head over to the project's GitHub to see the code and documentation in action. Feedback is always appreciated, whether it’s a suggestion, a bug report, or just your thoughts on the approach. Open an issue on GitHub or drop a message on X.

Crafting Go Testing Module: Step 1 - Requirements

Rafal Zajac — Mon, 07 Apr 2025 19:45:57 +0000

This post marks the start of a series where I document my journey of developing a Testing Module for Go from the ground up. My goal is to share my thought process, my approach to problem-solving, and how I design software that’s not only functional but also a joy to use. A big part of this is focusing on developer experience (DX) - making sure the module feels intuitive and seamless for anyone who picks it up.

Why?

I’ve always admired Go for its simplicity and readability - at least in most cases. However, I hold an unpopular opinion: tests written solely with the standard library can be tough to follow. All those if statements and manual checks clutter the code and make it harder to understand what’s being tested. For example, here’s a typical assertion using the standard library:

if want != have {  
    t.Errorf("expected %v, but got %v", want, have)
}

It works, but it’s verbose and repetitive. In my view, tests become much more readable when you use assertion functions. They cut through the noise and let the intent shine through.

assert.Equal(t, want, have)

That said, assertions are just one piece of the puzzle. A truly comprehensive testing module requires more than assertions.

Requirements

I began by asking myself: what should a robust, full-featured testing module contain? After some thought, I compiled a list of requirements. It’s an ambitious set of goals, but I’m certain I can create a module that delivers on every one. Let’s break down each requirement, digging into what it entails and my approach to making it happen.

No External Dependencies

Without relying on someone else’s API or design choices, I can tailor the module exactly to my needs and preferences. This lets me craft a cohesive, intuitive interface that aligns with my vision, rather than adapting to the quirks of external tools. Another reason is simplicity. Dependency-free modules have fewer moving parts, making them easier to understand, debug, and maintain. External libraries often come with features you don’t use, adding unnecessary overhead. By writing a module from scratch, I can optimize it for my specific needs, keeping it lightweight and fast. It’s like crafting a custom tool instead of lugging around a bulky toolbox. Plus, it’s rewarding to build a tool tailored exactly to my vision, from features to docs. The catch is that it means writing a ton of code myself — code that itself will need rigorous testing to back it up.

Well-Documented

Good documentation is as vital as clean, well-crafted code - it’s the bridge linking the module to its users. To encourage developers to adopt this module, I want to provide a clear, welcoming entry point that makes diving in a breeze. That begins with a detailed README filled with practical, real-world examples they can follow, complemented by thoroughly commented code with docstrings that explain how things work. I’ll also leverage Go’s documentation strengths by including runnable examples - interactive snippets users can execute directly in the Go playground or locally - to showcase the module in action. My goal is to simplify onboarding, transforming a potentially intimidating task into a smooth, enjoyable experience. When developers can quickly see the module’s value, test it hands-on, and understand its purpose, they’re much more likely to adopt it for their own projects.

Asserting Composite and Recursive Types

Handling complex composite types-like []map[int]User or other nested structures - shouldn’t be a stumbling block for this module. Equality assertions need to work seamlessly, whether you’re comparing a simple integer or a deeply recursive type with slices, maps, and structs intertwined. Personally, I can’t stand those massive, unwieldy diffs that spill out when composite values don’t match-they’re a headache to sift through. That’s why, when a comparison fails, this module won’t just dump a wall of text; it’ll provide a concise trail of differences that I find far more readable, pinpointing the exact spot where things went off track.

expected values to be equal:  
  trail: User.Addresses[0].Appartment  
   want: 42  
   have: 4

To me, these trails are a game-changer, making debugging faster and less frustrating.

The module will be opinionated by design, shaped by my own experiences and needs as a developer, so it’s built to tackle these pain points head-on. The result is a tool that doesn’t just work - it works the way I think it should, turning a messy process into something clear and manageable.

Informative, Well-Formatted Log Messages

When a test fails, the error message shouldn’t leave developers guessing - it needs to tell the full story right away. That means delivering a neatly formatted log that clearly contrasts the expected value (want) with the actual value (have), so the mismatch is immediately obvious. A vague or cluttered message is a time sink, forcing developers to dig through code or rerun tests just to figure out what went wrong. On the other hand, a crisp, informative log acts like a spotlight, pointing straight to the problem and saving precious debugging time. My goal is to craft messages that not only highlight the failure but also provide enough context - like variable names or data types - to make fixing it as painless as possible. After all, a well-designed error message isn’t just a report; it’s a tool to keep workflows smooth and frustration low.

I'm thinking about messages like this:

// assert.Equal(42, byte(42))

expected values to be equal:  
      want: 42  
      have: 0x2a ('*')  
 want type: int  
 have type: uint8

Basic Assertions

The assert package will be the backbone of this testing module, and it needs to cover at least 90% of the typical use cases developers run into day-to-day. In these early stages, I’m starting with the essentials - scenarios I encounter regularly in my own work, like equality checks (assert.Equal), nil checks (assert.Nil), and basic boolean assertions. These are the bread-and-butter tests that pop up everywhere, and getting them right sets a solid foundation. From there, I’ll build out the package iteratively, refining it based on real-world feedback and evolving needs. The goal isn’t just to check boxes but to make assertions so intuitive and reliable that developers can write tests quickly without second-guessing the tools. Over time, this focused approach will ensure the module grows into something that feels indispensable, handling the common cases effortlessly while leaving room for more advanced features down the line.

Configurable

Flexibility isn’t just a nice-to-have - it’s a cornerstone of this module. I want developers to feel like they can mold it to suit their unique needs, whether that’s skipping specific fields during comparisons, registering custom checkers for their own types, or fine-tuning how those handy data trails are generated. Configuration isn’t about overwhelming users with options; it’s about handing them the reins to adapt the tool to their workflows seamlessly. For instance, if a struct has fields that don’t matter for a test, they can opt to ignore them without cluttering the output. Or if they’re working with a quirky custom type, they can plug in a tailored checker to handle it just right. To me, this kind of control is empowering - it transforms the module from a rigid framework into a versatile ally that bends to fit the way developers already work, rather than forcing them to adjust. And that flexibility sets the stage for extensibility, where developers can take this adaptability even further by building their own custom features on top.

Extensible

If configurability is about fine-tuning the module, extensibility is about opening the door wide for customization. I want this module to serve as an open invitation—a foundation that empowers developers to craft their own test helpers and tools, tailored to their unique ideas and needs. To make that happen, I’m including a set of building blocks: helper functions, assertion templates, and value dumpers that turn any type into a readable format. With these, anyone can craft their own test utilities, whether it’s a niche assertion for a specific use case or a custom log formatter that fits their style. ExtensibilitImage descriptiony isn’t just a feature - it’s a promise that the module can evolve alongside its users, growing more powerful as they add their own flair. My goal is to strike a balance: provide a solid foundation that’s ready to use out of the box, while leaving plenty of room for developers to extend it into something uniquely theirs.

Mocking

A testing module isn’t truly complete without solid mocking support - it’s a non-negotiable for serious testing. Mocking lets developers isolate dependencies, swap out real implementations with controlled fakes, and dig into those tricky edge cases that are otherwise tough to replicate. I’ve been burned before by tests that flaked out because of tangled external systems, and I’m determined to spare others that frustration. That’s why I’m building a robust mocking library into this module, designed to make the process as painless as possible. Whether it’s stubbing out a database call or simulating a flaky network, the goal is to give developers a simple, reliable way to create mocks that just work. It’s about stripping away complexity so they can focus on testing their logic, not wrestling with setup - and that’s where a mock generator comes in to take the heavy lifting even further.

Mock Generator

Hand-writing mocks might be manageable for a small test suite, but it quickly turns into a tedious, error-prone slog as projects grow. I’ve spent too many hours tweaking mock implementations by hand, only to miss a method or typo my way into a subtle bug-there’s got to be a better way. That’s why my module will include a mock generator that automatically creates mocks from interfaces, saving time and cutting down on human error. It’s a tool designed to churn out reliable, flexible, and ready-to-use mocks with minimal effort, so developers can focus on writing tests instead of wrestling with boilerplate. For me, this is a must-have to scale test coverage efficiently - whether you’re mocking one dependency or a dozen, it keeps the process smooth and mistake-free, building on the mocking support to make testing even more streamlined.

Golden Files

Comparing long strings, multiline outputs, or JSON blobs manually is a hassle without golden files. Basic support for them will let developers set expected outputs and check results easily, catching regressions without extra effort. For example, when testing a function that generates a big configuration file, you can save the correct version as a golden file and compare it to the output each time. Or if you’re working on an API that returns complex JSON, a golden file ensures the structure and data stay consistent. It’s a simple way to make testing these cases faster and more reliable in day-to-day work.

Test Kit

To wrap things up, I’m adding a tstkit package packed with utilities to make test writing faster and more readable. It’ll include handy helper functions to reduce repetitive code. The idea is to smooth out the rough edges of testing, making it less of a chore and more of a breeze. It’s all about giving developers practical shortcuts to keep their focus on the logic, not the busywork.

Closing Thoughts

This is just the beginning of my journey to build a Go Testing Module from scratch, and I’m excited to see where it takes me. I’ve laid out the vision - readable tests, no dependencies, and a toolbox that grows with its users - and now it’s time to roll up my sleeves and make it real. Each step will bring its own challenges and trade-offs, and I’ll be sharing them all here as I go. Stick around for the ride! In the next post, we’ll dive into the first real hurdle: designing readable tests for the module itself when the assertion library we need doesn’t exist yet. How do we write clean assertions without the tools we’re building? It’s a classic chicken-and-egg puzzle, and I can’t wait to unpack how we’ll crack it.

I’d love for you to check out the progress on Go Testing Module - head over to the GitHub repository to see the code and documentation in action. Feedback is always appreciated, whether it’s a suggestion, a bug report, or just your thoughts on the approach. Open an issue on GitHub or drop a message on X.

Stringify with Style: a Configurable Go Package for Value Dumping

Rafal Zajac — Tue, 18 Mar 2025 18:25:23 +0000

As a Go developer, I’ve often faced the frustration of comparing complex data structures during testing or debugging sessions. Nested structs, maps with mixed types, or recursive types can turn a simple equality check into a headache. Go’s built-in reflect.DeepEqual is a start, but when it fails, it leaves you guessing why two values differ. That’s where the dump package steps in — a utility that transforms any Go value into a human-readable string, making differences easy to spot, especially with diff tools. After wrestling with these challenges myself, I created the dump package to simplify the process, and I’m excited to share how it can help you.

The dump package is part of the Ctx42 Testing Module, an evolving project aimed at building a flexible, developer-friendly testing framework for Go. In this article, I’ll walk you through its features, show you how to use it effectively, and explain why it’s a game-changer for testing and debugging in Go.

What is the dump Package?

The dump package, available at github.com/ctx42/testing/tree/master/pkg/dump, provides a configurable way to serialize any Go value — whether it’s a simple integer, a nested struct, or a recursive data structure — into a human-readable string. This is invaluable in testing, where comparing complex values often demands more than a boolean result. By rendering values as strings, the dump package lets you use string comparison or diff tools to quickly pinpoint discrepancies, offering clarity where reflect.DeepEqual falls short.

Basic Usage

Getting started with the dump package is straightforward. Using its default configuration, you can dump a value with minimal setup. Here’s an example with a struct from the types package:

package main

import (
    "fmt"
    "time"
    "github.com/ctx42/testing/internal/types"
    "github.com/ctx42/testing/pkg/dump"
)

func main() {
    val := types.TA{
        Dur: 3,
        Int: 42,
        Loc: types.WAW,
        Str: "abc",
        Tim: time.Date(2000, 1, 2, 3, 4, 5, 0, time.UTC),
        TAp: nil,
    }

    have := dump.Default().Dump(val)
    fmt.Println(have)
}

Output:

{
    Int: 42,
    Str: "abc",
    Tim: "2000-01-02T03:04:05Z",
    Dur: "3ns",
    Loc: "Europe/Warsaw",
    TAp: nil,
}

The default configuration produces a nicely formatted, multi-line string. Fields are listed in the order they’re declared in the struct, ensuring consistent output for reliable comparisons.

Configuration Options

One of the dump's strengths is its configurability. You can tweak how values are rendered to fit your needs. Here are the key options, each with practical examples:

Flat Output

For a compact, single-line representation, use the dump.Flat option — ideal for logs or quick comparisons:

val := map[string]any{
    "int": 42,
    "loc": types.WAW,
    "nil": nil,
}

cfg := dump.NewConfig(dump.WithFlat)
have := dump.New(cfg).Any(val)
fmt.Println(have)

Output:

map[string]any{"int": 42, "loc": "Europe/Warsaw", "nil": nil}

When dumping maps, keys are sorted (when possible) to ensure consistent output.

Custom Time Formats

Customize how time.Time values appear with the dump.WithTimeFormat option. This is great for aligning with your preferred timestamp style:

val := map[time.Time]int{
    time.Date(2000, 1, 2, 3, 4, 5, 0, time.UTC): 42,
}

cfg := dump.NewConfig(dump.WithFlat, dump.WithTimeFormat(time.Kitchen))
have := dump.New(cfg).Any(val)
fmt.Println(have)

Output:

map[time.Time]int{"3:04AM": 42}

Pointer Addresses

By default, pointer addresses are hidden, but you can reveal them with the dump.WithPtrAddr option — useful for distinguishing between instances:

val := map[string]any{
    "fn0": func() {},
    "fn1": func() {},
}

cfg := dump.NewConfig(dump.WithPtrAddr)
have := dump.New(cfg).Any(val)
fmt.Println(have)

Output (example addresses):

map[string]any{
    "fn0": <func>(<0x533760>),
    "fn1": <func>(<0x533780>),
}

Custom Dumpers

For ultimate flexibility, define custom dumpers to control how specific types are serialized. A custom dumper is a function matching the dump.Dumper signature:

type Dumper func(dmp Dump, level int, val reflect.Value) string

Here’s an example that renders integers as hexadecimal values:

var i int
custom := func(dmp dump.Dump, lvl int, val reflect.Value) string {
    switch val.Kind() {
    case reflect.Int:
        return fmt.Sprintf("%X", val.Int())
    default:
        panic("unexpected kind")
    }
}

cfg := dump.NewConfig(dump.Flat, dump.WithCompact, dump.WithDumper(i, custom))
have := dump.New(cfg).Any(42)
fmt.Println(have)

Output:

2A

This feature lets you tailor the output to your specific use case, enhancing readability or compatibility with other tools.

Handling Complex and Recursive Types

The dump package excels at managing complex and recursive data structures, with built-in cycle detection to prevent infinite loops. Here’s an example with a recursive struct:

type Node struct {
    Value    int
    Children []*Node
}

val := &Node{
    Value: 1,
    Children: []*Node{
        {Value: 2, Children: nil},
        {Value: 3, Children: []*Node{{Value: 4, Children: nil}}},
    },
}

have := dump.Default().Any(val)
fmt.Println(have)

Output:

{
    Value: 1,
    Children: []*main.Node{
        {
            Value: 2,
            Children: nil,
        },
        {
            Value: 3,
            Children: []*main.Node{
                {
                    Value: 4,
                    Children: nil,
                },
            },
        },
    },
}

This structured output makes nested data easy to visualize and compare.

Using in Tests

The primary use case for the dump package in testing is to visualize not equal values by dumping them as part of error message or as an input to a diff tool to highlight differences.

Extensibility

Built with extensibility in mind, the dump package lets you define custom dumpers for your own types. This adaptability ensures it can evolve with your project, integrating seamlessly with your specific needs.

Conclusion

Comparing complex data structures in Go doesn’t have to be a struggle. The dump package simplifies the process by turning any value into a human-readable string, ready for comparison or diffing. Its configurability — flat output, custom time formats, pointer addresses, and custom dumpers—makes it versatile, while its handling of recursive types and testing support make it indispensable.

I encourage you to try the dump package in your next project and explore the Ctx42 Testing Modules. It’s an evolving toolset, and your feedback or contributions could help shape its future. Let’s make testing in Go simpler, more reliable, and—yes—even enjoyable!

Testing Go Test Helpers

Rafal Zajac — Sat, 15 Mar 2025 17:31:43 +0000

If you've spent any time writing Go tests, you've probably encountered the joy of *testing.T. It's the backbone of Go's testing framework - powerful, flexible, and ubiquitous. But as your test suite grows, you might find yourself repeating the same chunks of test logic across multiple test cases. To streamline your tests, improve readability, and reduce complexity you decide to move those chunks to reusable functions called test helpers. Various assert libraries are prime examples of test helpers, turning verbose checks into concise assertions.

But here's the catch: how do you test the test helpers themselves? After all, these are the tools you rely on to ensure your code works as expected. If they fail, your tests might silently lie to you. This is where the tester package comes to the rescue. In this article, we'll explore why testing test helpers matters and how the tester package makes it possible - and even enjoyable.

Test Helpers Are Code Too

Let's start with a simple example. Imagine you've written a test helper to check if a number is odd:

// IsOdd asserts "have" is odd number. Returns true if it is,
// otherwise marks the test as failed, writes error message to 
// the test log and returns false.
func IsOdd(t *testing.T, have int) bool {
  t.Helper()
  if have%2 == 0 {
    t.Errorf("expected %d to be odd", have)
    return false
  }
  return true
}

It takes a *testing.T instance (aka test manager, or test context), marks itself as a helper with call to t.Helper method, and either returns true on success or logs an error or returns false based on the input. It's simple, reusable, and makes your tests cleaner. You might use it like this:

func Test_Something(t *testing.T) {
  if !IsOdd(t, 3) {
    t.Log("additional log message or more assertions")
  }
}

Great, right? But what if there's a bug in IsOdd? Maybe the modulo check is backwards, or the error message is misleading. How do you ensure this test helper behaves as expected? You can't just trust it - you need to test it. This is tricky because *testing.T is deeply tied to the Go test runner, making it impossible to mock or inspect its behavior programmatically.

The `tester` Package

The tester package solves this problem by introducing two key components: the T interface and the Spy struct. Together, they let you test your test helpers with precision and confidence.
The tester.T interface is a curated subset of *testing.T's methods - things like Errorf, Fatal, Log, Helper, Cleanup and others to allow mocking.

// T is a subset of [testing.TB] interface.
type T interface {
   Cleanup(func())
   Error(args ...any)
   Errorf(format string, args ...any)
   Fatal(args ...any)
   Fatalf(format string, args ...any)
   FailNow()
   Failed() bool
   Helper()
   Log(args ...any)
   Logf(format string, args ...any)
   Name() string
   Setenv(key, value string)
   Skip(args ...any)
   TempDir() string
   Context() context.Context
}

Any test helper that works with *testing.T can work with tester.T, as long as it sticks to methods supported by tester.T. This means you can test IsOdd helper by first refactoring it to use tester.T:

// IsOdd asserts "have" is odd number. Returns true if it is,
// otherwise marks the test as failed, writes error message to 
// the test log and returns false.
func IsOdd(t tester.T, have int) bool {
  t.Helper()
  if have%2 == 0 {
    t.Errorf("expected %d to be odd", have)
      return false
    }
  return true
}

Then writing tests for it using Spy instance.

Spy Your Test Helpers

The real magic happens with tester.Spy. This struct implements tester.T and acts as a spy - it tracks every interaction your test helper has with the test manager. Want to know if t.Helper was called? If an error was logged? If a cleanup function was registered? Spy has you covered.

Here's how you might test IsOdd using Spy:

func Test_IsOdd(t *testing.T) {
  t.Run("error is not odd number", func(t *testing.T) {
    // --- Given ---

    // Set up the spy with expectations
    tspy := tester.New(t)
    tspy.ExpectError()                              // Expect an error.
    tspy.ExpectLogEqual("expected %d to be odd", 2) // Expect log.
    tspy.Close()                                    // No more expectations.

    // --- When ---
    success := IsOdd(tspy, 2) // Run the helper.

    // --- Then ---
    if success { // Verify the outcome.
      t.Error("expected success to be false")
    }
    tspy.AssertExpectations() // Ensure all expectations were met.
  })

  t.Run("success is odd number", func(t *testing.T) {
    // Given
    tspy := tester.New(t)
    tspy.Close()

    // When
    success := IsOdd(tspy, 3)

    // Then
    if !success {
      t.Error("expected success to be true")
    }

    // The `tspy.AssertExpectations()` is called automatically.
  })
}

In this example, Spy lets you:

Define expectations (e.g., "a t.Error() should be called", "a message should be logged").
Run the helper with a controlled test manager.
Verify both the helper's return value and its interactions with the test manager.

If IsOdd doesn't behave as expected - say, it forgets to call t.Helper() or logs the wrong message - tspy.AssertExpectations() will fail the test, pinpointing the issue.

Why This Matters

You might be thinking: "Do I really need to test my test helpers? They're simple!" But simplicity doesn't guarantee correctness. Test helpers are code, and code can have bugs. A subtle mistake in a helper could cascade across dozens of tests, leading to false positives (passing tests that should fail) or false negatives (failing tests that should pass). By testing your helpers, you build a stronger foundation for your entire test suite.

The tester package makes this process practical:

Flexibility: The T interface ensures your helpers are portable and testable.
Precision: Spy lets you set fine-grained expectations, from method calls through log messages to cleanup calls.
Confidence: You can trust your helpers because you've verified their behavior.

Beyond the Basics

The tester package doesn't stop at simple error checks. With Spy, you can:

Verify cleanup functions are registered and executed (ExpectCleanups, Finish).
Match log messages with exact strings, substrings, or regex patterns (ExpectLogEqual, ExpectLogContain, ExpectLogNotContain).
Inspect temporary directories created by TempDir (GetTempDir).
Even ignore logs when they're irrelevant (Spy.IgnoreLogs).
And many more.

This depth makes it invaluable for testing complex helpers - think assertion libraries or setup/teardown utilities.

Test Smarter, Not Harder

Testing test helpers might sound like overkill, but it's a small investment with a big payoff. The tester package empowers you to treat your helpers as first-class citizens in your codebase, ensuring they're as reliable as the code they test. Next time you write a helper, don't just use it - test it with tester. Your future self (and your test suite) will thank you.

Want to dive deeper? Check out the full documentation for the tester package and start spying on your test helpers today!

DEV Community: Rafal Zajac

Crafting Go Testing Module: Step 4 - Goldy and Must

The goldy Package

What’s a Golden File?

Using goldy in Tests

Why goldy Matters

The must Package

Exploring must Functions

A Word of Caution

Closing Thoughts

Crafting Go Testing Module: Step 3 - Testing the Test Helpers

Why Test Testing Tools?

The Challenge of Testing Affirmations

A Solution

Adapting Affirm Helpers

Writing Tests with Spy

Trade-Offs and Reflections

Closing Thoughts

Crafting Go Testing Module: Step 2 - Core

The Chicken-and-Egg Problem

The core Package

IsNil

WillPanic

Same

The affirm Package

Closing Thoughts

Crafting Go Testing Module: Step 1 - Requirements

Why?

Requirements

No External Dependencies

Well-Documented

Asserting Composite and Recursive Types

Informative, Well-Formatted Log Messages

Basic Assertions

Configurable

Extensible

Mocking

Mock Generator

Golden Files

Test Kit

Closing Thoughts

Stringify with Style: a Configurable Go Package for Value Dumping

What is the dump Package?

Basic Usage

Configuration Options

Flat Output

Custom Time Formats

Pointer Addresses

Custom Dumpers

Handling Complex and Recursive Types

Using in Tests

Extensibility

Conclusion

Testing Go Test Helpers

Test Helpers Are Code Too

The tester Package

Spy Your Test Helpers

Why This Matters

Beyond the Basics

Test Smarter, Not Harder

The `goldy` Package

Using `goldy` in Tests

Why `goldy` Matters

The `must` Package

Exploring `must` Functions

The `core` Package

The `affirm` Package

The `tester` Package