Document how to document tests
CodeLenny opened this issue · comments
Include a "Test Documentation" section outlining what styles of documentation are useful, and what isn't.
DO: Mention top-level test architecture (e.g. AVA) in the README.
DO: Mention test style (e.g. this guide) in the README.
DO: Call out local test resources that can help (e.g. prebuilt ConfigurableArbitrary
in the test directory) in the README.
DO: Assume that readers will scan through the dependencies in a file, and don't need any explanation about the library.
DON'T: List all test libraries/resources that are used in the repository (e.g. JSVerify, Lodash, etc.)
DO: Use test titles instead of comments.
DO: Explain lengthy or complex test architecture (in a block comment).
You may provide line-by-line comments in the test file describing the functionality of a test according to the repositories style guide for code. If you are providing these comments, write them well. Quickly written descriptions of functionality can hurt more than they help.
DO: Explain test architecture.
DON'T: Explain test implementation.
DO: Use AVA test description features (e.g. skip
, failing
) for specific purposes (describe)