-*- outline -*-

* Intro

We were wondering how we should go about keeping track of the
consensuses (sp?) we reached on the perlunit-devel mailing list.

Matthew was all for a cumbersome set of tags so we could grep the list
for "points".

Christian suggested a simple text file in CVS which we modify as
appropriate.

This is a compromise - a simple text file marked up for use with
emacs' "outline-mode". I chose this because I know that at least 2/4
active developers use emacs. Open to other suggestions of course.

				-- MCA 27/2/2001

** Links back to the mailing list

Might be handy for those with local archives, but dropping message-ids
in this file will make a mess IMHO  -- mca

* Test::Unit::Assert::assert()


What is Test::Unit::Assert for? -- pdc

** assert_eq(this, that, message) and other comparison routines

PerlUnit doesn't include these because the user should be left to
decide for s/himself whether to use == or eq .

For the same reason we suggest users should roll their own structure
comparison routines or use FreezeThaw::cmpStr()

Having said this, we don't have concrete examples of Bad Things
happening, as Adam pointed out. Please add examples below...

[PDC: With coderefs, it becomes:

    assert( sub {($_[0] eq $_[1]) || die "Expected '$_[0]', got '$_[1]'"},
	   $expected, $got );

There's nothing to stop us having a utility Test::Unit::CodeRef class method
that'd return an appropriate anon subroutine:

    assert(Test::Unit::Coderef->assert_eq, $expect, $got);

    assert(Test::Unit::Coderef->assert_numeric, $expect, $got);

Just a talking point.]

** assert_regexp(string, qr/regexp/, message)

Seems like a good idea, not yet committed

[PDC: Changed this slightly by reifying the first argument to
Test::Unit::Assert::assert into an 'assertion' object. If the first argument
is a regular expression (using hte qr/.../ method) then it becomes a
Test::Unit::Assertion::Regexp, which compares against the second argument and
returns a default error message.

Nothing to stop us extending this to take a possible different message as the
last argument and use that as the message instead of the default.]

** coderef_assert($cr, $self);

Code that returns true for success and dies with an exception if it
needs to make leave a message.

This and other (blessed) objects get their 'do_assert' method called.

See the 'pdc_coderefassert' branch of CVS.

[PDC: No longer using the 'coderef_assert' method. This functionality is now
rolled into the standard 'assert' method. If the first argument is a CODE
reference, it becomes a Test::Unit::CodeRef assertion and gets all sorts of
canny error reporting associated with it...]

* Auto-adding tests, Test::Unit::TestSuite->new()

** interaction with inheritance

Broken in v0.13, it will take SUPER::test_foo if test_foo is
an inheritted method in the class being scanned.

Fixed by Piers.

** regexps to pull functions called /^test/

I think current consensus is to change the default to /^test[_A-Z]/
but make it configurable.

I seem to have lost that thread -- mca

* Debug methods

Not much agreement yet, here are some of the suggestions

** $self->debug()

A dead/unused patch from Matthew, the idea was a default debug in the
base T:U:TestCase class and methods to override it. Messy and
inconvenient.

** $self->listener->debug($@)

Some say listeners are Java-ish. Others say that they're good anyway.
9-)

Arguments are headed towards something like
       debug( level => 123,
	      user => "simple message",
	      developer => "complicated message" );
or some variation on the theme.

This all looks rather verbose so far though. 8-(

** clever things with caller()

one vote for [MCA] (provided you can override it)
one vote against? [PDC]

* Documentation

** Where?

Where should it be kept? At the moment it lives almost entirely in POD
and mailing list/message board format, and so is inaccessible.

A pod2html pass of released software should probably be served on the
website.

Matthew's (almost finished) cvspublish.pl script could do most of this
but is probably overkill. Also it doesn't grok MANIFEST files.

There is a documentation manager on SF. The front door is not too
friendly and there is no back door to the data inside it.

** API & PerlUnit overview

Current favourite is to point at the JUnit docs.

There is in 'src/api' a set of basic perl modules containing the
essence of the structure, but they're getting old.

Also, the SF message boards have some knowledge which needs
distilling.

* Namespace pollution

** classes used during self-tests

We're going to try to avoid it while generating "inner classes" or
whatever, for the self-tests.

** keys in the TestCase object hash  [not yet discussed]

T:U::TestCase::new is biting into namespace belonging to classes
inherited from T:U::TestCase .. currently it only takes _name ... I'm
wondering whether we should go to '__' prefix in the C tradition for
"magic things", since the perlunit user shouldn't need to mess with
this? -- mca

Not sure I understand what you're getting at here. The PITA approach would be
to name all the keys used only by T:U::TestCase as 

'Test::Unit::TestCase::keyname', which is a pain to work with, but probably
the best practice. See the discussion in Damian Conway's Object Oriented Perl. 

   -- pdc

* TODO lists
** Matthew
*** Consider removing examples/tester* (uses old Test::SuiteWrapper)
*** Make Debian package
*** 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.

* Tests to add

** PerlUnit selftests, Test::Unit::tests

*** 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.

** 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.

* Keeping state

It's not nice but we're doing it already, in an untidy way.

Likely uses are 

 - backtrace quelledness (this goes away when we bin the backtrace)
 - (some) debug handlers
 - tagging tests (eg. "slow") for selective execution

It should be stored per-run (in the Listener) not per suite or
testcase.

I think it should be locally modifiable otherwise it's too inflexible.


* Packaging

[mca: Christian has SourceForge and CPAN packaging pretty much wrapped
up *cough*, this is documented in another file in this directory]

** Debian GNU/Linux

[mca: Since I use perlunit for production work, I'm tempted to roll a
package if it's not too tricky. There is a stack of reading to do
first though (I'm not an official Debian developer)

Relevant bit from /usr/doc/dh-make-perl/README

  dh-make-perl will create the files required to build
  a debian source package out of a perl package.
  This works for most simple packages and is also useful
  for getting started with packaging perl modules.

  There is an override mechanism in place to handle most of
  the little changes that may be needed for some modules
  (this hasn't been tested much, though).

  Using this program is no excuse for not reading the
  debian developer documentation, including the policy,
  the perl policy, the packaging manual and so on.

See also http://www.uk.debian.org/devel/  ]

** RedHat

[mca: I made a RH package a long time ago... don't remember how]