Provided by: libtest-bdd-cucumber-perl_0.60-1_all bug

NAME

       Test::BDD::Cucumber::Manual::Steps - How to write Step Definitions

VERSION

       version 0.60

INTRODUCTION

       The 'code' part of a Cucumber test-suite are the Step Definition files which match steps,
       and execute code based on them. This document aims to give you a quick overview of those.

STARTING OFF

       Most of your step files will want to start something like:

        #!perl

        use strict;
        use warnings;

        use Test::More;
        use Test::BDD::Cucumber::StepFile;

       The fake shebang line gives some hints to syntax highlighters, and "use strict;" and "use
       warnings;" are hopefully fairly standard at this point.

       Most of my Step Definition files make use of Test::More, but you can use any Test::Builder
       based testing module. E.g. "Test::Exception".

       Test::BDD::Cucumber::StepFile gives us the functions "Given()", "When()", "Then()" and
       "Step()".

STEP DEFINITIONS

        Given qr/I have (\d+)/, sub {
           S->{'count'} += $1;
        };

        When "The count is an integer", sub {
           S->{'count'} =
               int( S->{'count'} );
        };

        Then qr/The count should be (\d+)/, sub {
           is( S->{'count'}, C->matches->[0], "Count matches" );
        };

       Each of the exported verb functions accept a regular expression (or a string that's used
       as one), and a coderef. The coderef is passed a single argument, the
       Test::BDD::Cucumber::StepContext object. Before the subref is executed, localized
       definitions of "S" and "C" are set, such that the lines below are equivalent:

         # Access the first match
         sub { my $context = shift; print $context->matches->[0] }
         sub { C->matches->[0] }

         # Set a value in the scenario-level stash
         sub { my $context = shift; my $stash = $context->stash->{'scenario'}; $stash->{'count'} = 1 }
         sub { S->{'count'} = 1 }

       We will evaluate the regex immediately before we execute the coderef, so you can use $1,
       $2, $etc. Similarly you can access named matches using $+{match_name}.

   Accessing step, scenario and feature properties
       Step functions have access to the various properties of the step, scenario and feature in
       which they're being used. This includes tags, line numbers, etc. E.g.:

         # Examples of step properties
         C->step->line->number
         C->step->verb
         C->step->original_verb

         # Examples of scenario properties
         C->scenario->name
         C->scenario->tags

         # Examples of feature properties
         C->feature->name
         C->feature->tags
         C->feature->language

       For a full review of available properties, see Test::BDD::Cucumber::Model::Step,
       Test::BDD::Cucumber::Model::Scenario and Test::BDD::Cucumber::Model::Feature respectively.

   Re-using step definitions
       Sometimes you want to call one step from another step. You can do this via the
       StepContext, using the "dispatch()" method. For example:

         Given qr/I have entered (\d+)/, sub {
               C->dispatch( 'Given', "I have pressed $1");
               C->dispatch( 'Given', "I have pressed enter", { some => 'data' } );
         };

       For more on this topic, check the Redispatching section in the documentation for
       "Test::BDD::Cucumber::StepContext".

LOCALIZATION

       Both feature files and step files can be written using non-english Gherkin keywords. A
       german feature file could look like the example below.

         # language: de
         Funktionalität: Grundlegende Taschenrechnerfunktionen
           Um sicherzustellen, dass ich die Calculator-Klasse korrekt programmiert habe,
           möchte ich als Entwickler einige grundlegende Funktionen prüfen,
           damit ich beruhigt meine Calculator-Klasse verwenden kann.

           Szenario: Anzeige des ersten Tastendrucks
             Gegeben sei ein neues Objekt der Klasse Calculator
             Wenn ich 1 gedrückt habe
             Dann ist auf der Anzeige 1 zu sehen

       To see which keywords (and sub names) to use, ask pherkin about a specific language:

        > pherkin --i18n de
        | feature          | "Funktionalität"                             |
        | background       | "Grundlage"                                  |
        ...
        | given (code)     | "Angenommen", "Gegebensei", "Gegebenseien"   |
        | when (code)      | "Wenn"                                       |
        | then (code)      | "Dann"                                       |

       The last three lines of this list show you which sub names to use in your step file as
       indicated by the '(code)' suffix. A corresponding step file specifying a step function for
       "Wenn ich 1 gedrückt habe", could be:

         #!perl

         use strict;
         use warnings;
         use utf8;    # Interpret accented German chars in regexes and identifiers properly

         use Test::More;
         use Test::BDD::Cucumber::StepFile;

         Wenn qr/^ich (.+) gedrückt habe/, sub {
             S->{'Calculator'}->press($_) for split( /(,| und) /, C->matches->[0] );
         };

       For more extensive examples see examples/i18n_de/ and examples/i18n_es.

ADDITIONAL STEPS

       Next to the steps that will be matched directly against feature file input, a number of
       additional step functions are supported:

       ·   "Before" and "After"

           These steps create hooks into the evaluation process of feature files. E.g.

              Before sub {  # Run before every scenario
                 # ... scenario set up code
              };

              After sub {  # Run after every scenario
                # ... scenario tear down code
              };

           For more extensive hook functionality, see Test::BDD::Cucumber::Extension.

       ·   "Transform"

           The "Transform" step serves to map matched values or table rows from feature file
           (string) input to step input values. The step takes two arguments, same as the
           "Given", "When" and "Then" steps: a regular expression and a code reference. E.g.

              Transform qr/^(\d+)$/, sub {
                 # transform matches of digit-only strings

                 my $rv = $1;
                 # ... do something with $rv
                 return $rv;
              };

              Transform qr/^table:col1,col2$/, sub {
                 # transform tables with 2 columns, named col1 and col2 respectively

                 my ($step_context, $data) = @_;
                 # ... transform data in $data
                 return $data;
              };

BEST PRACTICES

       When writing step files, it's a good idea to take a few things into account.

       ·   Declare a "package" at the top of your step file

           By declaring a specific package (your own), you make sure not to step on internals of
           other modules.  At the time of writing, the default package is
           "Test::BDD::Cucumber::StepFile", which may lead to errors being reported in that
           package, even though they occur in your step file (which is confusing).

           The default package may change in the future and it will likely not be seeded with the
           content of the "T::B::C::StepFile" package.

       ·   Declare a different "package" per step file

           By using different packages per step file (or group of step files), name spaces are
           isolated which reduces the risk of importing functions with the same name from
           different packages.

           An example where this will be the case is when some of your step files are written
           using "Test::More" and some others are written using "Test2::Bundle::More" -- both
           export a function "ok", but with conflicting function prototypes.

       ·   Don't define functions in your step file

           Especially step files provided by extensions. Step files may be loaded more than once,
           depending on the exact scenario in which "App::pherkin" is run. When the step files
           are being loaded multiple times, there won't be any impact on step definition, but any
           function definitions will cause 'function redefined' warnings.

NEXT STEPS

       How step files are loaded is discussed in Test::BDD::Cucumber::Manual::Architecture, but
       isn't of much interest. Of far more interest should be seeing what you have available in
       Test::BDD::Cucumber::StepContext...

AUTHOR

       Peter Sergeant "pete@clueball.com"

LICENSE

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