Defining Reusable Actions¶

Creating Your First Step Definition¶

The main goal for a step definition is to be executed when Behat sees its matching step in executed scenario. However, just because a method exists within FeatureContext doesn’t mean Behat can find it. Behat needs a way to check that a concrete class method is suitable for a concrete step in a scenario. Behat matches FeatureContext methods to step definitions using pattern matching.

When Behat runs, it compares lines of Gherkin steps from each scenario to the patterns bound to each method in your FeatureContext. If the line of Gherkin satisfies a bound pattern, its corresponding step definition is executed. It’s that simple!

Behat uses PHP attributes to bind patterns to FeatureContext methods:

#[When('I do something with :methodArgument')]
public function someMethod($methodArgument) {}

Let’s take a closer look at this code:

1. When is a definition keyword. There are 3 supported keywords implemented as attributes: Given/When/Then. These three definition keywords are actually equivalent, but all three are available so that your step definition remains readable.

2. The argument to the attribute is the step text pattern (e.g. I do something with :methodArgument).

3. All token values of the pattern (e.g. :methodArgument) will be captured and passed to the method argument with the same name ($methodArgument).

As you have probably noticed, this pattern is quite general and its corresponding method will be called for steps that contain ... I do something with ..., including:

Given I do something with "string1"
When I do something with 'some other string'
Then I do something with 25

The only real difference between those steps in the eyes of Behat is the captured token text. This text will be passed to the step’s corresponding method as an argument value. In the example above, FeatureContext::someMethod() will be called three times, each time with a different argument:

1. $context->someMethod($methodArgument = 'string1');.

2. $context->someMethod($methodArgument = 'some other string');.

3. $context->someMethod($methodArgument = '25');.

Your step definitions can also define multiple arguments to pass to its matching FeatureContext method:

#[When('I do something with :stringArgument and with :numberArgument')]
public function someMethod($stringArgument, $numberArgument) {}

You can also specify alternative words and optional parts of words, like this:

#[When('there is/are :count monster(s)')]
public function thereAreMonsters($count) {}

If you need to come up with a much more complicated matching algorithm, you can always use good old regular expressions:

#[When('/^there (?:is|are) (\d+) monsters?$/i')]
public function thereAreMonsters($count) {}

And if you want to be able to say things in different ways that are not so easily written as a single regular expression, you can add multiple attributes for the one method:

#[When('/^I create (\d+) monsters$/i')]
#[Given('/^(\d+) monster(?:s|) (?:have|has) been created$/i')]
public function thereAreMonsters($count) {}

Behat will call the corresponding method if any of the patterns matches.

Definition Snippets¶

You now know how to write step definitions by hand, but writing all these method stubs, attributes and patterns by hand is tedious. Behat makes this routine task much easier and fun by generating definition snippets for you! Let’s pretend that you have this feature:

Feature:
Scenario:
 Given some step with "string" argument
And number step with 23

If your context class implements Behat\Behat\Context\SnippetAcceptingContext interface and you test a feature with missing steps in Behat:

$vendor/bin/behatfeatures/example.feature

Behat will provide auto-generated snippets for your context class.

It not only generates the proper definition attribute type (Given), but also a proper pattern with tokens capturing (:arg1, :arg2), method name (someStepWithArgument(), numberStepWith()) and arguments ( $arg1, $arg2), all based just on the text of the step. Isn’t that cool?

The only thing left for you to do is to copy these method snippets into your FeatureContext class and provide a useful body for them. Or even better, run behat with --append-snippets option:

$vendor/bin/behatfeatures/example.feature--dry-run--append-snippets

--append-snippets tells Behat to automatically add snippets inside your context class.

public static function getAcceptedSnippetType()
{
 return 'regex';
}

Step Execution Result Types¶

Now you know how to map actual code to PHP code that will be executed. But how can you tell what exactly "failed" or "passed" when executing a step? And how does Behat actually check that a step executed properly?

For that, we have step execution types. Behat differentiates between seven types of step execution results: "Successful Steps", "Undefined Steps", "Pending Steps", "Failed Steps", "Skipped Steps", "Ambiguous Steps" and "Redundant Step Definitions".

Let’s use our previously introduced feature for all the following examples:

# features/example.feature
Feature:
Scenario:
 Given some step with "string" argument
And number step with 23

// features/bootstrap/FeatureContext.php
use Behat\Behat\Context\Context;
use Behat\Step\Given;
class FeatureContext implements Context
{
 #[Given('some step with :argument1 argument')]
 public function someStepWithArgument($argument1)
 {
 }
 #[Given('number step with :argument1')]
 public function numberStepWith($argument1)
 {
 }
}

// features/bootstrap/FeatureContext.php
use Behat\Behat\Context\Context;
class FeatureContext implements Context
{
}

// features/bootstrap/FeatureContext.php
use Behat\Behat\Context\Context;
use Behat\Behat\Tester\Exception\PendingException;
use Behat\Step\Given;
class FeatureContext implements Context
{
 #[Given('some step with :argument1 argument')]
 public function someStepWithArgument($argument1)
 {
 throw new PendingException('Do some string work');
 }
 #[Given('number step with :argument1')]
 public function numberStepWith($argument1)
 {
 throw new PendingException('Do some number work');
 }
}

// features/bootstrap/FeatureContext.php
use Behat\Behat\Context\Context;
use Behat\Step\Given;
class FeatureContext implements Context
{
 #[Given('some step with :argument1 argument')]
 public function someStepWithArgument($argument1)
 {
 throw new Exception('some exception');
 }
 #[Given(number step with :argument1')]
 public function numberStepWith($argument1)
 {
 }
}

$phpcomposer.pharrequire--devphpunit/phpunit

PHPUnit_Framework_Assert::assertCount(intval($count), $this->basket);

$vendor/bin/behatfeatures/example.feature-vv

// features/bootstrap/FeatureContext.php
use Behat\Behat\Context\Context;
use Behat\Step\Given;
class FeatureContext implements Context
{
 #[Given('/^.* step with .*$/')]
 public function someStepWithArgument()
 {
 }
 #[Given('/^number step with (\d+)$/')]
 public function numberStepWith($argument1)
 {
 }
}

// features/bootstrap/FeatureContext.php
use Behat\Behat\Context\Context;
use Behat\Step\Given;
class FeatureContext implements Context
{
 #[Given('/^number step with (\d+)$/')]
 public function workWithNumber($number1)
 {
 }
 #[Given('/^number step with (\d+)$/')]
 public function workDifferentlyWithNumber($number1)
 {
 }
}