Loading...
  1. Documentation
  2. Using Builds
  3. Writing Scenarios

Writing Scenarios
Requires Production Plan

Blackfire scenarios provide a powerful way to test your application regularly, 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 within builds, periodic or externally triggered.

Once scenarios are completed, a Build Report is generated.

Like Blackfire tests, scenarios are defined in the .blackfire.yaml 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.

Validate your .blackfire.yaml file or test files ending with .bkf via the Blackfire online validator.

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

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.

You may use variables within your automated scenarios like for any Blackfire Player scenario. To inject values for these variables, define their key/value pairs in the Variables edition panel, available in your environment dashboard:

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

They are available from an environment'sBuilds 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.

You can write your HTTP scenarios by using the following integrations:

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.