View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Dominique Dumont > Config-Model-Tester > Config::Model::Tester



Annotate this POD


View/Report Bugs
Module Version: 3.006   Source  


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


version 3.006


In your test file (typically t/model_test.t):

 use warnings;
 use strict;

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

 run_tests() ;

Run tests with:

 perl t/model_test.t [ --log ] [--error] [--trace] [ subtest [ test_case ] ]


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

A specific layout for test files must be followed.

Sub test specification

Each subtest is defined in a file like:


This file specifies that app-name (which is defined in lib/Config/Model/*.d directory) will be used for the test cases defined in the * file.

This file contains a list of test case (explained below) and expects a set of files used as test data. The layout of these test data files is explained in next section.

Simple test file layout

Each test case is represented by a configuration file (not a directory) in the *-examples directory. This configuration file will be used by the model to test and is copied as $confdir/$conf_file_name using the global variables explained below.

In the example below, we have 1 app model to test: lcdproc and 2 tests cases. The app name matches the file specified in lib/Config/Model/*.d directory. In this case, the app name matches lib/Config/Model/system.d/lcdproc

 |-- model_test.t
 \-- model_tests.d           # do not change directory name
     |--   # subtest specification for lcdproc app
     \-- lcdproc-examples
         |-- t0              # test case t0
         \-- LCDD-0.5.5      # test case for older LCDproc

Subtest specification is written in file (i.e. this modules looks for files named like <app-name>>).

Subtests data is provided in files in directory lcdproc-examples ( i.e. this modules looks for test data in directory <model-name>-examples>. contains instructions so that each file will be used as a /etc/LCDd.conf file during each test case. can contain specifications for more test cases. Each test case requires a new file in lcdproc-examples directory.

See "Examples" for a link to the actual LCDproc model tests

Test file layout for multi-file configuration

When a configuration is spread over several files, each test case is provided in a sub-directory. This sub-directory is copied in $conf_dir (a global variable as explained below)

In the example below, the test specification is written in Dpkg layout requires several files per test case. will contain instructions so that each directory under dpkg-examples will be used.

 \--         # subtest specification
 \-- dpkg-examples
     \-- libversion            # example subdir, used as test case name
         \-- debian            # directory for used by test case
             |-- changelog
             |-- compat
             |-- control
             |-- copyright
             |-- rules
             |-- source
             |   \-- format
             \-- watch

See "Examples" for a link to the (many) Dpkg model tests

More complex file layout

Each test case is a sub-directory on the *-examples directory and contains several files. The destination of the test files may depend on the system (e.g. the OS). For instance, system wide ssh_config is stored in /etc/ssh on Linux, and directly in /etc on MacOS.

These files are copied in a test directory using a setup parameter:

  setup => {
    test_file_in_example_dir => 'destination'

Let's consider this example of 2 tests cases for ssh:

 |-- ssh-examples
     \-- basic
         |-- system_ssh_config
         \-- user_ssh_config

Unfortunately, user_ssh_config is a user file, so you specify where the home directory for the tests with another global variable:

  $home_for_test = '/home/joe' ;

For Linux only, the setup parameter is:

 setup => {
   'system_ssh_config' => '/etc/ssh/ssh_config',
   'user_ssh_config'   => "~/.ssh/config"

On the other hand, system wide config file is different on MacOS and the test file must be copied in the correct location. When the value of the setup hash is another hash, the key of this other hash is used as to specify the target location for other OS (as returned by Perl $^O variable:

      setup => {
        'system_ssh_config' => {
            'darwin' => '/etc/ssh_config',
            'default' => '/etc/ssh/ssh_config',
        'user_ssh_config' => "~/.ssh/config"

See the actual Ssh and Sshd model tests

Basic test specification

Each model subtest is specified in <model> This file contains a set of global variables. (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/model_tests directory)
 $conf_file_name = "fstab" ;
 # config dir where to copy the file (optional)
 #$conf_dir = "etc" ;
 # home directory for this test
 $home_for_test = '/home/joe' ;

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

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

 # list of tests. This modules looks for @tests global variable
 @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

You can suppress warnings by specifying no_warnings => 1. On the other hand, you may also want to check for warnings specified to your model. In this case, you should avoid specifying no_warnings here and specify warning tests or warning filters as mentioned below.

See actual fstab test.

Skip a test

A test file can be skipped using $skip global variable.

In this example, test is skipped when not running on a Debian system:

 eval { require AptPkg::Config; };
 $skip = ( $@ or not -r '/etc/debian_version' ) ? 1 : 0;

Internal tests or backend tests

Some tests will require the creation of a configuration class dedicated for test (typically to test corner cases on a backend).

This test class can be created directly in the test specification by calling create_config_class on $model variable. See for instance the layer test or the test for shellvar backend.

Test specification with arbitrary file names

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

 # not needed if test file is named
 $model_to_test = "Multistrap";

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

See the actual multistrap test.

Backend argument

Some application like systemd requires a backend argument specified by User (e.g. a service name for systemd). The parameter backend_arg can be specified to emulate this behavior.

Re-use test data

When the input data for test is quite complex (several files), it may be interested to re-use these data for other tests case. Knowing that test name must must unique, you can re-use test data with data_from parameter. For instance:

  @tests = (
        name  => 'some-test',
        # ...
        name  => 'some-other-test',
        data_from  => 'some-test',    # re-use data from test above
        # ...

See plainfile backend test for a real life example.

Test scenario

Each subtest follow a sequence explained below. Each step of this sequence may be altered by adding specification in <model-to-test>

Running the test

Run all tests with one of these commands:

 prove -l t/model_test.t :: [ t|l|e [ <model_name> [ <regexp> ]]]
 perl -Ilib t/model_test.t  [ t|l|e [ <model_name> [ <regexp> ]]]

By default, all tests are run on all models.

You can pass arguments to t/model_test.t:

Examples ^



Dominique Dumont


This software is Copyright (c) 2013-2018 by Dominique Dumont.

This is free software, licensed under:

  The GNU Lesser General Public License, Version 2.1, February 1999



The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Bugs / Feature Requests

Please report any bugs or feature requests by email to ddumont at, or through the web interface at You will be automatically notified of any progress on the request by the system.

Source Code

The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)

  git clone git://
syntax highlighting: