tests: improve documentation

Closes #711
`see below`