Documentation testing

To have more information, you can visit complete documentation.

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		✔	✔