Test::Synopsis::Expectation(3pm)

1Test::Synopsis::ExpectaUtsieorn(C3opnmt)ributed Perl DocTuemsetn:t:aStyinoonpsis::Expectation(3pm)
2
3
4

NAME

6       Test::Synopsis::Expectation - Test that SYNOPSIS code produces expected
7       results
8

SYNOPSIS

10           use Test::Synopsis::Expectation;
11
12           synopsis_ok('eg/sample.pod');
13           done_testing;
14
15       Following, SYNOPSIS of eg/sample.pod
16
17           my $num;
18           $num = 1; # => 1
19           ++$num;   # => is 2
20
21           use PPI::Tokenizer;
22           my $tokenizer = PPI::Tokenizer->new(\'code'); # => isa 'PPI::Tokenizer'
23
24           my $str = 'Hello, I love you'; # => like qr/ove/
25
26           my $obj = {
27               foo => ["bar", "baz"],
28           }; # => is_deeply { foo => ["bar", "baz"] }
29
30           my $bool = 1; # => success
31

DESCRIPTION

33       This module checks that a module's SYNOPSIS section is syntactically
34       correct, and will also check that it produces the expected results,
35       based on annotations you add in comments.
36

FUNCTIONS

38       •   synopsis_ok($files)
39
40           This function tests SYNOPSIS codes of each files.  This function
41           expects file names as an argument as ARRAYREF or SCALAR.  (This
42           function is exported)
43
44       •   all_synopsis_ok()
45
46           This function tests SYNOPSIS codes of the all of library files.
47           This function uses MANIFEST to list up the target files of testing.
48           (This function is exported)
49
50       •   prepare($code_str)
51
52           Register the executable codes to prepare for evaluation.
53
54           If you use like;
55
56               use Test::Synopsis::Expectation;
57               Test::Synopsis::Expectation::prepare('my $foo = 1;');
58               synopsis_ok('path/to/target.pm');
59               done_testing;
60
61               ### Following, SYNOPSIS of `target.pm`
62               $foo; # => 1
63
64           Then, SYNOPSIS of target.pm is the same as;
65
66               my $foo = 1;
67               $foo; # => 1
68
69           (This function is not exported)
70
71       •   set_ignorings
72
73           Set the procedures which would like to ignore.
74
75               use Test::Synopsis::Expectation;
76               Test::Synopsis::Expectation::set_ignorings(['++$num;']);
77               synopsis_ok(*DATA);
78               done_testing;
79
80               __DATA__
81               =head1 SYNOPSIS
82
83                   my $num;
84                   $num = 1; # => 1
85                   ++$num;
86                   $num; # => 1
87
88           In the above example, "++$num;" will be ignored.
89

NOTATION OF EXPECTATION

91       Comment that starts at "# =>" then this module treats the comment as
92       test statement.
93
94       •   # => is
95
96               my $foo = 1; # => is 1
97
98           This way is equivalent to the next.
99
100               my $foo = 1;
101               is $foo, 1;
102
103           This carries out the same behavior as "Test::More::is".
104
105       •   # =>
106
107               my $foo = 1; # => 1
108
109           This notation is the same as "# => is"
110
111       •   # => isa
112
113               use Foo::Bar;
114               my $instance = Foo::Bar->new; # => isa 'Foo::Bar'
115
116           This way is equivalent to the next.
117
118               use Foo::Bar;
119               my $instance = Foo::Bar->new;
120               isa_ok $instance, 'Foo::Bar';
121
122           This carries out the same behavior as "Test::More::isa_ok".
123
124       •   # => like
125
126               my $str = 'Hello, I love you'; # => like qr/ove/
127
128           This way is equivalent to the next.
129
130               my $str = 'Hello, I love you';
131               like $str, qr/ove/;
132
133           This carries out the same behavior as "Test::More::like".
134
135       •   # => is_deeply
136
137               my $obj = {
138                   foo => ["bar", "baz"],
139               }; # => is_deeply { foo => ["bar", "baz"] }
140
141           This way is equivalent to the next.
142
143               my $obj = {
144                   foo => ["bar", "baz"],
145               };
146               is_deeply $obj, { foo => ["bar", "baz"] };
147
148           This carries out the same behavior as "Test::More::is_deeply".
149
150       •   # => success
151
152               my $bool = 1;
153               $bool; # => success
154
155           This way checks value as boolean.  If target value of testing is 0
156           then this test will fail. Otherwise, it will pass.
157

ANNOTATIONS

159       •   =for test_synopsis_expectation_no_test
160
161           The code block behind this annotation will not be tested.
162
163                   my $sum;
164                   $sum = 1; # => 1
165
166               =for test_synopsis_expectation_no_test
167
168                   my $sum;
169                   $sum = 1; # => 2
170
171           In this example, the first code block will be tested, but the
172           second will not.
173

RESTRICTION

175   Test case must be one line
176       The following is valid;
177
178           my $obj = {
179               foo => ["bar", "baz"],
180           }; # => is_deeply { foo => ["bar", "baz"] }
181
182       However, the following is invalid;
183
184           my $obj = {
185               foo => ["bar", "baz"],
186           }; # => is_deeply {
187              #        foo => ["bar", "baz"]
188              #    }
189
190       So test case must be one line.
191
192   Not put test cases inside of for(each)
193           # Example of not working
194           for (1..10) {
195               my $foo = $_; # => 10
196           }
197
198       This example doesn't work. On the contrary, it will be error (Probably
199       nobody uses such as this way... I think).
200

NOTES

202   yada-yada operator
203       This module ignores yada-yada operators that is in SYNOPSIS code.
204       Thus, following code is runnable.
205
206           my $foo;
207           ...
208           $foo = 1; # => 1
209

REPOSITORY

219       <https://github.com/moznion/Test-Synopsis-Expectation>
220

LICENSE

222       Copyright (C) moznion.
223
224       This library is free software; you can redistribute it and/or modify it
225       under the same terms as Perl itself.
226

AUTHOR

228       moznion <moznion@gmail.com>
229
230
231
232perl v5.38.0                      2023-07-25  Test::Synopsis::Expectation(3pm)