DOKK / manpages / debian 12 / libtest-synopsis-expectation-perl / Test::Synopsis::Expectation.3pm.en
Test::Synopsis::Expectation(3pm) User Contributed Perl Documentation Test::Synopsis::Expectation(3pm)

Test::Synopsis::Expectation - Test that SYNOPSIS code produces expected results

    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

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.

  • 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.

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.

•
=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.

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.

    # 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).

This module ignores yada-yada operators that is in SYNOPSIS code. Thus, following code is runnable.

    my $foo;
    ...
    $foo = 1; # => 1

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.

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

Copyright (C) moznion.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

moznion <moznion@gmail.com>

2022-10-14 perl v5.34.0