/ 
Config-Model-2.004
River stage two • 11 direct dependents • 11 total dependents
/ Config::Model::Tester

NAME

Config::Model::Tester - Test framework for Config::Model

VERSION

version 2.004

SYNOPSIS

# in t/foo.t
use warnings;
use strict;

use Config::Model::Tester ;
use ExtUtils::testlib;

my $arg = shift || '';
my $test_only_model = shift || '';
my $do = shift ;

run_tests($arg, $test_only_model, $do) ;

DESCRIPTION

This class provides a way to test configuration models with tests files. This class was designed to tests several models and severals tests cases per model.

A specific layout for test files must be followed

Test file layout

t/model_tests.d
|-- fstab-examples
|   |-- t0
|   \-- t1
|-- fstab-test-conf.pl
|-- debian-dpkg-examples
|   \-- libversion
|       \-- debian
|           |-- changelog
|           |-- compat
|           |-- control
|           |-- copyright
|           |-- rules
|           |-- source
|           |   \-- format
|           \-- watch
\-- debian-dpkg-test-conf.pl

In the example above, we have 2 models to test: fstab and debian-dpkg.

Each model test has specification in *-test-conf.pl files. Test cases are either plain files or directories in *-examples . The former is fine if your model deal with one file (e.g. /etc/fstab. Complete directories are required if your model deal with several files (e.g. Debian source package).

Basic test specification

Each model test is specified in <model>-test-conf.pl. This file contains a set of global variable. (yes, global variables are often bad ideas in programs, but they are handy for tests):

# config file name (used to copy test case into test wr_root directory)
$conf_file_name = "fstab" ;
# config dir where to copy the file
#$conf_dir = "etc" ;

Here, t0 file will be copied in wr_root/test-t0/etc/fstab.

# config model name to test
$model_to_test = "Fstab" ;

# list of tests
@tests = (
   { 
    # test name 
    name => 't0',
    # add optional specification here for t0 test
   },
   { 
    name => 't1',
    # add optional specification here for t1 test
    },
);

1; # to keep Perl happy

Test specification with arbitrary file names

In some models (e.g. Multistrap, the config file is chosen by the user. In this case, the file name must be specified for each tests case:

$model_to_test = "Multistrap";

@tests = (
   {
       name        => 'arm',
       config_file => '/home/foo/my_arm.conf',
       check       => {},
   },
);

test scenario

Each subtest follow a sequence explained below. Each step of this sequence may be altered by adding specification in the test case:

  • Setup test in wr_root/<subtest name>/

  • Create configuration instance, load config data and check its validity. Use load_check => 'no' if your file is not valid.

  • Check for config data warning. You should pass the list of expected warnings. E.g.

    load_warnings => [ qr/Missing/, (qr/deprecated/) x 3 , ],

  • Optionally load configuration data. You should design this config data to suppress any error or warning mentioned above. E.g:

    load => 'binary:seaview Synopsis="multiplatform interface for sequence alignment"',

  • Optionally, call apply_fixes:

    apply_fix => 1,

  • Call dump_tree to check the validity of the data. Use dump_errors if you expect issues:

    dump_errors =>  [ 
    # the issues     the fix that will be applied
    qr/mandatory/ => 'Files:"*" Copyright:0="(c) foobar"',
    qr/mandatory/ => ' License:FOO text="foo bar" ! Files:"*" License short_name="FOO" '
],

  • Likewise, specify any expected warnings:

    dump_warnings => [ (qr/deprecated/) x 3 ],

    You can tolerate any dump warning this way:

    dump_warnings => undef ,

  • Run specific content check to verify that configuration data was retrieved correctly:

    check => { 
    'fs:/proc fs_spec',           "proc" ,
    'fs:/proc fs_file',           "/proc" ,
    'fs:/home fs_file',          "/home",
},

    You can run check using different check modes (See "fetch( ... )" in Config::Model::Value):

    check_layered  => {
            'sections:debian packages:0' ,'dpkg-dev',
            'sections:base packages:0', 'gcc-4.2-base',
        },

    The mode is specified after check_.

  • Write back the config data in wr_root/<subtest name>/. You can skip warning when writing back with:

    no_warnings => 1,

  • Check the content of the written files(s) with Test::File::Contents:

    file_content => { 
         "/home/foo/my_arm.conf" => "really big string" ,
     }

  • Check added or removed configuration files. If you expect changes, specify a subref to alter the file list:

    file_check_sub => sub { 
    my $list_ref = shift ; 
    # file added during tests
    push @$list_ref, "/debian/source/format" ;
};

  • Copy all config data from wr_root/<subtest name>/ to wr_root/<subtest name>-w/. This steps is necessary to check that configuration written back has the same content as the original configuration.

  • Create another configuration instance to read the conf file that was just copied (configuration data is checked.)

  • Compare data read from original data.

running the test

Run all tests:

perl -Ilib t/model_test.t

By default, all tests are run on all models.

You can pass arguments to t/model_test.t:

  • a bunch of letters. 't' to get test traces. 'e' to get stack trace in case of errors, 'l' to have logs. All other letters are ignored. E.g.

    # run with log and error traces
perl -Ilib t/model_test.t el

  • The model name to tests. E.g.:

    # run only fstab tests
perl -Ilib t/model_test.t x fstab

  • The required subtest E.g.:

    # run only fstab tests t0
perl -Ilib t/model_test.t x fstab t0

Examples

See http://config-model.hg.sourceforge.net/hgweb/config-model/config-model/file/tip/config-model-core/t/model_tests.d/debian-dpkg-copyright-test-conf.pl

AUTHOR

Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO

Config::Model,