tests: improve documentation

Closes #711
below