| 1 | = Purpose, goals = |
| 2 | * built-in, very easy testing |
| 3 | * gain exactness |
| 4 | * good diagnostics |
| 5 | |
| 6 | = Definition = |
| 7 | * series of discrete operations with boolean result, marked as tests |
| 8 | |
| 9 | = Syntax = |
| 10 | == overall structure == |
| 11 | - plan(2); tests; # done |
| 12 | - plan(*); tests; tests-done(); # names subject to discussion ;-) |
| 13 | |
| 14 | == single tests == |
| 15 | we have two proposal: |
| 16 | |
| 17 | === adverb on operators === |
| 18 | $x eq 'foo' :ok('Test descriptions'); |
| 19 | $x == 23 :ok('explicit numeric test'); |
| 20 | ?$x :ok<stuff> # used to be ok($x, 'stuff'); |
| 21 | try { dispatch() } :ok<...> # used to be lives_Ok { ... }, '...'; |
| 22 | (it was also proposed to name it :test instead of :ok) |
| 23 | pros: |
| 24 | * good diagnose of output |
| 25 | * force exact comparison semantics |
| 26 | * no pollution of namespace |
| 27 | cons: |
| 28 | * have to auto-generate ops with adverbs |
| 29 | * more complicated grammar needed |
| 30 | * the fact that a line contains a test is somewhere in the |
| 31 | middle, so not too obvious |
| 32 | |
| 33 | === normal sub calls, like now === |
| 34 | ok $x eq 'foo', 'description'; |
| 35 | dies_ok { ... }, 'description'; |
| 36 | pros: |
| 37 | * easier to implement |
| 38 | * it's been proven to work out well |
| 39 | * visually tests are very easy to spot |
| 40 | cons: |
| 41 | * it's *very* hard to get good diagnostics out of failed tests |
| 42 | (advanced macro fiddling needed) |
| 43 | * clutters up namespace |
| 44 | * if we don't deprecate is(), we have to find sane comparison |
| 45 | semantics, fix up the tests (we have to do that anyway...) |
| 46 | and educate our test writes. Currently infix:<eqv> is a |
| 47 | candidate (advocated by pmichaud, because it's very dwimmy), |
| 48 | infix:<eq> being another (advocated by mority, because it's |
| 49 | very simple and easy to explain). |
| 50 | |
| 51 | = Backends and standard backend = |
| 52 | |
| 53 | * all the test logic should be easily overridable (for example for storing |
| 54 | test results in a db, or different test output format) |
| 55 | * simplest idea: |
| 56 | there's a Test::Backend object in $*TEST_BACKEND, and plan() class |
| 57 | the .plan method, :ok('...') adverbs on ops call. |
| 58 | * the default backend will emit TAP output |
| 59 | * the default backend will consider a test run failed if any single test |
| 60 | failed, or in case of plan mismatch |