1Test::Synopsis(3) User Contributed Perl Documentation Test::Synopsis(3)
2
6 Test::Synopsis - Test your SYNOPSIS code
7
9 # xt/synopsis.t (with Module::Install::AuthorTests)
10 use Test::Synopsis;
11 all_synopsis_ok();
12 # Or, run safe without Test::Synopsis
14 use Test::More;
15 eval "use Test::Synopsis";
16 plan skip_all => "Test::Synopsis required for testing" if $@;
17 all_synopsis_ok();
18
20 Test::Synopsis is an (author) test module to find .pm or .pod files
21 under your lib directory and then make sure the example snippet code in
22 your SYNOPSIS section passes the perl compile check.
23 Note that this module only checks the perl syntax (by wrapping the code
25 with "sub") and doesn't actually run the code, UNLESS that code is a
26 "BEGIN {}" block or a "use" statement.
27 Suppose you have the following POD in your module.
29 =head1 NAME
31 Awesome::Template - My awesome template
33 =head1 SYNOPSIS
35 use Awesome::Template;
37 my $template = Awesome::Template->new;
39 $tempalte->render("template.at");
40 =head1 DESCRIPTION
42 An user of your module would try copy-paste this synopsis code and find
44 that this code doesn't compile because there's a typo in your variable
45 name $tempalte. Test::Synopsis will catch that error before you ship
46 it.
47
49 Sometimes you might want to put some undeclared variables in your
50 synopsis, like:
51 =head1 SYNOPSIS
53 use Data::Dumper::Names;
55 print Dumper($scalar, \@array, \%hash);
56 This assumes these variables like $scalar are defined elsewhere in
58 module user's code, but Test::Synopsis, by default, will complain that
59 these variables are not declared:
60 Global symbol "$scalar" requires explicit package name at ...
62 In this case, you can add the following POD sequence elsewhere in your
64 POD:
65 =for test_synopsis
67 no strict 'vars'
68 Or more explicitly,
70 =for test_synopsis
72 my($scalar, @array, %hash);
73 Test::Synopsis will find these "=for" blocks and these statements are
75 prepended before your SYNOPSIS code when being evaluated, so those
76 variable name errors will go away, without adding unnecessary bits in
77 SYNOPSIS which might confuse users.
78
80 You can use a "BEGIN{}" block in the "=for test_synopsis" to check for
81 specific conditions (e.g. if a module is present), and possibly skip
82 the test.
83 If you die() inside the "BEGIN{}" block and the die message begins with
85 sequence "SKIP:" (note the colon at the end), the test will be skipped
86 for that document.
87 =head1 SYNOPSIS
89 =for test_synopsis BEGIN { die "SKIP: skip this pod, it's horrible!\n"; }
91 $x; # undeclared variable, but we skipped the test!
93 =end
95
97 "all_synopsis_ok"
98 all_synopsis_ok();
99 all_synopsis_ok( dump_all_code_on_error => 1 );
101 Checks the SYNOPSIS code in all your modules. Takes optional arguments
103 as key/value pairs. Possible arguments are as follows:
104 "dump_all_code_on_error"
106 all_synopsis_ok( dump_all_code_on_error => 1 );
108 Takes true or false values as a value. Defaults to: false. When set to
110 a true value, if an error is discovered in the SYNOPSIS code, the test
111 will dump the entire snippet of code it tried to test. Use this if you
112 want to copy/paste and play around with the code until the error is
113 fixed.
114 The dumped code will include any of the "=for" code you specified (see
116 "VARIABLE DECLARATIONS" section above) as well as a few internal bits
117 this test module uses to make SYNOPSIS code checking possible.
118 Note: you will likely have to remove the "#" and a space at the start
120 of each line ("perl -pi -e 's/^#\s//;' TEMP_FILE_WITH_CODE")
121 "synopsis_ok"
123 use Test::More tests => 1;
124 use Test::Synopsis;
125 synopsis_ok("t/lib/NoPod.pm");
126 synopsis_ok(qw/Pod1.pm Pod2.pm Pod3.pm/);
127 Lets you test a single file. Note: you must setup your own plan if you
129 use this subroutine (e.g. with "use Test::More tests => 1;"). Takes a
130 list of filenames for documents containing SYNOPSIS code to test.
131
133 This module will not check code past the "__END__" or "__DATA__"
134 tokens, if one is present in the SYNOPSIS code.
135 This module will actually execute "use" statements and any code you
137 specify in the "BEGIN {}" blocks in the SYNOPSIS.
138 If you're using HEREDOCs in your SYNOPSIS, you will need to place the
140 ending of the HEREDOC at the same indent as the first line of the code
141 of your SYNOPSIS.
142 Redefinition warnings can be turned off with
144 =for test_synopsis
146 no warnings 'redefine';
147
149 Fork this module on GitHub: <https://github.com/miyagawa/Test-Synopsis>
150
152 To report bugs or request features, please use
153 <https://github.com/miyagawa/Test-Synopsis/issues>
154 If you can't access GitHub, you can email your request to
156 "bug-Test-Synopsis at rt.cpan.org"
157
159 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
160 Goro Fuji blogged about the original idea at
162 <http://d.hatena.ne.jp/gfx/20090224/1235449381> based on the testing
163 code taken from Test::Weaken.
164
166 Zoffix Znet <cpan (at) zoffix.com>
167
169 • Dave Rolsky (DROLSKY <https://metacpan.org/author/DROLSKY>)
170 • Kevin Ryde (KRYDE <https://metacpan.org/author/KRYDE>)
172 • Marcel Grünauer (MARCEL <https://metacpan.org/author/MARCEL>)
174 • Mike Doherty (DOHERTY <https://metacpan.org/author/DOHERTY>)
176 • Patrice Clement (monsieurp <https://github.com/monsieurp>)
178 • Greg Sabino Mullane (TURNSTEP
180 <https://metacpan.org/author/TURNSTEP>)
181 • Zoffix Znet (ZOFFIX <https://metacpan.org/author/ZOFFIX>)
183 • Olivier Mengué (DOLMEN <https://metacpan.org/author/DOLMEN>)
185
187 This library is free software; you can redistribute it and/or modify it
188 under the same terms as Perl itself.
189
191 This library is Copyright (c) Tatsuhiko Miyagawa
192
194 Test::Pod, Test::UseAllModules, Test::Inline,
195 Test::Synopsis::Expectation
196perl v5.36.0 2023-01-20 Test::Synopsis(3)