Agreed. The test suite should be a first class part of a module's documentation. Being executable ensures that it is always kept up to date.

Having a nicely commented test for each example given in the module's documentation ensures the examples actually work and allows the test suite to be usefully browsed as tutorial material.