Test::Valgrind(3pm)

1Test::Valgrind(3)     User Contributed Perl Documentation    Test::Valgrind(3)
2
3
4

NAME

6       Test::Valgrind - Generate suppressions, analyse and test any command
7       with valgrind.
8

VERSION

10       Version 1.19
11

SYNOPSIS

13           # From the command-line
14           perl -MTest::Valgrind leaky.pl
15
16           # From the command-line, snippet style
17           perl -MTest::Valgrind -e 'leaky()'
18
19           # In a test file
20           use Test::More;
21           eval 'use Test::Valgrind';
22           plan skip_all => 'Test::Valgrind is required to test your distribution with valgrind' if $@;
23           leaky();
24
25           # In all the test files of a directory
26           prove --exec 'perl -Iblib/lib -Iblib/arch -MTest::Valgrind' t/*.t
27

DESCRIPTION

29       This module is a front-end to the "Test::Valgrind::*" API that lets you
30       run Perl code through the "memcheck" tool of the "valgrind" memory
31       debugger, to test for memory errors and leaks.  If they aren't
32       available yet, it will first generate suppressions for the current
33       "perl" interpreter and store them in the portable flavour of
34       ~/.perl/Test-Valgrind/suppressions/$VERSION.  The actual run will then
35       take place, and tests will be passed or failed according to the result
36       of the analysis.
37
38       The complete API is much more versatile than this.  By declaring an
39       appropriate Test::Valgrind::Command class, you can run any executable
40       (that is, not only Perl scripts) under valgrind, generate the
41       corresponding suppressions on-the-fly and convert the analysis result
42       to TAP output so that it can be incorporated into your project's
43       testsuite.  If you're not interested in producing TAP, you can output
44       the results in whatever format you like (for example HTML pages) by
45       defining your own Test::Valgrind::Action class.
46
47       Due to the nature of perl's memory allocator, this module can't track
48       leaks of Perl objects.  This includes non-mortalized scalars and memory
49       cycles.  However, it can track leaks of chunks of memory allocated in
50       XS extensions with "Newx" and friends or "malloc".  As such, it's
51       complementary to the other very good leak detectors listed in the "SEE
52       ALSO" section.
53

METHODS

55   "analyse"
56           Test::Valgrind->analyse(%options);
57
58       Run a "valgrind" analysis configured by %options :
59
60       •   "command => $command"
61
62           The Test::Valgrind::Command object (or class name) to use.
63
64           Defaults to Test::Valgrind::Command::PerlScript.
65
66       •   "tool => $tool"
67
68           The Test::Valgrind::Tool object (or class name) to use.
69
70           Defaults to Test::Valgrind::Tool::memcheck.
71
72       •   "action => $action"
73
74           The Test::Valgrind::Action object (or class name) to use.
75
76           Defaults to Test::Valgrind::Action::Test.
77
78       •   "file => $file"
79
80           The file name of the script to analyse.
81
82           Ignored if you supply your own custom "command", but mandatory
83           otherwise.
84
85       •   "callers => $number"
86
87           Specify the maximum stack depth studied when valgrind encounters an
88           error.  Raising this number improves granularity.
89
90           Ignored if you supply your own custom "tool", otherwise defaults to
91           24 (the maximum allowed by "valgrind").
92
93       •   "diag => $bool"
94
95           If true, print the output of the test script as diagnostics.
96
97           Ignored if you supply your own custom "action", otherwise defaults
98           to false.
99
100       •   "regen_def_supp => $bool"
101
102           If true, forcefully regenerate the default suppression file.
103
104           Defaults to false.
105
106       •   "no_def_supp => $bool"
107
108           If true, do not use the default suppression file.
109
110           Defaults to false.
111
112       •   "allow_no_supp => $bool"
113
114           If true, force running the analysis even if the suppression files
115           do not refer to any "perl"-related symbol.
116
117           Defaults to false.
118
119       •   "extra_supps => \@files"
120
121           Also use suppressions from @files besides "perl"'s.
122
123           Defaults to empty.
124
125   "import"
126           use Test::Valgrind %options;
127
128       In the parent process, "import" calls "analyse" with the arguments it
129       received itself - except that if no "file" option was supplied, it
130       tries to pick the first caller context that looks like a script.  When
131       the analysis ends, it exits with the status returned by the action (for
132       the default TAP-generator action, it's the number of failed tests).
133
134       In the child process, it just "return"s so that the calling code is
135       actually run under "valgrind", albeit two side-effects :
136
137       •   Perl::Destruct::Level is loaded and the destruction level is set to
138           3.
139
140       •   Autoflush on "STDOUT" is turned on.
141

VARIABLES

143   $dl_unload
144       When set to true, all dynamic extensions that were loaded during the
145       analysis will be unloaded at "END" time by "dl_unload_file" in
146       DynaLoader.
147
148       Since this obfuscates error stack traces, it's disabled by default.
149

CAVEATS

151       Perl 5.8 is notorious for leaking like there's no tomorrow, so the
152       suppressions are very likely not to be complete on it.  You also have a
153       better chance to get more accurate results if your perl is built with
154       debugging enabled.  Using the latest "valgrind" available will also
155       help.
156
157       This module is not really secure.  It's definitely not taint safe.
158       That shouldn't be a problem for test files.
159
160       What your tests output to "STDOUT" and "STDERR" is eaten unless you
161       pass the "diag" option, in which case it will be reprinted as
162       diagnostics.
163

DEPENDENCIES

165       XML::Twig, File::HomeDir, Env::Sanctify, Perl::Destruct::Level.
166

AUTHOR

179       Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
180
181       You can contact me by mail or on "irc.perl.org" (vincent).
182

BUGS

184       Please report any bugs or feature requests to "bug-test-valgrind at
185       rt.cpan.org", or through the web interface at
186       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Valgrind>.  I will
187       be notified, and then you'll automatically be notified of progress on
188       your bug as I make changes.
189

SUPPORT

191       You can find documentation for this module with the perldoc command.
192
193           perldoc Test::Valgrind
194

ACKNOWLEDGEMENTS

196       Rafaël Garcia-Suarez, for writing and instructing me about the
197       existence of Perl::Destruct::Level (Elizabeth Mattijsen is a close
198       second).
199
200       H.Merijn Brand, for daring to test this thing.
201
202       David Cantrell, for providing shell access to one of his smokers where
203       the tests were failing.
204
205       The Debian-perl team, for offering all the feedback they could
206       regarding the build issues they met.
207
208       All you people that showed interest in this module, which motivated me
209       into completely rewriting it.
210

COPYRIGHT & LICENSE

212       Copyright 2008,2009,2010,2011,2013,2015,2016 Vincent Pit, all rights
213       reserved.
214
215       This program is free software; you can redistribute it and/or modify it
216       under the same terms as Perl itself.
217
218
219
220perl v5.32.1                      2021-01-27                 Test::Valgrind(3)