Document testing conventions

[perdasilva]

Discussed in #168

^{Originally posted by perdasilva April 14, 2023}
A recent discussion in #142 raised a couple of questions around what our unit testing conventions ought to be:

• should we still use ginkgo for unit tests or stick with gotest?
• should we default to tabular tests, singular tests, or are we happy with either?

For the sake of consistency, I'm putting this out there to our community so we can establish some best practices and conventions. IMHO:

• I think we should rollback on ginkgo for unit testing. Adds additional files (*_suite.go), it's not as nicely integrated with my IDE (or I haven't found a way to have as nice an experience as I do with gotests).
• I personally think there is a trade-off between tabular and singular tests, and I'm of the camp that thinks that for unit tests readability > conciseness (and I personally have a hard time reading tabular tests as there is a physical distance between the input and the logic). Having said that, I'm happy to default to what out community decides. Ultimately, consistency is a better goal in my mind.

Acceptance Criteria:

• document describing development conventions in /docs created
• development conventions doc covers our testing conventions:
  • No ginkgo for unit tests - use go test
  • Use tabular tests when it makes sense - call out trade-offs
  • Minimize the use of shared helper functions as they can often go forgotten
• call out specific assertion framework (e.g. testify)
• add examples for different types of well-organized tests: unit, e2e, integration
• addressed comments in this issue [e.g.]

For more info, see discussion #168

[joelanford]

Can we add a callout for using a particular assertion framework as well (e.g. testify)?

I agree with most of the points in the discussion about Ginkgo. But the one thing I've found that I like about it is that it generally encourages tests to be written in a way that adding the next test is easy because you can setup layers of contexts. With standard go tests, there are sometimes the questions of:

• "add this to an existing Test* function or create a new Test* function?"
• and the corollary, "how big/how many assertions should go in a single Test* function?"

Perhaps having the docs point out examples of well-organized tests would help?

Lastly, I'd very much like to see something that talks about how we choose between unit/integration/e2e. Not sure if that's this doc or another one though.