The behavior of an application is defined at three levels: in the code, in the documentation and in the tests.

This approach allows you to define the behavior in only one place, the code.

The documentation is generated and serves as a reference to ensure non regression.

It’s a mix between living documentation Golden Master (or characterization-testing]) and Behavior Driven Development.

We used to say that tests are the first documentation.
But a test often looks like that:

@Test
public void player_A_won_1_point_and_then_player_B_win_2_points() {
    game.pointA();
    game.pointB();
    game.pointB();
    assertEquals("15-30", game.score());
}

Is it really what we want as documentation ?
Is it easy to read and to understand for every one in the project ?

Don’t you think it will be a better documentation if this test look like that ?

Tennis

Player A

✔

15 - 30

Player B

✔

✔

Here, what resources you can find on this site

More explanation

You want to have more information of the concept, the idea, the history, …​

video (10mn in french)

Just try it

We explain how to experiment whatever your language.

Some examples

We will present some documentation. That shows how we can present some information in a documentation that is also a test.

Tools

Tools, full discussions and choices

Java, Python, …​

Full project documentation is here: https://sfauvel.github.io/documentationtesting

Repository github: https://github.com/sfauvel/documentationtesting/tree/master