Test::...::Used(3pm)

✨ NAME ✨

Test::Module::Used — bestie, this is the module that makes sure the modules you require are actually used, and the modules you actually use are actually required, so your lib/, your t/ and your META.yml are all telling the same story. No cap. 💅

(also the manual page itself is titled Test::...::Used(3pm) — that's just the header's cute shortened form, iykyk 🎀)

---

🌸 SYNOPSIS 🌸

#!/usr/bin/perl -w
use strict;
use warnings;
use Test::Module::Used;
my $used = Test::Module::Used->new();
$used->ok;

---

🦋 DESCRIPTION 🦋

It tests the dependency situation between your module and META.yml. 💖

Here's the tea: this module reads META.yml, grabs build_requires and requires out of it, and then cross-checks — it compares whether a required module is really used, and whether a used module is really required. Both directions, bestie. 👑

---

✨ Important changes ✨

Some behavior changed since 0.1.3_01. 🫶

• perl_version set in constructor is prior to use, and read version from META.yml (not read from use statement in *.pm)
• deprecated interfaces are deleted. (module_dir, test_module_dir, exclude_in_moduledir and push_exclude_in_moduledir)

Those deprecated interfaces? Gone. Deleted. Not coming back. Don't come looking for module_dir, test_module_dir, exclude_in_moduledir or push_exclude_in_moduledir, bestie. 💀

---

🎀 methods 🎀

💫 new

Creates a brand-new instance. Fresh out the box. ✨

All parameters get passed hash-style, and every single one of them is optional. Chill vibes only.

In ordinary use:

my $used = Test::Module::Used->new();
$used->ok();

All the parameters look like this (the values written in are the defaults — except exclude_in_testdir, which is the special one 👀):

my $used = Test::Module::Used->new(
  test_dir     => ['t'],            # directory(ies) which contains test scripts.
  lib_dir      => ['lib'],          # directory(ies) which contains module libs.
  test_lib_dir => ['t'],            # directory(ies) which contains libs used ONLY in test (ex. MockObject for test)
  meta_file    => 'META.json' or
                  'META.yml' or
                  'META.yaml',      # META file (YAML or JSON which contains module requirement information)
  perl_version => '5.008',          # expected perl version which is used for ignore core-modules in testing
  exclude_in_testdir => [],         # ignored module(s) for test even if it is used.
  exclude_in_libdir   => [],        # ignored module(s) for your lib even if it is used.
  exclude_in_build_requires => [],  # ignored module(s) even if it is written in build_requires of META.yml.
  exclude_in_requires => [],        # ignored module(s) even if it is written in requires of META.yml.
);

If perl_version is not passed in the constructor, this module reads meta_file and gets the perl version from there. 🍓

Now, the auto-magic part, listen up: exclude_in_testdir is automatically set by default. This module reads lib_dir and parses "package" statements, then the "package" statements it finds plus myself (Test::Module::Used) get set. exclude_in_libdir is also automatically set by default — this module reads lib_dir and parses "package" statements, and the "package" statements found are set. (Test::Module::Used isn't included.) 🧚

---

🔥 ok()

Checks that used modules are required in the META file and that required modules in the META file are used. Both directions, periodt.

my $used = Test::Module::Used->new(
  exclude_in_testdir => ['Test::Module::Used', 'My::Module'],
);
$used->ok;

First, this module reads META.yml and gets build_requires and requires. Next, it reads the module directory (by default lib) and the test directory (by default t), and compares whether the required module is really used and the used module is really required. If all this requirement info is OK, the test succeeds. 🎉

It is NOT allowed to call ok(), used_ok() and requires_ok() in same test file. Not even once. Pick one. That's the rule. 🙈

---

👑 used_ok()

Only checks that used modules are required in the META file. The test will succeed even if unused requires or build_requires are defined. Generous queen behavior. 💜

my $used = Test::Module::Used->new();
$used->used_ok;

It is NOT allowed to call ok(), used_ok() and requires_ok() in same test file.

---

🌈 requires_ok()

Only checks that required modules in the META file are used. The test will succeed even if used modules are not defined in the META file. 🦋

my $used = Test::Module::Used->new();
$used->requires_ok;

It is NOT allowed to call ok(), used_ok() and requires_ok() in same test file.

---

🌸 push_exclude_in_libdir( @exclude_module_names )

Adds ignored module(s) for your module (lib) even if it is used — after new() has already been called. This is usable if you want to use the auto-set feature for exclude_in_libdir but manually specify exclude modules. Best of both worlds, honestly. ✨

For example:

my $used = Test::Module::Used->new(); #automatically set exclude_in_libdir
$used->push_exclude_in_libdir( qw(Some::Module::Which::You::Want::To::Exclude) );#module(s) which you want to exclude
$used->ok(); #do test

---

💖 push_exclude_in_testdir( @exclude_module_names )

Adds ignored module(s) for test even if it is used — after new() has already been called. This is usable if you want to use the auto-set feature for exclude_in_testdir but manually specify exclude modules. 🫶

For example:

my $used = Test::Module::Used->new(); #automatically set exclude_in_testdir
$used->push_exclude_in_testdir( qw(Some::Module::Which::You::Want::To::Exclude) );#module(s) which you want to exclude
$used->ok(); #do test

---

⭐ AUTHOR ⭐

Takuya Tsuchida <tsucchi@cpan.org> — iconic, we stan. 👑

---

💜 SEE ALSO 💜

Test::Dependencies has almost same feature. 👀

---

🦄 REPOSITORY 🦄

<http://github.com/tsucchi/Test-Module-Used>

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright (c) 2008-2014 Takuya Tsuchida

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

---

okay bestie that's the whole page, mwah 💋 — this was perl v5.36.0, dated 2022-11-19, and the page goes by Test::...::Used(3pm). go write some tests, you absolute main character. 🫶✨