/ 
Test-Dist-Zilla-v0.4.1
River stage one • 8 direct dependents • 8 total dependents
/ Test::Dist::Zilla

NAME

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

VERSION

Version v0.4.1, released on 2015-10-29 22:06 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();
    if ( exists( $expected->{ exception } ) ) {
        cmp_deeply( $self->exception, $expected->{ exception } );
    } else {
        is( $self->exception, undef );
    };
    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     => 'Assa',
        version  => '0.007',
        author   => 'John Doe',
        ...
    },
    ...
};

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' => "lib/Assa.pm\nChanges\nMANIFEST\n",
} };

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 in anyway.

Note: Avoid calling build on tzil:

$self->tzil->build();

Call build directly on $self instead:

$self->build();

See build method description for difference.

Examples:

use Path::Tiny;
tests 'Check META.json' => sub {
    my ( $self ) = @_;
    if ( $self->exception ) {
        plan skip_all => 'exception occurred';
    };
    my $built_in = path( $self->tzil->built_in );
    my $json = $built_in->child( 'META.json' )->slurp;
    cmp_deeply( $json, $self->expected->{ json } );
};

exception

Exception occurred during build, or undef is no exception were occurred.

test 'Post-build' => sub {
    my ( $self ) = @_;
    if ( $self->exception ) {
        plan skip_all => 'exception thrown';
    };
    ...
};

expected

A hash of expected outcomes. Test::Dist::Zilla itself does 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 the 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 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

The method calls same-name method on tzil, catches exception if any thrown, and saves the caught exception in exception attribute for further analysis.

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

Examples:

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

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 } );

SEE ALSO

Test::Dist::Zilla::Build
Test::Routine
Dist::Zilla
Dist::Zilla::Tester::DieHard
"dist_ini" in Test::DZil

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2015 Van de Bugger

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.