.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::BDD::Cucumber::Manual::Integration 3pm"
.TH Test::BDD::Cucumber::Manual::Integration 3pm "2023-08-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::BDD::Cucumber::Manual::Integration \- Test suite integration options
.SH "VERSION"
.IX Header "VERSION"
version 0.86
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
How to use Test::BDD::Cucumber in your test suite
.SH "OVERVIEW"
.IX Header "OVERVIEW"
Test::BDD::Cucumber offers two options to integrate your tests with your
test framework:
.PP
.Vb 4
\& 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)
.Ve
.PP
The benefits from using the former approach is that all \f(CW\*(C`prove\*(C'\fR's advanced
features like parallel testing, randomized order, \f(CW\*(C`\-\-state\*(C'\fRful runs,
JUnit output, etc., are available out of the box.
.SH "prove integration"
.IX Header "prove integration"
With Test::BDD::Cucumber installed in the Perl search path (\s-1PERL5LIB\s0)
comes the possibility to run the .feature files with a \f(CW\*(C`prove\*(C'\fR command
directly, by specifying
.PP
.Vb 5
\& $ prove \-r
\&         \-\-source Feature
\&         \-\-ext=.feature
\&         \-\-feature\-option tags=~@wip
\&         t/
.Ve
.PP
This command registers a \f(CW\*(C`prove\*(C'\fR plugin named \f(CW\*(C`Feature\*(C'\fR associated with
the \f(CW\*(C`.feature\*(C'\fR extension.  Additionally, it passes a tag filter to exclude
\&\f(CW@wip\fR tagged features and scenarios from being run.
.PP
When executed, the command searches the \f(CW\*(C`t/\*(C'\fR directory recursively for files
with the \f(CW\*(C`.feature\*(C'\fR extension.  For each directory holding at least one
\&\f(CW\*(C`.feature\*(C'\fR file, the step files are loaded from the \f(CW\*(C`step_definitions/\*(C'\fR
subdirectory.
.PP
The command above will find and run \fIonly\fR \f(CW\*(C`.feature\*(C'\fR files. When you want
to run your regular \f(CW\*(C`.t\*(C'\fR files as well as Test::BDD::Cucumber's
\&\f(CW\*(C`.feature\*(C'\fR files, run the following command:
.PP
.Vb 7
\& $ prove \-r
\&         \-\-source Perl
\&         \-\-ext=.t
\&         \-\-source Feature
\&         \-\-ext=.feature
\&         \-\-feature\-option tags=~@wip
\&         t/
.Ve
.SH "Test::Builder integration \*(-- a documented example"
.IX Header "Test::Builder integration a documented example"
The code below needs to be stored in a \f(CW\*(C`.t\*(C'\fR file in the \f(CW\*(C`t/\*(C'\fR or \f(CW\*(C`xt/\*(C'\fR
directory. When done that way, the tests are integrated into \f(CW\*(C`make test\*(C'\fR
as generated from \f(CW\*(C`make test\*(C'\fR after \f(CW\*(C`perl Makefile.PL\*(C'\fR.
.PP
.Vb 1
\& #!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 .*\e.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(
\&        \*(Aqt/cucumber_core_features/\*(Aq );
\&
\& # 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();
.Ve