Test::Exports(3pm)

🎀 Test::Exports 🎀

hiii bestie, welcome to the Test::Exports era 💅 this one lives in the User Contributed Perl Documentation section of your friendly neighbourhood perldoc, and it is literally the module you want when you gotta make sure your module exports the right stuff. no cap.

---

✨ NAME ✨

Test::Exports — test that modules export the right symbols 🦋

---

🌸 SYNOPSIS 🌸

use Test::More;
use Test::Exports;

require_ok "My::Module" or BAIL_OUT "can't load module";

import_ok "My::Module", [],             "default import OK";
is_import qw/foo bar/, "My::Module",    "imports subs";

new_import_pkg;

import_ok "My::Module", ["foo"],        "named import OK";
is_import "foo", "My::Module",          "imports foo";
cant_ok "bar",                          "doesn't import bar";

like. look at her go. ✨

---

💜 DESCRIPTION 💜

okay so this module hands you a lil' set of test functions for testing other modules' import methods. right now the testing is limited to checking which subs have been imported — that's the whole vibe, no more no less.

here's the clever bit 🧠 in order to keep all your different calls to ->import from smushing into each other, Test::Exports does those calls from a private package. then the symbol-testing functions go check whether those symbols are hanging out in that private package or not — which means none of this interferes with your test script itself. periodt. 💅

---

🫶 FUNCTIONS 🫶

all of these are exported by default, as is the norm with testing modules, iykyk.

new_import_pkg

make a brand new package to perform imports into 🎀 this is the move when you wanna test ->import with different arguments — because otherwise you'd be stuck tryna find some way of going back and clearing up the imports from the last call, and that's giving pain honestly.

it returns the name of the new package (which is gonna look like Test::Exports::TestAAAAB) in case you need it. 👑

import_ok $module, \@args, $name

calls $module->import from the current testing package, passes it @args, and checks the call succeeded. and what counts as "success" here? not throwing an exception — because use doesn't care if import returns false, so neither do we. fr fr. 🤝

@args defaults to the empty list; $name defaults to something sensible.

import_nok $module, \@args, $name

calls $module->import(@args) and expects it to throw an exception 💀 defaults are the same as for import_ok.

is_import @subs, $module, $name

for each name in @subs, check that the current testing package has a sub by that name and that it's the same as the equinominal sub in the $module package. yes, "equinominal". iconic word, ate.

⚠️ neither $module nor $name is optional. you must pass both. no skipping bestie.

cant_ok @subs, $name

for each sub in @subs, check that a sub of that name does not exist in the current testing package. and if one is found, the diagnostic will indicate where it was originally defined, to help you track down that stray export. detective mode activated 🔍✨

---

🦋 TODO 🦋

is_import

right now this just checks that \&Our::Pkg::sub == \&Your::Pkg::sub, which means:

• it is impossible to test for exports which have been renamed, and
• we can't be sure the sub originally came from Your::Pkg: it may have been exported into both packages from somewhere else. 🙈

it would be good to fix at least the former. (the first one. bestie. the renaming one.)

---

👑 AUTHOR 👑

Ben Morrow <ben@morrow.me.uk> 💖

---

💀 BUGS 💀

please report any bugs to <bug-Test-Exports@rt.cpan.org>. don't be shy, they wanna hear it.

---

🌈 COPYRIGHT 🌈

Copyright 2010 Ben Morrow.

redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

yeah that's the legal bit, i'm not paraphrasing that one, i have self-preservation instincts. 💅

---

aaaand that's the whole page bestie 🎀 this was written for perl v5.32.1, dated 2021-09-19, and yes it's the Test::Exports(3pm) page — go write some tests and slay 💖✨🦋