Behat Requires Premium/Enterprise

Trigger Blackfire Builds with Behat

Behat is a popular and open-source Behavior-Driven-Development (aka BDD) framework for PHP.

It makes it possible to write tests using a structured natural language. For testing applications in a web context, it uses another component, Mink, which role is to manage browser sessions using drivers.

If you already implemented such tests, you may want to re-use them for your performance tests using Blackfire Builds, and avoid writing your test scenarios twice.

Using the Blackfire SDK, you can leverage these tests to create Blackfire Builds, directly from your CI system.

Requirements

  • PHP >= 7.2
  • Behat 3
  • friends-of-behat/mink-extension >= 2.0
  • friends-of-behat/mink-browserkit-driver >= 1.5

Note

Note that the original behat/mink-extension and minkphp/mink-browserkit-driver will not work with the Blackfire extension.

Installation

Add Blackfire PHP SDK as a dependency in your project (1.25+ version), together with the Mink extension and the BrowserKit driver:

1
composer require blackfire/php-sdk friends-of-behat/mink-extension friends-of-behat/mink-browserkit-driver

Usage

Edit your Behat configuration file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# behat.yaml.dist
default:
    extensions:
        # Declare and configure the BlackfireExtension
        Blackfire\Bridge\Behat\BlackfireExtension:
            # UUID or name of your Blackfire environment
            blackfire_environment: 'My Blackfire environment'
            # The name you want to give to your Blackfire Builds triggered by Behat
            build_name: 'BDD test with Behat'
        Behat\MinkExtension:
            base_url: 'https://localhost:8000'
            sessions:
                default:
                    # Declare the Blackfire Mink driver
                    blackfire: ~

    suites:
        'Main Suite':
            contexts:
                - FeatureContext
                - Behat\MinkExtension\Context\MinkContext

Now, every time you launch the behat command, Mink is going to use the Blackfire driver. Every step in your Behat scenario is going to be profiled unless you tell it otherwise from a feature context.

A Blackfire Build is created for each defined Behat Suite. As such, every scenario defined in a suite is considered part of the corresponding Blackfire Build.

By default, every HTTP requests sent by the blackfire Mink driver are profiled.

However, you can control this behavior with the disableProfiling() and enableProfiling() functions from the BlackfireContextTrait:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
use Behat\MinkExtension\Context\RawMinkContext;
use Blackfire\Bridge\Behat\Context\BlackfireContextTrait;

class SomeContext extends RawMinkContext
{
    use BlackfireContextTrait;

    /**
     * @Given I am on ":landingPage" landing page
     * @When I go to ":landingPage" landing page
     */
    public function iAmOnLandingPage($landingPage)
    {
        $this->disableProfiling();
        $this->visitPath("/$landingPage");

        // You may re-enable profiling and visit other pages
        $this->enableProfiling();
        $this->visitPath('/foo/bar');
    }
}

Builds Comparison

To compare the current build to another one, you may set BLACKFIRE_EXTERNAL_ID and BLACKFIRE_EXTERNAL_PARENT_ID environment variables when launching your tests:

1
2
3
BLACKFIRE_EXTERNAL_ID=current_build_reference \
BLACKFIRE_EXTERNAL_PARENT_ID=parent_build_reference \
vendor/bin/behat

Note

You may use Git commit identifiers as references.

Disable the Blackfire Builds Globally

You may want to run Blackfire tests in a separate job in your pipeline, while still running your functional tests.

In this case, it is possible to globally disable the Blackfire build by setting the BLACKFIRE_BUILD_DISABLED environment variable to 1:

1
BLACKFIRE_BUILD_DISABLED=1 vendor/bin/behat