2 Test::Valgrind - Test Perl code through valgrind.
8 # From the command-line
9 perl -MTest::Valgrind leaky.pl
11 # From the command-line, snippet style
12 perl -MTest::Valgrind -e 'leaky()'
16 eval 'use Test::Valgrind';
17 plan skip_all => 'Test::Valgrind is required to test your distribution with valgrind' if $@;
20 # In all the test files of a directory
21 prove --exec 'perl -Iblib/lib -Iblib/arch -MTest::Valgrind' t/*.t
24 This module is a front-end to the "Test::Valgrind::*" API that lets you
25 run Perl code through the "memcheck" tool of the "valgrind" memory
26 debugger, to test it for memory errors and leaks. If they aren't
27 available yet, it will first generate suppressions for the current
28 "perl" interpreter and store them in the portable flavour of
29 ~/.perl/Test-Valgrind/suppressions/$VERSION. The actual run will then
30 take place, and tests will be passed or failed according to the result
33 Due to the nature of perl's memory allocator, this module can't track
34 leaks of Perl objects. This includes non-mortalized scalars and memory
35 cycles. However, it can track leaks of chunks of memory allocated in XS
36 extensions with "Newx" and friends or "malloc". As such, it's
37 complementary to the other very good leak detectors listed in the "SEE
41 "analyse [ %options ]"
42 Run a "valgrind" analysis configured by %options :
44 * "command => $command"
46 The Test::Valgrind::Command object (or class name) to use.
48 Defaults to Test::Valgrind::Command::PerlScript.
52 The Test::Valgrind::Tool object (or class name) to use.
54 Defaults to Test::Valgrind::Tool::memcheck.
58 The Test::Valgrind::Action object (or class name) to use.
60 Defaults to Test::Valgrind::Action::Test.
64 The file name of the script to analyse.
66 Ignored if you supply your own custom "command", but mandatory
69 * "callers => $number"
71 Specify the maximum stack depth studied when valgrind encounters an
72 error. Raising this number improves granularity.
74 Ignored if you supply your own custom "tool", otherwise defaults to
79 If true, print the output of the test script as diagnostics.
81 Ignored if you supply your own custom "action", otherwise defaults
84 * "extra_supps => \@files"
86 Also use suppressions from @files besides "perl"'s.
90 * "no_def_supp => $bool"
92 If true, do not use the default suppression file.
97 In the parent process, "import" calls "analyse" with the arguments it
98 received itself - except that if no "file" option was supplied, it tries
99 to pick the highest caller context that looks like a script. When the
100 analyse finishes, it exists with the status that was returned.
102 In the child process, it just "return"s so that the calling code is
103 actually run under "valgrind".
107 When set to true, all dynamic extensions that were loaded during the
108 analysis will be unloaded at "END" time by DynaLoader::dl_unload_file.
110 Since this obfuscates error stack traces, it's disabled by default.
113 Perl 5.8 is notorious for leaking like there's no tomorrow, so the
114 suppressions are very likely not to be very accurate on it. Anyhow,
115 results will most likely be better if your perl is built with debugging
116 enabled. Using the latest "valgrind" available will also help.
118 This module is not really secure. It's definitely not taint safe. That
119 shouldn't be a problem for test files.
121 What your tests output to "STDOUT" and "STDERR" is eaten unless you pass
122 the "diag" option, in which case it will be reprinted as diagnostics.
125 Valgrind 3.1.0 (<http://valgrind.org>).
127 XML::Twig, version, File::HomeDir, Env::Sanctify, Perl::Destruct::Level.
130 All the "Test::Valgrind::*" API, including Test::Valgrind::Command,
131 Test::Valgrind::Tool, Test::Valgrind::Action and
132 Test::Valgrind::Session.
136 Devel::Leak, Devel::LeakTrace, Devel::LeakTrace::Fast.
139 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
141 You can contact me by mail or on "irc.perl.org" (vincent).
144 Please report any bugs or feature requests to "bug-test-valgrind at
145 rt.cpan.org", or through the web interface at
146 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Valgrind>. I will
147 be notified, and then you'll automatically be notified of progress on
148 your bug as I make changes.
151 You can find documentation for this module with the perldoc command.
153 perldoc Test::Valgrind
156 Rafaƫl Garcia-Suarez, for writing and instructing me about the
157 existence of Perl::Destruct::Level (Elizabeth Mattijsen is a close
160 H.Merijn Brand, for daring to test this thing.
162 All you people that showed interest in this module, which motivated me
163 into completely rewriting it.
166 Copyright 2008-2009 Vincent Pit, all rights reserved.
168 This program is free software; you can redistribute it and/or modify it
169 under the same terms as Perl itself.