Building a Portable Testing Rig with GoConvey and Docker

Editor's Notes

• #2: Hi! Thank you all for being here today. This is my talk on better and more fun testing in Go with Docker and GoConvey. And, I have to say, I was a little concerned Bryan was going to steal my thunder earlier, but since he only had one slide on GoConvey, he’s forgiven.
• #4: But before we get into this, I have a confession to make… I’m not really a Go programmer. I’m a Python and Node.js programmer. In fact, I’m probably the only speaker on stage today who also attended Mark’s awesome “Intro to Go” workshop yesterday. That said, what I hope to bring here is a bit of a Go newbie’s fresh perspective. Something else I DO have a lot of experience with... is testing.
• #5: At 18F, I was co-organizer of our Automated Testing Workgroup, which was a group centered around testing techniques and best practices. I’m sure I’m preaching to the choir here, but testing is important. Testing makes our code smarter. I believe it even makes _us_ smarter developers. When we test, we end up building better interfaces. Our modules become more decoupled. We also avoid regressions, so we can confidently ship software, and… by the way, *hands up* who here enjoys manually testing your software every time you make a change?
• #6: Since it’s so important, testing should be easy and FUN. Which means that any testing framework should be, at a MINIMUM: *lightweight, *require minimal changes to our codebase, *include the option to fail fast, meaning the test run stops at the first failure, so we don’t have to wait for the whole suite to finish running; *it should be colorful, so it’s easy to visually scan the test output. Annnd another really great feature to have is autotesting, so our tests watch for code changes, and re-run live, as soon as we make changes. By the way, since you’re probably wondering, that photo is of a real test rollercoaster, so it’s LITERALLY TESTING FUN. And safety…. (It’s from a company in Italy called Ride Tek, which designs rollercoasters. You can read about it on Wikipedia.)
• #7: So… What does all this test evangelism have to do with Go? Well, I recently found myself helping out with a golang project. And of course, the first thing I did, after cloning the repo, was to find out where the tests were located and how to run them. And the first thing I realized was: the standard go testing library is pretty SPARTAN. No colors No failfast option It didn’t support test subsets or tagging and worst of all, no autotest. But that’s ok, because that’s what 3rd-party testing frameworks are for, right? So let’s take a look at some of the options.
• #8: Looking around at libraries, I found Ginkgo, testify, gocheck, prettytest, go-spec, mao/zen, and more. But I’m not going to cover all of those, because just as I was starting to explore the landscape, my colleague, Jeff Damick, suggested that I check out GoConvey.
• #9: And GoConvey had something so unique, in my experience, that I had to try it out. That really unique feature was this:
• #10: The GoConvey Web UI. It acts like a local CI/CD server for your Go project. GoConvey runs as a daemon on your local machine, watches your code for changes, and automatically re-runs your tests while you code. This is really awesome for speeding up our development feedback loops, and reducing the barriers to testing. So, let’s take a quick tour of the UI.
• #15: Play/Pause, Retry, Test History, and a few others.
• #16: That third button, the test history, is really interesting, because it brings up another panel which shows our test histories, and lets us click on any one, to travel back in time, and inspect anything about the test run.
• #17: At the left, we have a pane which includes coverage information.
• #18: And from there, we can click on a package name to enter the coverage browser. But I’ll go over that more in a little bit.
• #19: Test failures are really well highlighted. And if you can see the little icon that looks like an eye, that will toggle to let us ignore any given module if we know we have tests that are going to fail, or for some reason we don’t want to keep rerunning them.
• #20: So, this GoConvey UI is really cool, and one of the best parts about it, is that it works with the standard go ‘testing’ module. But if you prefer, it also has a nice BDD syntax that we can use, with some pretty powerful asserts available. I won’t go into those here, but you can find a full list of the asserts on the GoConvey repo in the wiki.
• #21: So, at the beginning I promised this talk was going to include something about Docker. And in fact, this whole talk was inspired by the fact that I figured out how to get GoConvey running in a Docker container, and it was so friggin’ cool, I just had to come here and tell you all about it. In this next part, we are going to see how to run GoConvey in its own Docker container, and get many of the benefits of this framework, without ever changing our project’s code. So that’s what this is about. Our portable… testing... Rig. Let’s see how it works!
• #22: Here, I drew a little picture for you. How it works, is that you have your project repo on your laptop, and you mirror that directory into a volume on your container. And if you don’t know about volumes in Docker, when you mirror a path on the host, changes continue to be reflected live in the container, even after it’s built. That’s really the crux of how this whole thing works. The project from the host, gets mirrored into the $GOPATH in the container. The cool thing here is that $GOPATH on the host vs $GOPATH on the container are a totally arbitrary relationship. They look the same here, but they don’t have to be the same. If you hold that thought, I’ll have a little bit more to say about that later.
• #23: Here, we see the paths to two files we’re going to need to accomplish this setup, Dockerfile.testing and docker-compose.yml. So we have our two files, and this is just showing that the Dockerfile.testing file sets up the basic GoConvey build instructions, while the docker-compose.yml wraps those build instructions and injects the details of the local project into the build via some arguments.
• #24: And here is the text of those two files. With two small files, and under 35 lines of code, we get that whole working GoConvey setup, which I’ll demo for you a bit more in a minute. But next, I’ll go through each of these files in more detail, and if you want to pull down these files for yourself, just use the link at the bottom– they’re in a Gist on Github. (And don’t worry, I’m going to move on, but this link will be on a few of the next slides, and at the end, too.)
• #25: So, if we go through this file, section by section, first we have the FROM image– we’re just using a standard golang image based on the alpine Linux distro, which makes it really lightweight, and keeps the filesizes really small. Next, we have a couple of arguments– these get populated by the docker-compose file, which we’ll see in a minute– but you can see that we’re specifying a port to run on, and the app_path, which is the path to our repo (relative to the GOPATH/src directory). Then we EXPOSE the port, we RUN commands to install git as well as goconvey, and finally, we have the command which will start up the goconvey daemon. A few things to note there-- host works best as 0.0.0.0 with Docker – by default, it’s localhost, but that and 127.0.0.1 did not work in my testing. Port is self-explanatory, workDir is the path to the project we want to test, and finally, launchBrowser equals false– by default, goconvey tries to open itself in a browser for us, but since that won’t work from within the container, we turn it off to avoid an error.
• #26: Here is the docker-compose.yml. This says we’re using version three of the docker-compose syntax. We’re defining just one service, called goconvey… There’s some build info, including the context, which is our local project directory. We specify the dockerfile name, since we’re not using the default name, just to avoid conflicts with any existing Dockerfile you may have. By the way, you might need to do a similar renaming of the docker-compose file if you also have an existing one of those. (One caveat: don’t name your file Dockerfile.goconvey. GoConvey is a little dumb in this respect, and it will throw an error at you, because apparently the file pattern that it watches matches anything with ”.go” in the name ~anywhere~.) Next, we specify the args, our port is 9006, our app_path is the path to our go module. Then we have the volumes mapping, which is basically just mapping $GOPATH/src to $GOPATH/src here. Finally, we map port 9006 on the host to 9006 on the container. And that’s all it takes. Next, let’s watch how to get it running.
• #27: First, we’ll do a build.
• #28: Ok, now that it’s running, what can we do with it? Let’s see how autotesting works. I’ll fix a test failure and you can see the web interface re-run the tests and update in almost real-time. END: “There we go. It’s already back to passing. I didn’t even have to reload the page or trigger anything, other than saving my Go file.”
• #29: Next, let’s check out that cool test history inspector, that’s kind of like our build history in a CI/CD system. (Might re-run this one a second time)
• #30: This is one of my favorite parts– the coverage browser.
• #31: Ok, last demo: that web ui can take up a lot of screen real estate, but it doesn’t have to. The interface is built to be fully responsive, so you can shrink it down and have it display side-by-side with your editor, if you like.
• #32: So, to reiterate, you can have a portable testing rig with GoConvey and Docker, everything I showed you above, with just two small files dropped in to your project.
• #33: So the really great thing about this is– if you’re just helping out, or just checking out a Github repo, you can use this anytime, to get a more responsive testing experience, without installing a single go package or changing a single line of the code base.
• #34: Keeping GoConvey in a separate container from your app follows the principle of one process per container. And if you already have a docker-compose file, you can just specify them both with the –f flag on the command line, and it should all work.
• #35: Use Docker and clone your repos where you will!
• #36: This neat trick has its limits, I must admit… [READ SLIDE] But if you want the feeling of a local CI/CD system as you develop, and you want to be able to use it on any project you touch, you can use this portable testing rig setup! In fact, you may even be able to build the image once, push it to a docker registry, then bring nothing but the docker-compose file from project to project. I haven’t tried this myself, but it should be possible. In addition, I’m sure there are some improvements that could be made to those Docker files that I posted. And if you find any, get in touch, I’d love to hear about them!
• #37: And that’s all. Thank you! Once again, there’s the link to the Gist for the files, I’m arowla on Twitter, and… I wish you happy and fun testing!