Dist::...:dztest(3pm)

💖 Dist::Zilla::Util::Test::KENTNL::dztest — the manual page, but make it make sense 💖

okay bestie, so this is the dztest page from the Dist::Zilla::Util::Test::KENTNL family, and it lives in section 3pm of the perl docs. it's the shared dist-testing logic that makes dzil stuff easy to test. yes, the real name up top is Dist::...:dztest(3pm) because perl doc tooling loves to abbreviate, but you and me both know what it is 🫶

---

✨ NAME ✨

Dist::Zilla::Util::Test::KENTNL::dztest — the shared dist testing logic for easy dzil things. it's giving "one helper to rule all your test files" energy 👑

---

🌸 VERSION 🌸

version 1.005014 — that's the one, no cap.

---

🦋 SYNOPSIS 🦋

here's the whole vibe in one go, literally copy-paste territory:

  use Test::More;
  use Test::DZil qw( simple_ini );
  use Dist::Zilla::Util::Test::KENTNL qw( dztest );

  my $test = dztest;

  ## utility method.
  $test->add_file( 'dist.ini', simple_ini( .... ));

  ## build the dist
  # 1x subtest
  $test->build_ok;

  ## assert prereqs are identical to the hash
  ## extracting them from distmeta
  # 1x subtest
  $test->prereqs_deeply( { } );

  ## Test for specific log messages by regex
  # 1x subtest
  #  - tests there are messages
  #  - each regex must match a message
  my @list = (
    [ $regex, $indepdent_reason ],
    [ $regex ],
  );
  $test->has_messages( $reason, \@list );

  ## Test for any deep structure addressed
  ## By a Data::DPath expression
  # 1x subtest
  #   - asserts the expression returns a result
  #   - compares the structure against the expected one.
  $test->meta_path_deeply(
      '/author/*/[1]',
      [ 'E. Xavier Ample <example@example.org>' ],
      'The 1st author is the example author emitted by simple_ini'
  );

  ## Test for a file existing on the build side
  ## and return it if it exists.
  my $file = $test->test_has_built_file('dist.ini');

like, that's the whole tour. slay 💅

---

🎀 METHODS 🎀

💜 "add_file"

drop a file into the scratch directory so it can be built later. think of it as prepping your little dist before the glow-up ✨

  # ->add_file( $path, $string );
  # ->add_file( \@path, $string );
  $test->add_file('dist.ini', simple_ini() );
  $test->add_file('lib/Foo.pm', $content );
  $test->add_file([ 'lib','Foo.pm' ], $content );

---

💜 "build_ok"

build the dist safely, and report "ok" if the dist builds "ok", spewing file listings via "note".

bestie, heads up: "BAIL_OUT" gets triggered if any of your "add_file" calls don't arrive in the intended location. so if your file is missing, the whole thing nopes out. no silent failures here 💀

---

💜 "prereqs_deeply"

demand that "distmeta" "prereqs" exactly match the ones you specified. exact match. not "close enough". exact. periodt.

  $test->prereqs_deeply( { hash } );

this is literally just a more memorable version of:

  $test->meta_path_deeply('/prereqs/', { });

---

💜 "has_messages"

test that there are messages, and that all the given rules match messages. every regex has to land on something, fr fr.

  $test->has_messages( 'Some descriptor', [
     [ $regex, $description ],
     [ $regex, $description ],
  ]);

---

💜 "meta_path_deeply"

  $test->meta_path_deeply( $expression, $expected_data, $reason );

uses $expression as a "Data::DPath" expression to pick a LIST of nodes from "distmeta", and compares that LIST vs $expected_data. 🧚

  # Matches only the first author.
  $test->meta_path_deeply('/author/*/[1]', ['SomeAuthorName <wadef@wath>'], $reason );

  # Matches all authors
  $test->meta_path_deeply('/author/*/*', ['SomeAuthorName <wadef@wath>','Author2', ..], $reason );

---

💜 "test_has_built_file"

test (as in, "Test::More::ok") that a file exists in the "dzil" build output directory.

also returns it if it exists. so you get the verdict and the goods. two-for-one 🍓

  $test->test_has_built_file('dist.ini');  # ok/fail

  my $object = test->test_has_built_file('dist.ini'); # ok/fail + return

---

💜 "create_plugin"

make an instance of the named plugin and hand it back to you. main character plugin energy 👑

  my $t = dztest();
  $t->add_file('dist.ini', simple_ini( ... ));
  my $plugin = $t->create_plugin('GatherDir' => { ignore_dotfiles => 1 });
  # poke at $plugin here

note: this lets you test plugins outside the requirement of interoperating with "dzil" phases, but the downside is that it doesn't interact with "dzil" phases — and it won't even be seen by "dzil" phases. yes, seen. with asterisks and everything. iconic. 👀

but that's totally OK if you want to directly test a module's interface instead of doing it through the proxy of "dzil".

and bonus: you can subsequently create many such objects without requiring a "dzil build" penalty. no tax, just vibes ✨

---

💜 "source_file"

re-fetch content you added with "add_file".

you probably want "built_file" though, just saying 🙈

  $test->source_file( $path  );
  $test->source_file( \@path );

returns "undef" if the file does not exist.

  if ( my $content = $test->source_file('dist.ini') ) {
    print $content->slurp_raw;
  }

---

💜 "safe_build"

make sure the distribution is built safely, returns exceptions or "undef".

  if ( $test->safe_build ) {
    say "Failed build";
  }

---

💜 "safe_configure"

construct the internal builder object safely. returns exceptions or "undef".

  if( $test->configure ) { say "configure failed" }

---

💜 "built_file"

returns the named file if it exists in the build, "undef" otherwise. simple as. 🦋

  my $file = $test->built_file('dist.ini');

---

💜 "note_tempdir_files"

recursively walk "tempdir" and note its contents. a lil stroll through your temp dir 🌈

---

💜 "note_builddir_files"

recursively walk "builddir"(output) and note its contents. same stroll, but the output side 🎀

---

💜 "has_message"

assert there are messages, and that this single message exists:

  $test->has_message( $regex, $description );

---

💜 "run_command"

execute a Dist::Zilla command in the constructed scratch directory.

  $test->run_command(['build','foo']);

the syntax is technically:

  $test->run_command( $argv, $arg );

but, and I quote the author's own vibe here, they're yet to work out the meaning of the latter. 😭 honestly same.

---

💅 ATTRIBUTES 💅

🌸 "configure"

construct the internal builder object.

  $test->configure;

---

👑 AUTHOR 👑

Kent Fredric <kentnl@cpan.org> — the legend themself.

---

🌈 COPYRIGHT AND LICENSE 🌈

this software is copyright (c) 2017 by Kent Fredric <kentnl@cpan.org>.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie!! 💖 this one's from the perl docs as shipped with perl v5.34.0, dated 2022-06-13, and it's the Dist::...:dztest(3pm) page under User Contributed Perl Documentation. go forth and test your dists, you absolute icon 🫶✨