NAME

       Test::BDD::Cucumber::Manual::Architecture - Structural Overview

VERSION

       version 0.86

INTRODUCTION

       This short document exists to give you an idea how the different components of this distribution fit
       together. Components fall into three categories: one for dealing with definition of the step functions
       (Perl code), the other for dealing with feature files. And then there's the third group, with
       "Test::BDD::Cucumber::Executor" which links the two groups together; building on the steps to execute the
       features.

       In the first group are "Test::BDD::Cucumber::StepFile" and "Test::BDD::Cucumber::Loader". The second
       group is bigger and is comprised of

       •   "Test::BDD::Cucumber::Parser"

       •   "Test::BDD::Cucumber::Model::*"

       The third group holds - next to "Test::BDD::Cucumber::Executor":

       •   "Test::BDD::Cucumber::Harness::*"

       •   "Test::BDD::Cucumber::StepContext"

       •   "Test::BDD::Cucumber::Errors"

       •   "Test::BDD::Cucumber::Extension"

       Please  note  that  the  "Test::BDD::Cucumber::Harness"  should  not  be  confused with "TAP::Harness" or
       "Test2::Harness"; this harness is TBC's own and optionally forwards events to  the  "Test::Builder::Test"
       harness.

MODELS

       The  core  of  a  Cucumber-based  test  suite  are  the  feature files and the step definitions files. By
       convention, these are saved under "/features/" and "/features/step_definitions/" respectively.

       The feature files are encapsulated by the classes in "Test::BDD::Cucumber::Model".

                         one to one
        TBCM::Feature<----------------->TBCM::Document
             |                               |
             +-------------------+           |
             | has many          | has a     | has many
             V                   |           V
        TBCM::Scenario           +----->TBCM::Line
             |                            ^  ^
             +----------------------------+  |
             | has many                      |
             V                               |
        TBCM::Step---------------------------+

EXECUTOR

       We build up a Test::BDD::Cucumber::Executor object, in to which we load the  step  definitions.  We  then
       pass  this  in  a  Test::BDD::Cucumber::Model::Feature  object, along with a Test::BDD::Cucumber::Harness
       object, which controls interaction with the outside world.

   Test::Builder
       While running step functions, "Test::BDD::Cucumber::Executor" reroutes the flow of test events (calls  to
       "ok",  "fail",  etc)  to itself. Based on the collected data, the step itself is reported as a success or
       failure to the test driver.

       Confusing about this situation is that both the channel to report through to the actual test driver is an
       instance of Test::Builder as well as the method used to route the stream of test events to itself uses  a
       Test::Builder instance.

EXTENSION

       Extensions  allow hooking into the execution of the steps, with pre- and post hooks for steps, scenarios,
       features and the entire execution. Extensions can provide additional step directories  from  which  steps
       will be made available. The feature and scenario stashes are passed to the extension hooks allowing for a
       means of communication between the hooks and the steps.

       Additionally,  as  of  0.60,  it's possible to define meta data for a step upon step definition like this
       example:

         Given qr/a step with meta data/ => { meta => 'data' }, sub { };

       This allows step function authors to communicate with extensions, because extensions  receive  this  meta
       data in their "pre_step" callback:

         sub pre_step {
           my ($stepdef, $step_context) = @_;
           my ($verb, $metadata, $stepfn) = @$stepdef;

           die 'All steps should have meta -> data'
             unless $metadata->{meta} eq 'data';
         }

       Extensions - when loaded by the pherkin test executor - receive their configuration from the pherkin.yaml
       configuration   file,   which   works   similar   to   the   configuration   of   extensions   in   Behat
       <http://docs.behat.org/en/v2.5/guides/7.config.html#extensions>.

       Note: when using extensions in combination  with  the  "TAP::Parser::SourceHandler::Feature"  plugin  for
       "prove",  there  is  no guarantee that the "pre_execute" and "post_execute" hooks execute exactly once or
       even execute at all.  This is a current limitation to be lifted in a future release.

AUTHOR

       Peter Sergeant "pete@clueball.com"

LICENSE

         Copyright 2019-2023, Erik Huelsmann
         Copyright 2011-2019, Peter Sergeant; Licensed under the same terms as Perl

perl v5.36.0                                       2023-08-29              Test::BDD::Cuc...l::Architecture(3pm)