---
name: "Dist::Zilla::Util::Test::KENTNL::dztest"
section: "3pm"
platform: "linux"
package: "libdist-zilla-util-test-kentnl-perl"
version: "1.005014-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Dist::Zilla::Util::Test::KENTNL::dztest"
---

# Dist::Zilla::Util::Test::KENTNL::dztest(3pm)

Shared dist testing logic for easy dzil things

## NAME

Dist::Zilla::Util::Test::KENTNL::dztest - Shared dist testing logic for easy dzil things

## VERSION

version 1.005014

## SYNOPSIS

```
  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');
```

## METHODS

### "add\_file"

Add a file to the scratch directory to be built.

```
  # ->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"`

`"BAIL_OUT"` is triggered if any of `"add_file"` don't arrive in the intended location.

### "prereqs\_deeply"

Demand `"distmeta"` `"prereqs"` exactly match those specified.

```
  $test->prereqs_deeply( { hash } );
```

This is just a more memorable version of

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

### "has\_messages"

Test that there are messages, and all the given rules match messages.

```
  $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 compare 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.

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

### "create\_plugin"

Create an instance of the named plugin and return it.

```
  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 inter-operating with `"dzil"` phases, but has the downside of not interacting with `"dzil"` phases, or even being *\*seen\** by `"dzil"` phases.

But this is OK if you want to directly test a modules interface instead of doing it through the proxy of `"dzil"`

You can also subsequently create many such objects without requiring a `"dzil build"` penalty.

### "source\_file"

Re-fetch content added with `"add_file"`.

You probably want `"built_file"`.

```
  $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"

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

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

### "note\_tempdir\_files"

Recursively walk `"tempdir"` and note its contents.

### "note\_builddir\_files"

Recursively walk `"builddir"`(output) and note its contents.

### "has\_message"

Assert there are messages, and 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 I'm yet to work out the meaning of the latter.

## ATTRIBUTES

### "configure"

Construct the internal builder object.

```
  $test->configure;
```

## AUTHOR

Kent Fredric \<kentnl@cpan.org\>

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