table of contents
Test::Synopsis::Expectation(3pm) | User Contributed Perl Documentation | Test::Synopsis::Expectation(3pm) |
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 - simpler module, which just checks the syntax of your SYNOPSIS section.
Dist::Zilla::Plugin::Test::Synopsis - a plugin for Dist::Zilla users, which adds a release test to your distribution, based on Test::Synopsis.
REPOSITORY¶
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 <moznion@gmail.com>
2022-10-14 | perl v5.34.0 |