[![Build Status](https://travis-ci.org/moznion/Test-Synopsis-Expectation.svg?branch=master)](https://travis-ci.org/moznion/Test-Synopsis-Expectation) [![Coverage Status](https://img.shields.io/coveralls/moznion/Test-Synopsis-Expectation/master.svg)](https://coveralls.io/r/moznion/Test-Synopsis-Expectation?branch=master) # NAME Test::Synopsis::Expectation - Test that SYNOPSIS code produces expected results # SYNOPSIS use Test::Synopsis::Expectation; synopsis_ok('eg/sample.pod'); done_testing; Following, SYNOPSIS of `eg/sample.pod` my $num; $num = 1; # => 1 ++$num; # => is 2 use PPI::Tokenizer; my $tokenizer = PPI::Tokenizer->new(\'code'); # => isa 'PPI::Tokenizer' my $str = 'Hello, I love you'; # => like qr/ove/ my $obj = { foo => ["bar", "baz"], }; # => is_deeply { foo => ["bar", "baz"] } my $bool = 1; # => success # DESCRIPTION This module checks that a module's SYNOPSIS section is syntactically correct, and will also check that it produces the expected results, based on annotations you add in comments. # FUNCTIONS - synopsis\_ok($files) This function tests SYNOPSIS codes of each files. This function expects file names as an argument as ARRAYREF or SCALAR. (This function is exported) - all\_synopsis\_ok() This function tests SYNOPSIS codes of the all of library files. This function uses `MANIFEST` to list up the target files of testing. (This function is exported) - prepare($code\_str) Register the executable codes to prepare for evaluation. If you use like; use Test::Synopsis::Expectation; Test::Synopsis::Expectation::prepare('my $foo = 1;'); synopsis_ok('path/to/target.pm'); done_testing; ### Following, SYNOPSIS of `target.pm` $foo; # => 1 Then, SYNOPSIS of `target.pm` is the same as; my $foo = 1; $foo; # => 1 (This function is not exported) - set\_ignorings Set the procedures which would like to ignore. use Test::Synopsis::Expectation; Test::Synopsis::Expectation::set_ignorings(['++$num;']); synopsis_ok(*DATA); done_testing; __DATA__ =head1 SYNOPSIS my $num; $num = 1; # => 1 ++$num; $num; # => 1 In the above example, `++$num;` will be ignored. # NOTATION OF EXPECTATION Comment that starts at `# =>` then this module treats the comment as test statement. - # => is my $foo = 1; # => is 1 This way is equivalent to the next. my $foo = 1; is $foo, 1; This carries out the same behavior as `Test::More::is`. - # => my $foo = 1; # => 1 This notation is the same as `# => is` - # => isa use Foo::Bar; my $instance = Foo::Bar->new; # => isa 'Foo::Bar' This way is equivalent to the next. use Foo::Bar; my $instance = Foo::Bar->new; isa_ok $instance, 'Foo::Bar'; This carries out the same behavior as `Test::More::isa_ok`. - # => like my $str = 'Hello, I love you'; # => like qr/ove/ This way is equivalent to the next. my $str = 'Hello, I love you'; like $str, qr/ove/; This carries out the same behavior as `Test::More::like`. - # => is\_deeply my $obj = { foo => ["bar", "baz"], }; # => is_deeply { foo => ["bar", "baz"] } This way is equivalent to the next. my $obj = { foo => ["bar", "baz"], }; is_deeply $obj, { foo => ["bar", "baz"] }; This carries out the same behavior as `Test::More::is_deeply`. - # => success my $bool = 1; $bool; # => success This way checks value as boolean. If target value of testing is 0 then this test will fail. Otherwise, it will pass. # ANNOTATIONS - =for test\_synopsis\_expectation\_no\_test The code block behind this annotation will not be tested. my $sum; $sum = 1; # => 1 =for test_synopsis_expectation_no_test my $sum; $sum = 1; # => 2 In this example, the first code block will be tested, but the second will not. # RESTRICTION ## Test case must be one line The following is valid; my $obj = { foo => ["bar", "baz"], }; # => is_deeply { foo => ["bar", "baz"] } However, the following is invalid; my $obj = { foo => ["bar", "baz"], }; # => is_deeply { # foo => ["bar", "baz"] # } So test case must be one line. ## Not put test cases inside of for(each) # Example of not working for (1..10) { my $foo = $_; # => 10 } This example doesn't work. On the contrary, it will be error (Probably nobody uses such as this way... I think). # NOTES ## yada-yada operator This module ignores yada-yada operators that is in SYNOPSIS code. Thus, following code is runnable. my $foo; ... $foo = 1; # => 1 # SEE ALSO [Test::Synopsis](https://metacpan.org/pod/Test::Synopsis) - simpler module, which just checks the syntax of your SYNOPSIS section. [Dist::Zilla::Plugin::Test::Synopsis](https://metacpan.org/pod/Dist::Zilla::Plugin::Test::Synopsis) - a plugin for [Dist::Zilla](https://metacpan.org/pod/Dist::Zilla) users, which adds a release test to your distribution, based on [Test::Synopsis](https://metacpan.org/pod/Test::Synopsis). # REPOSITORY [https://github.com/moznion/Test-Synopsis-Expectation](https://github.com/moznion/Test-Synopsis-Expectation) # LICENSE Copyright (C) moznion. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. # AUTHOR moznion