Re^2: Using Test::More to make sense of documentation

The goals of experimentation are different than the goals of testing. In test mode, you propose an output and verify that the actual output is "as expected". This, as you note, takes a lot of understanding of the module.

However, in experimental mode, you start with a goal and consider various possible inputs and incantations that might result in the desired output. It is exploratory, not predictive. For failures, Test::More::is prints out a lot more than just "not ok". In fact, it prints out the right result, so it can be a good way to "see what happens".

An alternative see-what-happens technique is the command line or a REPL (read-eval-print-loop). Both are very good tools for small clarifications. REPL's don't run into quoting problems like the command line does. However, both have several other limitations: repeated setup, lack of annotations, inability to repeat what you did last week, inability to repeat en-mass a batch of trials with different inputs, and so on.

$& - agreed. But that wasn't the point of the example and I apologize if it wasn't clear. The point was really to show

how to test an incantation where the goal isn't simply the output of a subroutine (via eval)
an experimental approach. The intent was to give a sampling of the kinds of mistakes one might make while feeling one's way to understanding how capturing and back-references work.
being able to keep an annotated history of what does and doesn't work. A command line or REPL provides some short-term history, but no annotations you can go back to weeks later.
the ability to repeat experiments en-masse for new input by encapsulating a set of tests in a subroutine.

Best, beth

Comment on Re^2: Using Test::More to make sense of documentation Select or Download Code

Replies are listed 'Best First'.
Re^3: Using Test::More to make sense of documentation by gwadej (Chaplain) on May 01, 2009 at 17:10 UTC
I've sometimes used the inverse of this (reading the tests to understand the intended usage), but had never thought of it as an exploratory technique. Further consideration suggests that these experimental test files might be useful to the author, in at least two cases: when reporting a code bug or patch. when reporting a documentation bug or patch. The first of these is recommended practice, but the second might also be useful. When receiving a documentation patch or question, it's sometimes hard to tell why the person asking the question doesn't understand my <sarcasm>perfectly clear and understandable</sarcasm> documentation. I can see the test file containing your experiments being very useful in making assumptions and misconceptions slightly clearer. While some might argue that this isn't the best way to learn an interface, I think you have added another tool to my learning toolbox. G. Wade	[reply]

Replies are listed 'Best First'.

Re^3: Using Test::More to make sense of documentation
by gwadej (Chaplain) on May 01, 2009 at 17:10 UTC

I've sometimes used the inverse of this (reading the tests to understand the intended usage), but had never thought of it as an exploratory technique. Further consideration suggests that these experimental test files might be useful to the author, in at least two cases:

when reporting a code bug or patch.
when reporting a documentation bug or patch.

The first of these is recommended practice, but the second might also be useful. When receiving a documentation patch or question, it's sometimes hard to tell why the person asking the question doesn't understand my <sarcasm>perfectly clear and understandable</sarcasm> documentation. I can see the test file containing your experiments being very useful in making assumptions and misconceptions slightly clearer.

While some might argue that this isn't the best way to learn an interface, I think you have added another tool to my learning toolbox.

G. Wade

[reply]