NAME

       Lire::Test::FunctionalTestCase - Base class for writing functional unit tests

SYNOPSIS

         use base qw/ Lire::Test::FunctionalTestCase/;

DESCRIPTION

       This is a Test::Unit::TestCase subclass which can be used to make it easier to write functional tests.

   WHAT ARE FUNCTIONAL TESTS
       Unlike unit tests that test the semantics of the API and document the internals assumptions, functional
       tests are tests that tests the 'functionality' of the overall software. They kind of document the
       expected functionality of the software.

   Lire::Test::FunctionalTestCase
       In Lire, the "expected functionality" is exercised by running commands, so this module provides
       convenient methods to run Lire commands and tests their expected output.

       It also setup a mock sendmail which can be used to analyze the email that the Lire system should send.

       Some of Lire functionality cannot be tested anymore simply by running command (for example the Curses::UI
       based user interface cannot be tested that way but throught the use of Lire::Test::CursesUIDriver).  For
       these kind of tests, this base class will set up a new Lire::Config and Lire::PluginManager instance in
       the set_up method. Tests that requires these functionality can simply call Lire::Config->init() and
       Lire::PluginManager->instance()->register_default_converters() without fear of messing the test
       environement.

   homedir()
       Returns the directory which will be assigned to ENV{'HOME'} when commands are run. This directory is
       cleaned up after every test.

   rundir()
       Returns the directory which will be the working directory when the commands are run. This directory is
       cleaned up after every test.

   config_spec()
       Returns the Lire::Config::TypeSpec object which will be used at runtime by the functional tests. It can
       be used to setup configuration files for the test.

   locale( [new_locale] )
       Changes the locale under which the functional test is going to be run. By default, all tests are run
       under the 'C' locale ignoring all user's environment variables.

       Returns the previous locale set.

   lire_run( $shell_cmd )
       This method runs the command $shell_cmd through the shell and returns a Lire::Test::CommandResult object
       which can be used to run tests on this command. The Lire environment will be set up before invoking the
       shell.

   sent_mail()
       Returns in an array reference the message that were sent out during the test. The element of this array
       are hash reference containing two keys:

       recipients
           An array reference containing the recipients as passed on the command line to sendmail.

       message
           The email which was sent. This is the complete text of the email. This is what was passed to sendmail
           via STDIN.

   create_test_file( $filename, [$content] )
       Create a file $filename with the content $content. This file will be removed after the test is run during
       the tear_down() method. An empty file will be created if the $content parameter is omitted.

   install_xml_spec( $spec_type, $superservice, $file )
       Install  the  XML  specification in $file of base schema $superservice.  The $spec_type parameter specify
       where the file will be installed:

       site_filter
           The file will be installed as a filter specification in the system directory.

       site_report
           The file will be installed as a report specification in the system directory.

       site_schema
           The file will be installed as a schema specification in the system directory.

       filter
           The file will be installed as a filter specification in the HOME directory.

       report
           The file will be installed as a report specification in the HOME directory.

       schema
           The file will be installed as a schema specification in the HOME directory.

       These files will be removed after the test.

   create_test_cfg_file( $name )
       Returns a Lire::Config::ConfigFile object initialized with the  appropriate  config  specification.  This
       configuration  file  will  be created under $HOME/.lire/config/$name.xml when lire_run() will be used. It
       can be use to set config option which will be used when the command is run:

         my $cfg = $self->create_test_cfg_file( "test" );
         $cfg->global->get( "lr_from" )->set( "flacoste\@logreport.org" );

       If a configuration file $name was already created, it returns the associated ConfigFile object.

       Note that if you want these configurations variable to have effect when running test in-process ( not via
       lire_run() ), you have to call save() on the object before calling Lire::Config->init().  Otherwise,  you
       better set the configuration option directly using the Lire::Config API.

SEE ALSO

       Test::Unit::TestCase(3pm)

VERSION

       $Id: FunctionalTestCase.pm,v 1.27 2006/07/23 13:16:31 vanbaal Exp $

AUTHOR

       Francis J. Lacoste <flacoste@logreport.org>

COPYRIGHT

       Copyright (C) 2003 Stichting LogReport Foundation LogReport@LogReport.org

       This file is part of Lire.

       Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public
       License  as  published  by  the  Free  Software  Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;  without  even
       the  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
       License for more details.

       You should have received a copy of the GNU General Public License along with this program (see  COPYING);
       if not, check with http://www.gnu.org/copyleft/gpl.html.

Lire 2.1.1                                         2006-07-23                            FunctionalTestCase(3pm)