Test::Collectd::Plugins - Common out-of-band collectd plugin test suite
Version 0.1008
use Test::More; use Test::Collectd::Plugins typesdb => ["/usr/share/collectd/types.db"]; plan tests => 4; load_ok ("Collectd::Plugins::Some::Plugin"); read_ok ("Collectd::Plugins::Some::Plugin", "plugin_name_as_returned_by_dispatch"); read_config_ok ("My::Plugin", "my_plugin", "/path/to/my_plugin.conf"); my $expected = [[{{ plugin => "my_plugin", type => "gauge", values => [ 42 ] }}]]; my $got = read_values_config ("My::Plugin", "my_plugin", "/path/to/my_plugin.conf"); is_deeply ($got, $expected); done_testing;
Testing collectd modules outside of collectd's perl interpreter is tedious, as you cannot simply 'use' them. In fact you can't even 'use Collectd', try it and come back. This module lets you test collectd plugins outside of the collectd daemon. It is supposed to be the first step in testing plugins, detecting syntax errors and common mistakes. There are some caveats (see dedicated section), and you should use the usual collectd testing steps afterwards e.g. enabling debug at compile time, then running the collectd binary in the foreground while using some logging plugin, plus some write plugin. I usually use logfile to STDOUT and csv plugin.
Most methods will accept either $plugin or $module or both. They correspond to collectd-perl's LoadPlugin $module and Plugin $plugin respectively. It's easy to mistake one for the other. While $module is as its name suggests the perl module's name, $plugin corresponds to the collectd plugin's name, as called by plugin_dispatch_values. This difference makes it possible for a plugin to dispatch values on behalf of another, or to register multiple plugins. Make sure you ask the methods the right information.
collectd-perl
LoadPlugin $module
Plugin $plugin
Tries to load the plugin module. As collectd-perl plugin modules contain direct calls (upon loading) to "plugin_register" in Collectd, the former are intercepted by FakeCollectd which is part of this distribution. This has the effect of populating the %FakeCollectd hash. See FakeCollectd for more info.
See "plan" in Test::More.
Loads the plugin module identified by $module, then tries to fire up the registered read callback for this plugin ($plugin), while intercepting all calls to "plugin_dispatch_values" in Collectd, storing its arguments into the %FakeCollectd hash. The latter are checked against the following rules, which match the collectd guidelines:
There shall be only one and only one hashref argument
The following keys are mandatory: plugin, type, values
Only the following keys are valid: plugin, type, values, time, interval, host, plugin_instance, type_instance.
The key type must be present in the types.db file.
type
types.db
The key values must be an array reference and the number of elements must match its data type in module's configuration option types.db.
values
All other keys must be scalar strings with at most 63 characters: plugin, type, host, plugin_instance and type_instance.
plugin
host
plugin_instance
type_instance
The keys time and interval must be a positive integers.
time
interval
The keys host, plugin_instance and type_instance may use all ASCII characters except "/".
The keys plugin and type may use all ASCII characters except "/" and "-".
Same as read_ok but also reads configuration from $plugin_config and fires up the configuration callback of plugin $plugin_module. "parse" in Test::Collectd::Config will kindly format a configuration file or handle to suit this subroutine.
Returns arrayref containing the list of arguments passed to "plugin_dispatch_values" in Collectd. Example:
[ # first call to L<Collectd/plugin_dispatch_values> [ { plugin => "myplugin", type => "gauge", values => [ 1 ] }, ], # second call to L<Collectd/plugin_dispatch_values> [ { plugin => "myplugin", type => "gauge", values => [ 2 ] }, ], ]
A config hash can be provided for plugins with a config callback. The format of this hash must be the same as the one described in collectd-perl's manpage (grep for "Config-Item"). Use "parse" in Test::Collectd::Config for conveniently yielding such a hash from a collectd configuration file. Only the section concerning the plugin should be provided, e.g. without all global collectd config sections.
This module tricks the tested collectd plugins into loading FakeCollectd instead of Collectd, and replaces calls thereof by simple functions which populate the %FakeCollectd:: hash in order to store its arguments. As it uses the name of the calling plugin module for its symbols, subsequent calls to the test subs are not really independant, which is suboptimal especially for a test module. If you have a saner solution to do this, please let me know.
Replacements for most common Collectd::Plugins methods are implemented, as well as constants. We may have missed some or many, and as new ones are added to the main collectd tree, we will have to keep up to date.
Although "parse" in Test::Collectd::Config has been a straight port of liboconfig (which itself is using lex/yacc) to Parse::Yapp/Parse::Lex, you might get different results in edge cases.
liboconfig
lex/yacc
If no types.db list is being specified during construction, the object will try to use the shipped version. Also, if a list is given, the first appearance of the type will be used; this may differ from collectd's mechanism.
FakeCollectd, http://collectd.org/wiki/index.php/Naming_schema
Fabien Wernli, <wernli_workingat_in2p3.fr>
<wernli_workingat_in2p3.fr>
Please report any bugs or feature requests to https://github.com/faxm0dem/Test-Collectd-Plugins/issues.
You can find documentation for this module with the perldoc command.
perldoc Test::Collectd::Plugins
You can also look for information at:
Github: https://github.com/faxm0dem/Test-Collectd-Plugins
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Collectd-Plugins
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Test-Collectd-Plugins
CPAN Ratings
http://cpanratings.perl.org/d/Test-Collectd-Plugins
Search CPAN
http://search.cpan.org/dist/Test-Collectd-Plugins/
Copyright 2012 Fabien Wernli.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install Test::Collectd::Plugins, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Collectd::Plugins
CPAN shell
perl -MCPAN -e shell install Test::Collectd::Plugins
For more information on module installation, please visit the detailed CPAN module installation guide.