Test::...ctation(3pm)

🦋 Test::Synopsis::Expectation — the Test::...ctation(3pm) page, but make it make sense

okay bestie, so this is a User Contributed Perl Documentation page, and no cap it's one of my faves. It's Test::Synopsis::Expectation 💅 and it does exactly what the name says but cuter: it takes the SYNOPSIS in your docs and actually runs it, then checks the results against little comment annotations you sprinkle in. iconic behaviour fr fr.

---

✨ NAME ✨

Test::Synopsis::Expectation — test that SYNOPSIS code produces expected results. periodt. 🎀

---

💖 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

like… see how every line has a lil # => whisper next to it? that's the whole vibe bestie 🫶

---

🌸 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. it's giving "your docs are now also your test suite" main character energy 👑

---

✨ FUNCTIONS ✨

• synopsis_ok($files) — This function tests SYNOPSIS codes of each files. It 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. It 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. (This function is not exported 🙈)

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

the way that it literally prepends your setup code for you… obsessed.

• 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. yes bestie, that line just gets skipped entirely, no notes ✨

---

🎀 NOTATION OF EXPECTATION 🎀

Comment that starts at "# =>" then this module treats the comment as test statement. that's the magic string, the secret little handshake 🤝

• # => 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". same energy, less typing 💅

• # => 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. 🙏 manifesting passes for you

---

🦋 ANNOTATIONS 🦋

• =for test_synopsis_expectation_no_test

The code block behind this annotation will not be tested. it's the "do not perceive me" annotation 🙈

    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. so that deliberately-wrong # => 2 up there is chilling, unbothered, moisturized 🧖‍♀️

---

💀 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. no multi-line annotation glow-ups allowed, sorry bestie 😭

🚫 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). so like… don't 💀 the author is being so real with that parenthetical, iykyk.

---

👑 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

the ... gets politely ignored, hands off, no thoughts head empty — and your test still runs. ate. 🍓

---

🔥 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 🐇

<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 <moznion@gmail.com>

---

and that's the whole page bestie 🫶 this was Test::...ctation(3pm) from the User Contributed Perl Documentation, shipped with perl v5.36.0, dated 2022-10-14 — go annotate your SYNOPSIS and slay ✨💅🎀