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-08Test::BDD::Cucumber::Manual::Architecture(3pm)