Quattor¶
SYNOPSIS¶
use Test::Quattor qw(test_profile1 test_profile2...);
LOADING¶
When loading this module it will compile any profiles given as arguments. So,
use Test::Quattor qw(foo);
will trigger a compilation of src/test/resources/foo.pan
and the
creation of a binary cache for it. The compiled profile will be stored
as target/test/profiles/foo.json
, while the cache will be stored in
under target/test/profiles/foo/
.
This binary cache may be converted in an
EDG::WP4::CCM::CacheManager::Configuration
object using the
get_config_for_profile
function.
INTERNAL INFRASTRUCTURE¶
Module variables¶
This module provides backup methods for several CAF
modules. They
will prevent tests from actually modifying the state of the system,
while allowing an NCM component to follow a realistic execution path.
These backups record what files are being written, what commands are being run, and allow for inspection by a test.
This is done with several functions, see Redefined functions below, that control the following variables:
- QUATTOR_TEST_LOG_DEBUGLEVEL
If the environment variable QUATTOR_TEST_LOG_DEBUGLEVEL is set, the unittests will run with this debuglevel (0-5). Otherwise the default loglevel is ‘verbose’.
To actually see the verbose or debug output, you need to run prove with verbose flag (e.g. by passing
-Dprove.args=-v
or by setting-v
in the<~/.proverc
>).
$log_cmd
A boolean to enable logging of each command that is run via CAF::Process. Can also be set via the QUATTOR_TEST_LOG_CMD environment variable.
$log_cmd_missing
A boolean to log each cmd that has output mocked but has no output set. Can also be set via the QUATTOR_TEST_LOG_CMD_MISSING environment variable.
%files_contents
Contents of a file after it is closed. The keys of this hash are the absolute paths to the files.
This hash is a global variable whose contents can be checked in a test, if necessary. But if you want to set the file content before using the
CAF::Path
methods (for example, usingset_file_contents
), it is preferable to use%desired_file_contents
.
%commands_run
CAF::Process objects being associated to a command execution.
%commands_status
Desired exit status for a command. If the command is not present here, it is assumed to succeed.
%desired_outputs
When we know the component will callCAF::Process::output
and friends, we prepare here an output that the component will have to deal with.
%desired_err
When the component may analyse the standard error of a component, we supply it through this hash.
%desired_file_contents
Initial contents for a file that should be “edited”. The content of this hash (keys are the absolute path names) is managed/updated by all theCAF::FileWriter
methods. It is preferable to use it rather than%files_contents
, if you don’t need to access its contents directly from another module (CAF::FileWriter
methods give access to its contents in fact).
@command_history
CAF::Process commands that were run.
caf_path
A hashref withCAF::Path
methods and arrayref of reference of used arguments
NoAction
Set
Test::Quattor::NoAction
to overrideCAF::Object::NoAction
in any of the mockedTest::Quattor
methods (where relevant, e.g. mocked FileWriter and FileEditor).E.g. if you want to run tests with
CAF::Object::NoAction
not set (to test the behaviour of regularCAF::Object::NoAction
).Default is 1.
%immutable
The content of this hash (keys are the absolute path names) indicates if paths (files, directories, …) are immutable (or not). Any modification to an immutable path will result in an error.
You can add paths using the
set_immutable
function.
%status
The content of this hash (keys are the absolute path names) indicates current
CAF::Path::status
(mode
,mtime
,owner
and/orgroup
).You can add paths using the
set_status
function.
Redefined functions¶
In order to achieve this, the following functions are redefined automatically:
CAF::Process::{run,execute,output,trun,toutput}
Prevent any command from being executed.
CAF::FileWriter::open
Overriding this function allows us to inspect its contents after the unit under tests has released it.
CAF::FileWriter::close
Overriding this function to force noaction and update mocked%desired_file_contents
.
CAF::FileWriter::_close
Mock-only method to make the FileWriter instance not opened (in IO::String sense).
Required for cleanup of filehandles left by eg immutable paths.
CAF::FileWriter::_read_contents
Used to get the original content (for<CAF::FileWriter-``close>>) and/or source (for ``<CAF::FileEditor-``new>>) from the ``%desired_file_contents
.
CAF::FileEditor::_is_valid_file
Mock usingis_file
function.
CAF::FileEditor::_is_reference_newer
Mock usingis_file
function (but no support for pipes or age test).
CAF::FileReader::_is_valid_file
Mock usingis_file
function (but no support for pipes).
CAF::Reporter::debug
Checks that each debug() call starts with a debuglevel between 0 and 5.
CAF::Reporter::debug
Checks that each debug() call starts with a debuglevel between 0 and 5.
IO::String::close
Prevents the buffers from being released when explicitly closing a file.
CAF::Path::file_exists
Return the mockedis_file
CAF::Path::directory_exists
Return the mockedis_directory
CAF::Path::any_exists
Return the mockedis_any
- is_symlink
Test if givenpath
is a mocked symlink
- has_hardlinks
Test if given
path
is a mocked hardlinkNote that it is not a perfect replacement for the c<CAF::Path>
has_hardlinks
because the current implementation of mocked hardlinks does not allow to mimic multiple references to an inode. The differences are : the link used at creation time must be queried, not the target (where in a real hardlink target and link are undistinguishable); if the path is a hardlink the number of references for the inode is always 1.
- is_hardlink
Test ifpath1
andpath2
are hardlinked
- _make_link
Add a mocked
_make_link
.This mocked method implements most of the checks done in
LC::Check::link
, the function doing the real work in_make_link
, and returns the same values asCAF::Path
_make_link
. SeeCAF::Path
comments for details.Internally, this mocked symlink/hardlink support uses the file contents to track that a path is a symlink or hardlink. Thus, in addition to the symlink() and hardlink() methods, a link can be created with
set_file_contents($filename, $Test::Quattor::SYMLINK)
for a symlink andset_file_contents($filename, $Test::Quattor::HARDLINK)
for a hardlink.
CAF::Path::directory
Return directory name unless mocked
make_directory
or mockedLC_Check
fail.(The
temp
is ignored wrt creating the directory name).
CAF::Path::LC_Check
Store args incaf_path
usingadd_caf_path
.
CAF::Path::cleanup
remove_any
and store args incaf_path
usingadd_caf_path
.
CAF::Path::move
remove_any
and store args incaf_path
usingadd_caf_path
.
CAF::Path::status
Set and compare status.
CAF::Path::_listdir
Mock underlying _listdir method that does the actual opendir/readdir/closedir.
Has 2 args, one directory and one test function. The is no validation of any kind. Do not use this method directly, use
listdir
instead.
FUNCTIONS FOR EXTERNAL USE¶
The following functions are exported by default:
get_file
Returns the object that has manipulated$filename
set_file_contents
For file
$filename
, sets the initial$contents
the component should see. It also sets the defaultCAF::FileWriter
permissions (mode
644).Returns the contents on success, undef otherwise.
get_file_contents
For file$filename
, returns the contents on success, undef otherwise.
get_command
Returns all the information recorded about the execution of$cmd
, if it has been executed. This is a hash reference in which theobject
element is theCAF::Process
object itself, and themethod
element is the function that executed the command.
set_command_status
Sets the “exit status” we’ll report for a given command.
set_desired_output
Sets the standard output we’ll return when the caller issuesoutput
on this command
set_desired_err
Sets the standard error we’ll receive when the caller issuesexecute
on this command.
command_history_reset
Reset the command history to empty list.
command_history_ok
Given an arrayref of
required_commands
, it checks the@command_history
if all commands were called in the given order (it allows for other commands to exist inbetween). The commands are interpreted as regular expressions.E.g. if
@command_history
is (x1, x2, x3) thencommand_history_ok([x1,X3])
returns 1 (Both x1 and x3 were called and in that order, the fact that x2 was also called but not checked is allowed.).command_history_ok([x3,x2])
returns 0 (wrong order),command_history_ok([x1,x4])
returns 0 (no x4 command).A second arrayref of
forbidden_commands
can be given, and the@command_history
is then first checked that none of those commands occured. If you only want to check the non-occurence of commands, pass an undef as the first argument (and not an empty arrayref).
set_service_variant
Sets the
CAF::Service
variant to the one given in the command line:
linux_sysv
Linux SysV, e.g,/sbin/service foo start
linux_systemd
Linux, Systemd variant.
solaris
Solaris and SMF variant.
Test::Quattor
defaults tolinux_sysv
.
force_service_variant
Force the variant by bypassing
CAF::Service
AUTOLOAD
magic and defining the methods via glob assignments in the namespace.The first argument is the
$variant
to use.When testing subclassed
CAF::Service
, the second (optional) argument is the subclass, followed by all other arguments as additional non-standard actions.
- set_immutable
Makepath
immutable. Pass a falsebool
to make the path mutable again (not <undef>, default is to make the path immutable).
- set_status
(Re)set status ofpath
to the options (mode
,mtime
,owner
and/orgroup
).
- is_mutable
Check if the path and parent path are mutable. (Parent path is not checked when
skip_parent
argument is true).Report an error prefixed with
prefix
and return 0 when path (and/or parent path) is immutable.
- sane_path
sanitize path by
- squash multiple ‘/’ into one
- remove all trailing ‘/’
- is_file
Test if given$path
is a mocked file
- is_directory
Test if given$path
is a mocked directory
- is_any Test if given
path
is known (as file or directory or anything else) - make_directory
Add a directory to the mocked directories. If
rec
is true or undef, also add all underlying directories.If
mutable
is true, always create the directory.If directory already exists and is a directory, return SUCCESS (undef otherwise).
- remove_any
Recursive removal of apath
from the files_contents / desired_file_contents
- move
movesrc
todest
. Ifbackup
is defined and not empty string, movedest
to backup (backup
is a suffix).
- add_caf_path
Add array of arguments tocaf_path
hashref usingname
- reset_caf_path
Resetcaf_path
ref. Ifname
is defined, only reset that cache.
- dump_contents
Debug function to show the entries in
desired_file_contents
andfiles_contents
.Options
- log
Pass a reporter/logger instance, and report with verbose level. By default,Test::More::diag
is used.
- filter
Regex pattern to filter filenames to show (matches are kept).
- prefix
A message prefix
BUGS¶
Probably many. It does quite a lot of internal black magic to make
your executions safe. Please ensure your component doesn’t try to
outsmart the CAF
library and everything should be fine.