style: Document gotchas when using defers with `os.Exit()`

Using `os.Exit()` will cause the calling process to exit immediately
without executing any deferred functions. In the context of our tests,
this means that any created ondisk state may not get cleaned up
correctly. This commit thus documents those pitfalls in "STYLE.md".

1 files changed, 26 insertions, 0 deletions

diff --git a/STYLE.md b/STYLE.md
index 8230c8f9d..ea3dc4132 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -223,6 +223,32 @@ func TestTime(t *testing.T) {
   [Cheney blog post]: https://dave.cheney.net/2013/06/09/writing-table-driven-tests-in-go
   [Golang wiki]: https://github.com/golang/go/wiki/TableDrivenTests
 
+### Fatal exit
+
+Aborting test execution with any function which directly or indirectly calls
+`os.Exit()` should be avoided as this will cause any deferred function calls to
+not be executed. As a result, tests may leave behind testing state. Most
+importantly, this includes any calls to `log.Fatal()` and related functions.
+
+### Common setup
+
+When all tests require a common setup, we use the `TestMain()` function for
+this. `TestMain()` must call `os.Exit()` to indicate whether any tests failed.
+As this will cause deferred function calls to not be processed, we use the
+following pattern:
+
+```
+func TestMain(m *testing.M) {
+	os.Exit(testMain(m))
+}
+
+func testMain(m *testing.M) int {
+	cleanup := testhelper.Configure()
+	defer cleanup()
+	return m.Run()
+}
+```
+
 ## Black box and white box testing
 
 The dominant style of testing in Gitaly is "white box" testing, meaning