Define test code conventions for Scribe Android app

[albendz]

Terms

• [X] I have searched open and closed feature requests
• [X] I agree to follow Scribe-Android's Code of Conduct

Description

Summary

The codebase needs a set of coding conventions for writing unit tests to help manage unit test organization and help people understand how to test. This includes:

• When a new class is needed and where it goes in the project structure
• How tests should be named
• A recommendation on scope for a test

This issue is done when: a summary of recommendations is added to the CONTRIBUTING.md file.

Suggestions

Feel free to take or leave these.

There are many good ways to choose options for these recommendations. Here are a few I like:

• Unit test classes are usually 1:1 (Activity.kt has ActivityTest.kt) but occasionally the files get too big and they need to be split up by scenario. Initial suggestion is to still go with 1:1 - one test file for each source file
• There are a lot of test naming conventions for JUnit tests. My favorite convention is:

@Test
fun `WHEN call isEmpty on an empty string THEN return true`() {}

using the backtick syntax for kotlin functions (this is only allowed in test code). I like that this is more BDD but you'll definitely hit some long-method violations for very complicated cases.

• A few others:
  • testIsEmptyOnEmptySuccess
  • testIsEmptyOnEmpty_returns_true
• Another way to organize test naming is to use @Nested JUnit tests. It can help organize test classes where there are clear groups of functionality.
• For test scope, usually it is best to have one test method for one test case but you can end up with hundreds of methods that all have identical setup, particularly where there are a lot of if statements or boolean conditions in a given method. In this case, @Nested tests can also help. I suggest starting simple and recommending 1 function per test case and it's up to reviewers and contributors to make the call on whether a function has too much scope or not.

Contribution

No response

[KesharwaniArpita]

Hi @albendz I am interested in this issue!

[Linfye]

@andrewtavis Can this issue be closed? 😊

[andrewtavis]

I'll let @angrezichatterbox and @albendz weigh in on if further work is needed here or if we should open up a new issue now for the next steps :)

Thanks for the ping, @Linfye!

[angrezichatterbox]

It is fine. As far as the conventions more could be added as we write some tests going forward. @albendz Happy to hear your opinion on this.