PerlUnit TODO
=============

Here's our roadmap.  It should give you an idea of what is planned,
and in some cases when it's planned for and/or who's going to do it.
Only update this file on the main branch!

See also doc/consensus.txt.

* Before release 1.0

None of these are big jobs, but Adam thinks they should all be done
before 1.0 if we want the framework to gain respect and widespread
usage; after all, many people will check out PerlUnit for the first
time when they hear 1.0 being announced, and first impressions count
for a lot.

** Rename Test::Unit::HarnessUnit and Test::Unit::UnitHarness

Not sure what to yet, but we want to get these big API changes out of
the way before we bump the version number.

*** HarnessUnit
"A Test::Unit::Runner which outputs Test::Harness-style output"

Used for most of our self-tests.

***  UnitHarness
"A makeover of Test::Harness to allow its tests to be retrofitted as
unit tests".  Seems to need some work, but is neat for running t/*.t

What uses it?  I can't see anything here, but we may have real live
(and quiet) users.

It's referenced from T:U:Loader, but only used for certain inputs.

** Get working build on 5.7.2 and 5.8.0

Now seems happy on Debian 5.8.4-2, and I'll cheerfully let the
cpan-testers find out about the others.

** Rename do_run to run_suite

in the runners.

Is this to match T:U:Procedural and T:U:TkTestRunner ?

** Tidy up copyrights, credits, and licensing

We had copyrights, licenses, and out of date author attributions in
pretty much every file in the distribution.  Tidied up 2005-07 mca.

> It would be good to move all the copyrights and credits into one or
> two files (COPYING or LICENSE or AUTHORS, say),

There are still some single-author files:

  T:U:Assertion*

  T:U:Decorator
  T:U:Setup

  T:U:Tutorial

> and then to change the licensing/credit bits and pieces in all the
> other files into something which refers to that one file, and also
> states that none of the files should be distributed separately, only
> as an entire package, thereby preventing the copyright-containing
> file from being disassociated from the others.

Well I've done a chunk of that.  It's not clear that the project
licences need or seek to prevent dissociation of files from the
project.


* Document stuff better

** TestRunner::do_run should be public

Requested by Matthias Ferber, so that suites can be dynamically
generated by providing parameters.

** Filtering mechanism is poorly documented.

** Test::Unit::Tutorial is AWOL

** examples are old and sparse
Useful stuff has been on the lists...

** class diagram
We have one at doc/class-diagram.*

Dunno if it's much good.  Notes include specific TODOs at the bottom.


* Nice to have before 1.0

Some of these could be left until after 1.0.  Adam thinks it makes
sense to do them before the release, however; none of them are big
jobs.

** @TESTS isn't tested.

** Pinch more assertions from Test::More

I don't think there's even any particular reason against importing
them directly from Test::More.  No point in duplicating code across
CPAN modules without good reason.

I like these ones:

*** use_ok(), require_ok(), eq_set()

import straight in

*** is_deeply()

either import or write using FreezeThaw::cmpStr or Data::Compare
or whatever

*** eq_array(), eq_hash()

Hmm.  Test::Unit::Assertion::Array / Test::Unit::Assertion::Hash?

*** Easier assertion-set extensibility

mca: I extend test cases by having a standard (for me) superclass,
into which I pile assorted stuff.  It would be nice to provide such
functionality easily and without kinking everyone's inheritance tree.

Also, may need to avoid bloating the standard assertions set.  The
overhead for the compiler is small, but the learning curve ends up
looking much steeper than it needs to be.

Options...

 - provide "simple" and "hedgehog (bristling)" versions of TestCase

 - use import options to determine assertion set

 - leave them all in, but split the documentation

 - spread them into Piers' T:U:A:* structure...  need to investigate


** Rethink how the tests are split up between the t/*.t.

Currently we have t/all_tests.t, which is clearly a misnomer, and we
have some tests for the assertion code being run from that rather than
from t/assert.t.

** Test::Unit::Loader working with whole directories.

Test::Unit::Loader::load_test_dir() needs to be finished.

* After 1.0

No harm done if they end up being done before 1.0 though, of course.

** Test filtering

Piers suggested the beautiful idea of using Attribute::Handlers so you
could do things like:

  sub test_something : todo {...}
  sub test_something : skip_if(<condition>) {...}
  sub test_something : skip {...}

Adam needs this for work ASAP, and will probably implement it very soon.
There is already a primitive filtering mechanism in place which is
controlled by the filter() and filter_method() methods.

Update: Adam met up with Piers a few months ago and together they
figured out that Attribute::Handlers may be unusable due to its
magic happening in the BEGIN phase, whereas all user test code gets
compiled at run-time via Test::Unit::Loader.  Hmm.

** Tests to add

*** PerlUnit selftests

**** die errors that look like variable names  [mca]

A test that fails with an error like

  die '$lotsofdollars';

and make sure it gets wrapped into an ExceptionError

**** doing the right OOP thing in constructors and isa() checks

Possibly a test that overrides the 'isa' method so Piers' fix to my
patch

  (back to using $exception->isa(C) instead of UNIVERSAL::isa($exception,C))

can be exercised.

Also Adam has patched some of the PerlUnit constructors to allow
passing a classname instead of being invoked as a method.

**** check for broken Error.pm overloading of exceptions [as]

Older Error.pms don't do boolean overload, so

  eval { ... };
  if ($@) {
    ...
  }

could break.  We should check for that.

*** Generic tests for users to include

Matthew wrote some. Whether anyone else wants them remains to be seen.

The potentially useful ones:

**** test_SubsAllNeedTests

Checks all subs in a module are tested. Take the code and put it
somewhere else.

**** test_PodChecker

Look the sourcecode up in %INC and run it through the Pod::Checker
(which spits out stuff to STDOUT regardless).

**** test_HaveWarnings

Check $^W .. a bit cheeky. I was actually after a check for
strictness, after forgetting to use it in some module I broke off, but
this is either tricky or impossible.

[Impossible I believe. That's kind of the point of lexical scope after all
   -- pdc]

*** Test coverage tests

There was a big thread on this but it's someone else's turn to write
about that. 8-)  -- mca

Current thinking is to keep test-coverage tests away from the executed
tests, mainly so you can have a script which draws a pretty chart of
how well your code is tested. Adam has some code for this.

* Personal TODO lists

Moved here from doc/consensus.txt.

** Matthew

tktestrunner: ctrl-q, file menu shortcut

assert_deep_equals patches:
 check Test::More for updates
 can we do that direct use linkage?
 do I need to backport the patches we have?

move the scripts somewhere so they get installed in a bin/

put version numbers in all modules (my or our or oldestyle?)
as below,

 - if derived from CVS, with a note somewhere about bumping CVS
   versions if files take non-linear routes somewhere

 - cd src/Test-Unit; grep -rL VERSION lib/ | grep -v CVS/

*** integrate Debianisations and credit the relevant folks
/usr/share/doc/libtest-unit-perl/changelog.Debian.gz

note, dropped from Debian unstable:
  http://bugs.debian.org/279805
  http://bugs.debian.org/317416

*** update top-level README

*** Periodic checks
(should go in doc/release-checklist, or better yet in an installation
test)

Search for Test::* and check they still exist

Search for 'package' ... UnitHarness contains >1

http://www.cpan.org/modules/04pause.html says:
  Please make sure all your *.pm files contain a $VERSION variable that
  conforms to the CPAN rules, i.e. the complete computation of $VERSION
  must take place on the one first line within the module that assigns
  to it. You can test if this is the case by running

  perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'file'

*** Find a neat way to run unit-tested programs without the suite

It's convenient for medium sized projects to stick the test subs in
the classes they test, but then you have a run-time dependence on perlunit.

**** Local Variables:
**** mode: outline
**** End: