Writing Scenariosnew

Note

The Scenarios feature is only available to Premium and Enterprise users.

Blackfire scenarios provides a powerful way to test your application on a regular basis, like when you deploy your code on a staging environment or in production, or when you create a pull-request to add a new feature or fix a bug. The idea is to assess the performance of your code and to check its behavior.

Scenarios are run when triggered.

Once scenarios are completed, a Build Report is generated.

Scenarios

Caution

Scenarios should be written with the Blackfire Player DSL. We strongly suggest that you update your existing scenarios to the new syntax. For the deprecated scenarios syntax, please read the legacy documentation.

Like Blackfire tests, scenarios are defined in the .blackfire.yml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
scenarios: |
    #!blackfire-player

    scenario
        name 'Visitor'

        visit url('/pricing')
            name 'Pricing page'

        visit url('/docs/introduction')
            name 'Documentation'

    scenario
        name 'Authentication'

        set user_login "my_login"
        set user_password "my_password"

        visit url('/login')
            name 'Login page'

        submit button('Log in')
            name 'Submit log in form'
            param _username user_login
            param _password user_password

        follow
            name 'Login redirection'
            expect current_url() == endpoint ~ '/'
            expect body() matches '/Welcome ' ~ user_login ~ '/'

The scenarios are run by the Blackfire Player. It provides a nice DSL to crawl HTTP services, assert responses, and extract data from HTML/XML/JSON responses.

Note

Don't forget the | (pipe) at the end of the scenarios: | line to start a multiline string.

Please also note that the Player script must start with #!blackfire-player

Note

If you trigger a build with a webhook URL, please ensure it is not an outdated version.

If the URL contains /api/v1/build/, upgrade your webhook URL by generating a new one on the environment build's tab.

When a build is triggered, it generates a report and notifications are sent.

Build Report

Build reports contain the result of all assertions written in the scenarios or in the Tests section of the blackfire.yml file.

They are available from an environment's Builds section.

Build Reports have an overall status (pass or fail). The availability of a new report and its status can be sent as a notification to users with a wide variety of Notification Channels.

Builds reports have a retention policy of 13 months. Their profiles are subject to the retention policy of your plan.

Other Ways to Automate Scenarios

You can write your own HTTP scenarios by using our PHP SDK or our integration with Goutte or Guzzle.

You can also write scenarios "manually" via PHPunit for libraries or CLI commands and automatically benefit from the builds and notification channels of your continuous integration platform.