.\" 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::StepContext 3pm"
.TH Test::BDD::Cucumber::StepContext 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::StepContext \- Data made available to step definitions
.SH "VERSION"
.IX Header "VERSION"
version 0.86
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The coderefs in Step Definitions have a single argument passed to them, a
\&\f(CW\*(C`Test::BDD::Cucumber::StepContext\*(C'\fR object. This is an attribute-only class,
populated by Test::BDD::Cucumber::Executor.
.PP
When steps are run normally, \f(CW\*(C`C()\*(C'\fR is set directly before execution to return
the context; this allows you to do:
.PP
.Vb 1
\&  sub { return C\->columns }
.Ve
.PP
instead of:
.PP
.Vb 1
\&  sub { my $c = shift; return $c\->columns; }
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "columns"
.IX Subsection "columns"
If the step-specific data supplied is a table, the this attribute will contain
the column names in the order they appeared.
.SS "_data"
.IX Subsection "_data"
Step-specific data. Will either be a text string in the case of a """ string, or
an arrayref of hashrefs if the step had an associated table.
.PP
See the \f(CW\*(C`data\*(C'\fR method below.
.SS "stash"
.IX Subsection "stash"
A hash of hashes, containing two keys, \f(CW\*(C`feature\*(C'\fR, \f(CW\*(C`scenario\*(C'\fR.
The stash allows you to persist data across features or scenarios.
.PP
The scenario-level stash is also available to steps by calling \f(CW\*(C`S()\*(C'\fR, making
the following two lines of code equivalent:
.PP
.Vb 2
\& sub { my $context = shift; my $stash = $context\->stash\->{\*(Aqscenario\*(Aq}; $stash\->{\*(Aqcount\*(Aq} = 1 }
\& sub { S\->{\*(Aqcount\*(Aq} = 1 }
.Ve
.SS "feature"
.IX Subsection "feature"
.SS "scenario"
.IX Subsection "scenario"
.SS "step"
.IX Subsection "step"
Links to the Test::BDD::Cucumber::Model::Feature,
Test::BDD::Cucumber::Model::Scenario, and Test::BDD::Cucumber::Model::Step
objects respectively.
.SS "verb"
.IX Subsection "verb"
The lower-cased verb a Step Definition was called with.
.SS "text"
.IX Subsection "text"
The text of the step, minus the verb. Placeholders will have already been
multiplied out at this point.
.SS "harness"
.IX Subsection "harness"
The Test::BDD::Cucumber::Harness harness being used by the executor.
.SS "executor"
.IX Subsection "executor"
Weak reference to the Test::BDD::Cucumber::Executor being used \- this allows
for step redispatch.
.SS "matches"
.IX Subsection "matches"
Any matches caught by the Step Definition's regex. These are also available as
\&\f(CW$1\fR, \f(CW$2\fR etc as appropriate.
.SS "is_hook"
.IX Subsection "is_hook"
The harness processing the output can decide whether to shop information for
this step which is actually an internal hook, i.e. a Before or After step
.SS "parent"
.IX Subsection "parent"
If a step redispatches to another step, the child step will have a link back to
its parent step here; otherwise undef. See \*(L"Redispatching\*(R".
.SH "METHODS"
.IX Header "METHODS"
.SS "background"
.IX Subsection "background"
Boolean for \*(L"is this step being run as part of the background section?\*(R".
Currently implemented by asking the linked Scenario object...
.SS "data"
.IX Subsection "data"
See the \f(CW\*(C`_data\*(C'\fR attribute above.
.PP
Calling this method will return either the """ string, or a possibly Transform-ed
set of table data.
.SS "matches"
.IX Subsection "matches"
See the \f(CW\*(C`_matches\*(C'\fR attribute above.
.PP
Call this method will return the possibly Transform-ed matches .
.SS "transform"
.IX Subsection "transform"
Used internally to transform data and placeholders, but it can also be called
from within your Given/When/Then code.
.SH "Redispatching"
.IX Header "Redispatching"
Sometimes you want to call one step from another step. You can do this via the
\&\fIStepContext\fR, using the \f(CW\*(C`dispatch()\*(C'\fR method. For example:
.PP
.Vb 5
\&  Given qr/I have entered (\ed+)/, sub {
\&        C\->dispatch( \*(AqGiven\*(Aq, "I have pressed $1");
\&        C_>dispatch( \*(AqGiven\*(Aq, "I have passed\-in data", C\->data );
\&        C\->dispatch( \*(AqGiven\*(Aq, "I have pressed enter", { some => \*(Aqdata\*(Aq } );
\&  };
.Ve
.PP
You redispatch step will have its own, new step context with almost everything
copied from the parent step context. However, specifically not copied are:
\&\f(CW\*(C`columns\*(C'\fR, \f(CW\*(C`data\*(C'\fR, the \f(CW\*(C`step\*(C'\fR object, and of course the \f(CW\*(C`verb\*(C'\fR and the
\&\f(CW\*(C`text\*(C'\fR.
.PP
If you want to pass data to your child step, you should \s-1IDEALLY\s0 do it via the
text of the step itself, or failing that, through the scenario-level stash.
Otherwise it'd make more sense just to be calling some subroutine... But you
\&\fBcan\fR pass in a third argument \- a hashref which will be used as \f(CW\*(C`data\*(C'\fR. The
data in that third argument can be one of:
.IP "\(bu" 4
a string
.Sp
This scenario corresponds with having a \f(CW""" ... """\fR string argument
to the step. It's passed to the child step verbatim.
.IP "\(bu" 4
a hash reference (deprecated)
.Sp
This scenario corresponds with the third example above and has been
supported historically. There is no good reason to use this type of
argument passing, because there is no way for a feature to pass data
to the step. When you need to use this scenario, please consider
implementing a separate subroutine instead.
.IP "\(bu" 4
a reference to an array of hashes
.Sp
This scenario corresponsds with a data table argument to the step. The
names of the columns are taken from the first hash in the array (the
first row in the data table).
.Sp
No transformations are applied to the table passed in to prevent
duplicate transformations being applied.
.PP
The value of the third argument will be used as the \f(CW\*(C`C\->data\*(C'\fR value
for the \f(CW\*(C`StepContext\*(C'\fR of the child step. All values passed in, will be
passed to the child without applying \f(CW\*(C`Transform\*(C'\fR declarations. That way,
double transformation is prevented.
.PP
If the step you dispatch to doesn't pass for any reason (can't be found, dies,
fails, whatever), it'll throw an exception. This will get caught by the parent
step, which will then fail, and show debugging output.
.PP
\&\fBYou must use the English names for the step verb, because we have no access to
the parser. Also, remember to quote them as if you're in a step file, there may
be a subroutine defined with the same name.\fR
.SS "dispatch"
.IX Subsection "dispatch"
.Vb 1
\&    C\->dispatch( \*(AqThen\*(Aq, "the page has loaded successfully");
.Ve
.PP
See the paragraphs immediately above this
.SH "AUTHOR"
.IX Header "AUTHOR"
Peter Sergeant \f(CW\*(C`pete@clueball.com\*(C'\fR
.SH "LICENSE"
.IX Header "LICENSE"
.Vb 2
\&  Copyright 2019\-2023, Erik Huelsmann
\&  Copyright 2011\-2019, Peter Sergeant; Licensed under the same terms as Perl
.Ve