package Test::BDD::Cucumber::Manual::Integration;

=head1 NAME

Test::BDD::Cucumber::Manual::Integration - Test suite integration options

=head1 VERSION

version 0.75

=head1 DESCRIPTION

How to use Test::BDD::Cucumber in your test suite

=head1 OVERVIEW

Test::BDD::Cucumber offers two options to integrate your tests with your
test framework:

 1. Integration with C<prove> which will run your .feature
    files as it does .t files
 2. Creation of a .t file which fires off your selected .feature files
    (Test::Builder integration)

The benefits from using the former approach is that all C<prove>'s advanced
features like parallel testing, randomized order, C<--state>ful runs,
JUnit output, etc., are available out of the box.


=head1 prove integration

With Test::BDD::Cucumber installed in the Perl search path (PERL5LIB)
comes the possibility to run the .feature files with a C<prove> command
directly, by specifying

 $ prove -r
         --source Feature
         --ext=.feature
         --feature-option tags=~@wip
         t/

This command registers a C<prove> plugin named C<Feature> associated with
the C<.feature> extension.  Additionally, it passes a tag filter to exclude
@wip tagged features and scenarios from being run.

When executed, the command searches the C<t/> directory recursively for files
with the C<.feature> extension.  For each directory holding at least one
C<.feature> file, the step files are loaded from the C<step_definitions/>
subdirectory.

The command above will find and run I<only> C<.feature> files. When you want
to run your regular C<.t> files as well as Test::BDD::Cucumber's
C<.feature> files, run the following command:

 $ prove -r
         --source Perl
         --ext=.t
         --source Feature
         --ext=.feature
         --feature-option tags=~@wip
         t/



=head1 Test::Builder integration -- a documented example

The code below needs to be stored in a C<.t> file in the C<t/> or C<xt/>
directory. When done that way, the tests are integrated into C<make test>
as generated from C<make test> after C<perl Makefile.PL>.

 #!perl

 use strict;
 use warnings;

 # This will find step definitions and feature files in the directory you point
 # it at below
 use Test::BDD::Cucumber::Loader;

 # This harness prints out nice TAP
 use Test::BDD::Cucumber::Harness::TAP;

 # Load a directory with Cucumber files in it. It will recursively execute any
 # file matching .*_steps.pl as a Step file, and .*\.feature as a feature file.
 # The features are returned in @features, and the executor is created with the
 # step definitions loaded.
 my ( $executor, @features ) = Test::BDD::Cucumber::Loader->load(
        't/cucumber_core_features/' );

 # Create a Harness to execute against. TAP harness prints TAP
 my $harness = Test::BDD::Cucumber::Harness::TAP->new({});

 # For each feature found, execute it, using the Harness to print results
 $executor->execute( $_, $harness ) for @features;

 # Shutdown gracefully
 $harness->shutdown();

=cut

1;