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

Writing Scenarios
Requires Production Plan

Deprecation notice: Blackfire-hosted Synthetic Monitoring — including periodic builds, webhook-triggered builds, and native integrations — is deprecated and removed since May 30, 2026.

Migrate to Blackfire Player with --report to run Synthetic Monitoring from your own infrastructure, with full control over scheduling and secret management.

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.

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

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:

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.