https://github.com/moznion/test-synopsis-expectation
Test SYNOPSIS code with expectations
https://github.com/moznion/test-synopsis-expectation
Last synced: 8 months ago
JSON representation
Test SYNOPSIS code with expectations
- Host: GitHub
- URL: https://github.com/moznion/test-synopsis-expectation
- Owner: moznion
- License: other
- Created: 2013-12-04T08:22:53.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2014-12-16T02:27:56.000Z (over 11 years ago)
- Last Synced: 2025-01-31T07:34:18.786Z (over 1 year ago)
- Language: Perl
- Homepage: https://metacpan.org/release/Test-Synopsis-Expectation
- Size: 305 KB
- Stars: 5
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: Changes
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/moznion/Test-Synopsis-Expectation) [](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