[hannasm]

I like the idea of this article but I would say that it's actually integration tests that are documentation.

When learning a new codebase, and I'm looking for an example of how to use feature X I would look in the tests first or shortly after a web search.

It seems to me like the second half of this article also undermines the main idea and goal of using unit tests in this way though.

  > Descriptive test name, Atomic, Keep tests simple, Keep tests independent

A unit test that is good at documenting the system needs to be comprehensive, clear and in many cases filled with complexity that a unit test would ignore or hide.

A test with a bunch of mocks, helpers, overrides and assumptions does not help anyone understand things like how to use feature X or the correct way to solve a problem with the software.

There are merits to both kinds of tests in their time and place but good integration tests are really the best ones for documenting and learning.

[Terretta]

Executable documentation:

Hitchstory is a type-safe StrictYAML python integration testing framework exploring some interesting ideas around this.

https://hitchdev.com/hitchstory/

Example:

https://hitchdev.com/hitchstory/using/behavior/run-single-na...

Source:

https://github.com/hitchdev/hitchstory/blob/master/hitch/sto...

See also the explanation of self-rewriting tests:

https://hitchdev.com/hitchstory/why/rewrite/