The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Config-System-0.23
River stage zero No dependents
++
/ Test::Config::System

NAME

Test::Config::System - System configuration related unit tests

VERSION

Version 0.23

SYNOPSIS

Test::Config::System is used to help test system configuration, ie, cfengine unit tests.

    use Test::Config::System tests => 3;
    
    check_package('less', 'package less');
    check_package('emacs21', 'emacs uninstalled', 1);
    check_link('/etc/alternatives/www-browser', '/usr/bin/w3m');
    check_file('Test/Config/System.pm', qr/do {local \$\//);

DESCRIPTION

Test::Config::System provides functions to help test system configuration, such as installed packages or config files. It was built for use in a cfengine staging environment. (http://www.cfengine.org. cfengine is used for automating and managing system configuration at large sites).

Test::Config::System does not depend on, or interact with cfengine in any way, however, and can be used on its own or with another configuration management tool (such as puppet or bcfg2).

This module is a subclass of Test::Builder::Module, and is used like any other Test::* module. Instead of directly providing an ok() function, the functions exported (described below), call ok() themselves, based on the outcome of the check they preform.

EXAMPLE

    use Test::Config::System tests => 3;
    # check something we already know:  :)
    check_package('perl', 'perl is installed');
    check_file('/etc/apt/sources.list', qr/apt-proxy/,
        'apt-proxy is not being used', 1); # check that the apt-proxy does not
                                           # appear anywhere in sources.list
    check_package('vim');      # Make sure we have the one true editor

EXPORT

check_package check_file check_link check_dir

From Test::Builder::Module:

plan diag ok

FUNCTIONS

Each of the functions below use Test::Builder::Module's ok() function to report test success or failure. They return the result of ok() upon normal completion, or undef on error (eg a required parameter not provided, or FS doesn't support symlinks).

check_package( NAME, [DESC, INVERT, PACKAGE_MANAGER] )

NOTE: check_package currently only supports dpkg. If run on a non-dpkg system, the test will /always/ fail.

check_package tests whether or not a package is installed. If the package is not installed or if the given package manager does not exist, the test fails. Otherwise, the test will pass. (If the test is inverted, the outcome is the opposite).

  - NAME: package name
  - DESC: test name (optional, defaults to package name)
  - INVERT: invert test (optional, defaults to 0.  Possible values are 0 and 1.)
  - PACKAGE_MANAGER: package manager (optional and currently ignored, defaults to 'dpkg')

Examples: # Will fail if nethack is not installed check_package('nethack-text'); # This will fail if x11-common is installed: check_package('x11-common', 'x11-common is not installed', 1);

check_file( FILENAME, REGEX, [DESC, INVERT] )

check_file tests that a file's contents match a given regex. It slurps the contents of the given filename, then matches it against the given regex. If the regex matches the contents of the file, ok() is called with a true value, causing the test to pass. If the regex does not match, the test will fail (as in check_package, if the test is inverted, the results are inverted as well).

If the given file cannot be opened for reading, check_file will return undef, and ok() will not be called.

Note that the entire file is slurped into memory at once. This has two concequences. First, large files will eat up RAM. Second, ^ and $ do not work line-by-line, as one might expect. "\n" can be used in place of ^ or $.

  - FILENAME: file to test
  - REGEX: regex to match (qr//-style regex)
  - DESC: test name (optional, defaults to filename)
  - INVERT: invert test (optional, defaults to 0.  Possible values are 0 and 1.)

Examples: check_file('/etc/fstab', qr|proc\s+/proc\s+proc\s+defaults\s+0\s+0|, 'proc is in fstab'); check_file('/etc/passwd', qr|evilbob:x:\d+:\d+:|, 'evilbob is not in passwd', 1);

check_link( FILENAME, [TARGET, DESC, INVERT] )

check_link verifies that a symlink exists and, optionally, points to the correct target.

If no filename is passed, it will return undef, otherwise a test will be run and the result of ok() will be returned.

If the filesystem does not support symlinks, the test will be skipped, and check_link will return undef.

  - FILENAME: filename (path to a symlink)
  - TARGET:   path the link should point to.  optional.  If not specified,
              check_link will ignore the target, and just verify that the link
              exists.
  - DESC: test name (optional, defaults to filename)
  - INVERT: invert test (optional, defaults to 0.  Possible values are 0 and 1.)

Examples: check_link('/etc/alternatives/rsh', '/usr/bin/ssh'); check_link('/etc/sudoers', '', 'sudoers is not a symlink', 1);

check_dir( PATH, [STAT, DESC, INVERT] )

check_dir verifies that a directory exists. Optionally, it can check various attributes such as owner, group, or permissions.

  - PATH: path of the directory to check
  - STAT: a hashref of attributes to check and their desired values.  Valid keys:
        -uid    owner uid
        -gid    owner gid
        -mode   file permissions
    Each key is optional, as is the entire hash.  Note that the type need not
    be specified in -mode; it is added automatically (ie use 0700 instead of
    040700).

  - DESC: test name (optional, defaults to PATH)
  - INVERT: invert test (optional, defaults to 0.  Possible values are 0 and 1.)

Examples: check_dir('/var/www'); check_dir('/home/ian', { '-uid' => scalar getpwnam('ian') } ); check_dir('/root/', { '-uid' => 0, '-gid' => 0, '-mode' => 0700 }, '/root/ has sane permissions'); check_dir('/home/evilbob', { }, 'Evilbobs homedir does not exist', 1);

AUTHOR

Ian Kilgore, <iank at cpan.org>

BUGS

  • Never call check_package or check_file with untrusted input.

    check_package shells out to dpkg, and check_file uses an arbitrary regexp.

  • check_package currently only supports dpkg

  • This module remains untested on windows and non-linux unixes

Please report any bugs or feature requests to bug-test-config-system at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Config-System. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Test::Config::System

You can also look for information at:

ACKNOWLEDGEMENTS

Many thanks to [naikonta] at perlmonks, for reviewing the module before release.

COPYRIGHT & LICENSE

Copyright 2007 Ian Kilgore, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Test::Builder::Module