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

NAME

6       Test::Synopsis - Test your SYNOPSIS code
7

SYNOPSIS

9         # xt/synopsis.t (with Module::Install::AuthorTests)
10         use Test::Synopsis;
11         all_synopsis_ok();
12
13         # 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

DESCRIPTION

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
24       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
28       Suppose you have the following POD in your module.
29
30         =head1 NAME
31
32         Awesome::Template - My awesome template
33
34         =head1 SYNOPSIS
35
36           use Awesome::Template;
37
38           my $template = Awesome::Template->new;
39           $tempalte->render("template.at");
40
41         =head1 DESCRIPTION
42
43       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

VARIABLE DECLARATIONS

49       Sometimes you might want to put some undeclared variables in your
50       synopsis, like:
51
52         =head1 SYNOPSIS
53
54           use Data::Dumper::Names;
55           print Dumper($scalar, \@array, \%hash);
56
57       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
61           Global symbol "$scalar" requires explicit package name at ...
62
63       In this case, you can add the following POD sequence elsewhere in your
64       POD:
65
66         =for test_synopsis
67         no strict 'vars'
68
69       Or more explicitly,
70
71         =for test_synopsis
72         my($scalar, @array, %hash);
73
74       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

SKIPPING TEST FROM INSIDE THE POD

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
84       If you "die()" inside the "BEGIN{}" block and the die message begins
85       with sequence "SKIP:" (note the colon at the end), the test will be
86       skipped for that document.
87
88         =head1 SYNOPSIS
89
90         =for test_synopsis BEGIN { die "SKIP: skip this pod, it's horrible!\n"; }
91
92             $x; # undeclared variable, but we skipped the test!
93
94         =end
95

EXPORTED SUBROUTINES

97   "all_synopsis_ok"
98         all_synopsis_ok();
99
100         all_synopsis_ok( dump_all_code_on_error => 1 );
101
102       Checks the SYNOPSIS code in all your modules. Takes optional arguments
103       as key/value pairs. Possible arguments are as follows:
104
105       "dump_all_code_on_error"
106
107         all_synopsis_ok( dump_all_code_on_error => 1 );
108
109       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
115       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
119       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
122   "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
128       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

CAVEATS

133       This module will not check code past the "__END__" or "__DATA__"
134       tokens, if one is present in the SYNOPSIS code.
135
136       This module will actually execute "use" statements and any code you
137       specify in the "BEGIN {}" blocks in the SYNOPSIS.
138
139       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
143       Redefinition warnings can be turned off with
144
145         =for test_synopsis
146         no warnings 'redefine';
147

REPOSITORY

149       Fork this module on GitHub: <https://github.com/miyagawa/Test-Synopsis>
150

BUGS

152       To report bugs or request features, please use
153       <https://github.com/miyagawa/Test-Synopsis/issues>
154
155       If you can't access GitHub, you can email your request to
156       "bug-Test-Synopsis at rt.cpan.org"
157

AUTHOR

159       Tatsuhiko Miyagawa <miyagawa@bulknews.net>
160
161       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

MAINTAINER

166       Zoffix Znet <cpan (at) zoffix.com>
167

CONTRIBUTORS

169       ·   Dave Rolsky (DROLSKY <https://metacpan.org/author/DROLSKY>)
170
171       ·   Kevin Ryde (KRYDE <https://metacpan.org/author/KRYDE>)
172
173       ·   Marcel Grünauer (MARCEL <https://metacpan.org/author/MARCEL>)
174
175       ·   Mike Doherty (DOHERTY <https://metacpan.org/author/DOHERTY>)
176
177       ·   Patrice Clement (monsieurp <https://github.com/monsieurp>)
178
179       ·   Greg Sabino Mullane (TURNSTEP
180           <https://metacpan.org/author/TURNSTEP>)
181
182       ·   Zoffix Znet (ZOFFIX <https://metacpan.org/author/ZOFFIX>)
183
184       ·   Olivier Mengué (DOLMEN <https://metacpan.org/author/DOLMEN>)
185

LICENSE

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

SEE ALSO

194       Test::Pod, Test::UseAllModules, Test::Inline
195
196
197
198perl v5.32.0                      2020-07-28                 Test::Synopsis(3)
Impressum