But some didn't. In those cases, I got errors you know along the lines

t/025_some_test............ok 1/256                                   
+                 
#   Failed test in t/025_some_test.t at line 7235.
#          got: 'FOO'
#     expected: 'BAR'
# Looks like you failed 1 test of 256.
t/025_some_test............dubious                                    
+               
        Test returned status 1 (wstat 256, 0x100)
DIED. FAILED test 123
[download]

OK, fine. Invoke $EDITOR and look at line 7235. Maybe you can figure what went wrong. Maybe you can't, because the module's author has been a bit too terse for your knowledge. You could get hints from the SYNOPSIS section of the module's pod, but sometimes you just won't without grokking the entire module.

Now, as test files are valid perl files, the author could have just placed some pod along the lines of their test files. Wouldn't that be handy? You could then just say perldoc t/025_some_test.t and get a description about the test being performed, see which test does what, and an explanation of the test and maybe failure conditions. Since writing test files requires some thinking, the thoughts could just be documented by writing them as pod sections into the test files whilst composing those files. The script h2xs could write stubs for that into the initial test file.

I would advocate documenting test scripts as a First Best Practice for module authors. What do you think about it?

--shmem

update: Test files (could) give much more insight into a module's usage than can ever be placed into a module's pod without it being overburdened. That's another reason.

_($_=" "x(1<<5)."?\n".q·/)Oo.  G°\        /
                              /\_¯/(q    /
----------------------------  \__(m.====·.(_("always off the crowd"))."·
");sub _{s./.($e="'Itrs `mnsgdq Gdbj O`qkdq")=~y/"-y/#-z/;$e.e && print}