Writing Scenarios (Deprecated)


This way of defining scenarios is deprecated. You should migrate your scenarios to the new format instead.


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

Blackfire Scenarios builds on Blackfire Tests. Blackfire scenarios are a list of important URLs to profile on a regular basis, like when you deploy your code on a staging environment or in production, 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.


Note that scenarios are only able to express HTTP requests, they cannot be used for CLI commands.

Scenarios are run when triggered; the result of triggering a scenario is a report accessible on blackfire.io that has a status (pass or fail) that can be notified to users.

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.


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

    Pricing page:
        - /pricing

    Integrations page:
        - /integrations

    Blackfire.yml Validator:
        - path: /docs/validator
          method: POST
          samples: 10
              accept: "application/json"

Validate .blackfire.yml files via the Blackfire online validator.

Each section defines a scenario and accept the following settings:

  • a name (e.g. "Pricing page");
  • a URL to profile or a hash made of a required path (the URL to profile) and other optional items:
    • method: The HTTP method to use;
    • samples: The number of samples (10 by default for GET and HEAD requests, 1 for other types of requests);
    • headers: An array of HTTP headers (e.g. "[ accept: "application/json" ]");
    • warmup: Whether to warmup the URL first (the default, auto is to warmup only safe HTTP requests or when the number of samples is more than one, you can set it to false or true explicitly).

Scenarios currently have the following limitations:

  • Each scenario is run independently from the other ones, so Blackfire does not keep the cookies between requests;
  • You cannot add an HTTP body to requests.

For more complex scenarios, use Goutte or Guzzle.

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

Build Report

The build report is available from the dashboard under the Builds section. Builds have a retention policy of 13 months and their profiles are subject to the retention policy of your plan.