Fixing Go Unit Test Problems: When Your Code Just Stops!

Have you ever tried to test your computer program, and it just stops and says "panic: test timed out"? It's like trying to get your friend to talk, and they just stare blankly into space for 30 seconds. It's super annoying, especially when you think your code should be working!

I recently built a simple chat program in Go, kind of like an old-school Netcat. When I tried to test it, I kept running into this "test timed out" message. It felt like my tests were stuck in quicksand!

This story is the first part of how I fixed these tricky problems. We'll focus on how I got my chat program's client (the part people use to type messages) to work with the tests.

What Does "Panic: Test Timed Out" Even Mean?

When you run tests in Go, the computer gives each test a certain amount of time to finish, usually about 30 seconds. If a test doesn't finish in that time, the computer gets impatient and stops the test, yelling "panic: test timed out".

So, why does this happen? Most of the time, it's because:

• Your code is waiting forever: Imagine your program is trying to read a message from someone, but that message never comes. Your program just sits there, waiting and waiting.
• Hidden helpers are stuck: You might have small helper programs (called "goroutines" in Go) running in the background. If one of these helpers gets stuck in a loop or waits forever for something, your main test can't finish.
• Everyone is waiting for someone else: Sometimes, two parts of your program are both waiting for the other to do something, and neither can move. This is called a "deadlock."

When you see that "panic: test timed out" message, look at the messy text that comes after it. It shows you where in your code different parts of the program were stuck. For example, you might see "net.(*pipe).read", which tells you your program was stuck trying to read from a connection.

Our Secret Weapon: net.Pipe() for Easy Testing

Testing programs that talk over a network can be hard. You don't want your tests to rely on real internet connections or actual network parts, because that makes them slow and sometimes they just don't work right. This is where net.Pipe() becomes a super helper!

net.Pipe() creates a fake, in-memory connection right inside your computer's memory. It acts just like a real network connection but is much faster and more reliable for tests. It has two ends: a "server" end and a "client" end.

For my chat program, I used server, client := net.Pipe(). I would give the server end to the part of my program that handles clients (my HandleClient function). Then, in my test, I would use the client end to pretend I was a user typing messages or receiving them. This made my tests much cleaner and faster.

Solution 1: SetReadDeadline - No More Endless Waiting!

One big reason my tests timed out was because my HandleClient function would just sit there waiting for the client to send a name or a message. If my test didn't send anything fast enough, HandleClient would never finish, and the test would crash.

The cool fix for this is net.Conn.SetReadDeadline(time.Now().Add(duration)). This line tells the computer: "Hey, if you're trying to read something from this connection, only wait for this much time." If nothing comes in that time, it will give an error instead of just waiting forever.

Here's a simple idea of how I used it in my tests:

// Before trying to read, tell it to only wait 2 seconds
client.SetReadDeadline(time.Now().Add(2 * time.Second))

// ... then try to read the message ...

// Important: If you don't need a deadline anymore, or you're about to write,
// it's good to reset it so it doesn't cause problems later.
client.SetReadDeadline(time.Time{})

When the deadline runs out, you'll get a special error. You can check for this error in your code to know that a timeout happened.

Important tip: Use SetReadDeadline every time you expect to read something and want to make sure it doesn't wait forever. It makes your tests much more predictable!

Solution 2: Channels for Teamwork - No More Guessing with time.Sleep

Another problem that made my tests tricky was using time.Sleep(). This tells your program to pause for a certain amount of time, like time.Sleep(100 * time.Millisecond). But how do you know if 100 milliseconds is enough? What if the computer is busy and it takes longer? What if it's too much, and your tests take forever to run? time.Sleep is like guessing, and it makes tests unreliable.

My HandleClient function runs in its own little helper program (goroutine). My tests needed to know exactly when that helper finished its job (like after a user typed "/quit") so I could check if things changed (like if the user was removed from the chat room). This is where "channels" became super useful for making my helpers work together.

I used a simple "done" channel (make(chan bool)) to tell the main test when the HandleClient helper was finished:

// Make a channel to know when HandleClient is done
done := make(chan bool)

// Start the HandleClient function in its own helper program
go func() {
    cl.HandleClient(server, "nonexistent.txt")
    done <- true // When it's done, send a message through the channel
}()

// ... now do things in the test, like sending a "/quit" message ...

// Wait for the helper to finish, but only for 5 seconds
select {
case <-done:
    // Yay! The helper finished!
case <-time.After(5 * time.Second): // If it takes longer than 5 seconds, something is wrong
    t.Fatal("Handler did not finish after quit command") // Make the test fail
}

The select part is really neat. It lets your test wait for either the "done" message from the helper or the 5-second timer to run out. This way, your test won't hang forever if the helper gets stuck.

Solution 3: Cleaning Up Your Mess

Even if your helper programs aren't stuck and your reads don't wait forever, old connections, open files, or leftover information in your program's memory can mess up other tests. This causes flaky test failures that are super hard to figure out.

Good Go tests always clean up thoroughly:

• Close connections: For every net.Conn (even the fake ones from net.Pipe()), always add defer conn.Close() right after you create it. This makes sure the connection is closed when the test is done.
• Delete temporary files: If your test makes files, like logo.txt or history.txt, use defer os.Remove(filename) to delete them when the test finishes.
• Reset global stuff: My chat program used global lists (models.Clients) and message channels (models.Broadcast). It's super important to reset these before every test. This makes sure each test starts fresh and doesn't get messed up by what happened in the previous test. I used models.Mu.Lock() and models.Clients = make(map[net.Conn]string) at the start of my tests to do this.

Real Examples: Fixing My Client Tests

Let's see how these fixes actually helped my TestHandleClientQuit and TestHandleClientBasicFlow tests.

TestHandleClientQuit

At first, this test would crash because HandleClient would get stuck waiting for a /quit command, or the test would hang trying to read something it expected.

The Fixes:

1. SetReadDeadline: I added client.SetReadDeadline(time.Now().Add(2 * time.Second)) before trying to read the chat program's welcome message (logo) and the name prompt. This made sure the test wouldn't wait forever if those messages didn't come.
2. done channel: I ran HandleClient in its own helper and used the done channel with a select statement. This way, after I sent the /quit command, the test would wait exactly until the helper program finished, not just guess with a Sleep.
3. Cleanup: I made sure to add defer client.Close() and defer os.Remove("logo.txt").

TestHandleClientBasicFlow

This test was more complex. It pretended a user joined, saw old chat messages, sent new messages, and then left. It also had timeout problems, especially when trying to read all the starting messages from the server.

The Fixes:

1. Reading with a deadline, step by step: When reading the chat history, my test needed to read many lines until a special prompt appeared. I wrote a loop that used client.SetReadDeadline for each read. I also told it to stop if it saw the end of the connection (io.EOF) or if the deadline passed (net.Error timeout). This kept the test from getting stuck if it read all the history but was still waiting for the next thing.
2. done channel: Just like the other test, I used a done channel to make sure the HandleClient helper finished its work correctly.
3. Full Cleanup: I added a final /quit command from the test side to make sure HandleClient cleaned up and exited properly, along with all the other file and connection cleanups.

After putting all these pieces in place, my client tests stopped being flaky and stuck. They became fast and reliable, showing that my chat program was working right!

Big Lessons for Better Go Tests

My time fixing these client test timeouts taught me some important things:

• Be Smart, Not Slow: Don't use time.Sleep in your tests! It makes tests slow and unreliable. Instead, use channels or sync.WaitGroup to wait for things to happen exactly when they should.
• Timeouts are Your Friends: Use SetReadDeadline for network stuff and time.After with select to set limits on how long your tests will wait. If something is taking too long, the test will quickly tell you, instead of just hanging.
• Clean Up Everything: Always close connections, delete temporary files, and reset any global information your tests use. A messy test can cause weird problems in other tests later.
• Read the Clues: When a test times out, that "panic: test timed out" message with all the messy text is your best friend. It points you right to where your program got stuck.

In the next part of this story, we'll talk about how I fixed problems with the "broadcaster" part of my chat program, which sends messages to everyone, and how to handle shared information in your program correctly. Stay tuned!

Comments

[Antony Oduor]

Great read! I didn’t know how important it was to clean up things like connections and temporary files after each test. I do try to clean up but not for this particular reason. Now I see that leaving stuff behind can cause random test problems that are hard to find. I’ll make sure to remember this for my next project.

[John Paul Nyunja]

Glad this helped