Yesterday I needed to test something at work. We have an event driven distributed system, and I wanted to verify that a small part of it I’d just deployed worked as expected when the trigger event was emitted. I could have elected to just manually publish a suitable event, but I’ve found that all too often this results in subtle yet meaningful differences from what happens when the emitting services themselves actually do so. In this instance, the originating service was one supporting a specific file import, so all I needed was a valid CSV to feed it. But what did that CSV need to look like?
My first attempt at answering that question led me to our internal wiki, where we try and document the various features and processes comprising our platform. Unfortunately, as is frequently the case on software teams—and particularly small, fast moving ones—documentation didn’t quite provide the answer I needed. I found what appeared to be the original project brief which discussed what the import needed to support, but not specific columns or sample files.
My next reflex was to look at the code. After all, that’s the actual truth, right? In this case, there wasn’t an easy to find section where an exhaustive list of columns was parsed out for me to reference, and anyway I rather quickly thought of a better route.
The better route were the tests. We have a pretty decent habit of writing tests for most of our backend code, and at the very least basic happy path smoke tests are usually present. I looked for the tests for this import service, found them, and voilà—there it was, a fixture generating a fake CSV with everything I needed.
From that point it took me less than a minute to write out a CSV with the kind of data I could use for my needs, and it worked like a charm.
So yes, if you’re writing automated tests for your code, they can serve as documentation on how to use it. If you run them constantly—like via continuous integration—they’ll actually be validated pretty often. And if you think about this while writing said tests, it might inspire you to make them even more useful.
Thanks for reading! You can keep up with my writing via the feed or newsletter, or you can get in touch via email or Mastodon.