NAME

Test::Dist::Zilla - Test your Dist::Zilla plugin

VERSION

Version v0.4.4, released on 2016-12-28 19:48 UTC.

SYNOPSIS

    package Test::Dist::Zilla::Build;

    use namespace::autoclean;
    use Test::Routine;
    use Test::Deep qw{ cmp_deeply };

    with 'Test::Dist::Zilla';

    test 'Build' => sub {
        my ( $self ) = @_;
        my $expected = $self->expected;
        $self->build();
        cmp_deeply( $self->exception, $expected->{ exception } );
        if ( exists( $expected->{ messages } ) ) {
            cmp_deeply( $self->messages, $expected->{ messages } );
        };
    };

    1;

DESCRIPTION

This is a Test::Routine-based role. It does not provide any test routines, but it establishes infrastructure for writing tests on Dist::Zilla and its plugins. A test written with Test::Dist::Zila does not require external source files (which are usually placed into corpus/ directory) — all the source files (including dist.ini) for the test are generated on-the-fly in a temporary directory.

The role is not intended to be used directly in tests. Instead, it serves as a base for other more specific roles, for example, Test::Dist::Zilla::Build.

OBJECT ATTRIBUTES

`dist`

Hash of distribution options: name, version abstract, etc. to write to the test's dist.ini. This attribute is passed to dist_ini as \%root_config argument, see "dist_ini" in Test::DZil.

HashRef. Default value can be overridden by defining _build_dist builder.

Examples:

    sub _build_dist { {
        name     => 'Assa',
        version  => '0.007',
        author   => 'John Doe',
        ...
    } };

    run_me {
        dist => {
            name     => 'Shooba',
            version  => 'v0.7.0',
            author   => 'John Doe, Jr.',
            ...
        },
        ...
    };

TODO: Merge specified keys into default?

`plugins`

Plugin configuration to write to the test's dist.ini. Attribute is passed to dist_ini as @plugins argument, see "dist_ini" in Test::DZil.

ArrayRef, optional. Default value is empty array (i. e. no plugins), it can be overridden by defining _build_plugins builder.

Examples:

    sub _build_plugin { [
        'GatherDir',
        'Manifest',
        'MetaJSON',
    ] };

    run_me {
        plugins => [
            'GatherDir',
            [ 'PodWeaver' => {
                'replacer' => 'replace_with_comment',
            } ],
        ],
        ...
    };

`files`

Hash of source files to add to the test's distribution source. Keys are file names, values are file contents. A file content may be specified by a (possibly multi-line) string or by array of lines (newlines are optional and will be appended if missed).

Note: Explicitly specified dist.ini file overrides dist and plugins attributes.

HashRef, optional, default value is empty hash (i. e. no files).

Examples:

    sub _build_files { {
        'lib/Assa.pm' => [
            'package Assa;',
            '# VERSION',
            '1;',
        ],
        'Changes'  => "Release history for Dist-Zilla-Plugin-Assa\n\n",
        'MANIFEST' => [ qw{ lib/Assa.pm Changes MANIFEST } ],
    } };

    run_me {
        files => {
            'lib/Assa.pod' => [ ... ],
            ...
        },
        ...
    };

`tzil`

Test-enabled Dist::Zilla instance (or DieHard "survivor" object, if Dist::Zilla constructing fails).

By default Dist::Zilla instance is created by calling Builder->from_config( ... ) with appropriate arguments. Thanks to Dist::Zilla::Tester::DieHard, it is never dies even if constructing fails, so $self->tzil->log_message returns the log messages anyway.

Note: Avoid calling build and release on tzil:

    $self->tzil->build();       # NOT recommended
    $self->tzil->release();     # NOT recommended

Call build and release directly on $self instead:

    $self->build();             # recommended
    $self->release();           # recommended

See build and release method descriptions for difference.

Examples:

    use Path::Tiny;
    test 'Check META.json' => sub {
        my ( $self ) = @_;
        $self->skip_if_exception();
        my $built_in = path( $self->tzil->built_in );
        my $json = $built_in->child( 'META.json' )->slurp_utf8;
        cmp_deeply( $json, $self->expected->{ json } );
    };

`exception`

Exception occurred, or undef is no exception was occurred.

    test 'Post-build' => sub {
        my ( $self ) = @_;
        cmp_deeply( $self->exception, $self->expected->{ exception } );
        ...
    };

`expected`

A hash of expected outcomes. Test::Dist::Zilla itself does not use this attribute, but more specific roles may do. For example, Test::Dizt::Zilla::Build uses exception and messages keys, Test::Dizt::Zilla::BuiltFiles uses files key.

HashRef, required.

Examples:

    run_me {
        ...,
        expected => {
            exception => "Aborting...\n",
            messages  => [
                '[Plugin] Oops, something goes wrong...',
            ],
        },
    };

`message_filter`

If message_filter is defined, it is used by default messages implementation to filter the actual log messages. message_filter function is called once with list of all the log messages. The function is expected to return a list of messages (possibly, grepped and/or edited).

Note: message_filter value is a function, not method — messages method does not pass $self reference to the message_filter.

If messages method is overridden, the attribute may be used or ignored — it depends on new messages implementation.

Maybe[CodeRef], optional. There is no default message filter — messages method returns all the messages intact. Default message filter may be set by defining _build_message_filter builder.

Examples:

Pass messages only from Manifest plugin and filter out all other messages:

    sub _build_message_filter {
        sub { grep( { $_ =~ m{^\[Manifest\] } ) @_ ) };
    };

Drop plugin names from messages:

    run_me {
        message_filter => sub { map( { $_ =~ s{^\[.*?\] }{}r ) @_ ) },
        ...
    };

OBJECT METHODS

`build`

`release`

The methods call same-name method on tzil, catch exception if any thrown, and save the caught exception in the exception attribute for further analysis.

Avoid calling these methods on tzil — some tests may rely on method modifiers, which are applicable to $self->method() but not to $self->tzil->method().

Examples:

    test Build => sub {
        my ( $self ) = @_;
        $self->build();     # == dzil build
        ...
    };

    test Release => sub {
        my ( $self ) = @_;
        $self->release();   # == dzil release
        ...
    };

`messages`

This method is assumed to return ArrayRef of Dist::Zilla log messages. It may be complete log as it is or not — the method may filter out and/or edit actual messages to make them more suitable for comparing with expected messages.

Default implementation filters the actual messages with the message_filter (if it is defined). If default behaviour is not suitable, the method can be overridden.

Examples:

    cmp_deeply( $self->messages, $self->expected->{ messages } );

skip_if_exception

This convenience method makes test routines a bit shorter. Instead of writing

    if ( defined( $self->exception ) ) {
        plan skip_all => 'exception occurred';
    };

you can write just

    $self->skip_if_exception;

VARIABLES

$Cleanup

Dist::Zilla::Tester creates distribution source and build directories in a temporary directory, and then unconditionally cleans it up. Sometimes (especially in case of test failure) such behavior may be not desirable — you may want to look at source or built files for troubleshooting purposes.

Test::Dist::Zilla provides control over temporary directory via $Test::Dist::Zilla::Cleanup package variable:

0: Never clean up temporary directory.
1: Clean up temporary directory only if the test is passed (it is default).
2: Always clean up temporary directory.

If temporary directory is going to remain, the test output will contain diagnostic message like this one:

    # tempdir: tmp/AKrvBhhM4M

to help you identify the temporary directory created for the test.

Note: Controlling temporary directory requires Dist::Zilla 5.021 or newer.

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

License GPLv3+: The GNU General Public License version 3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

To install Test::Dist::Zilla, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Test::Dist::Zilla

CPAN shell

perl -MCPAN -e shell
install Test::Dist::Zilla

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

OBJECT ATTRIBUTES

dist

plugins

files

tzil

exception

expected

message_filter

OBJECT METHODS

build

release

messages

skip_if_exception

VARIABLES

$Cleanup

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

`dist`

`plugins`

`files`

`tzil`

`exception`

`expected`

`message_filter`

`build`

`release`

`messages`