Fork us

Configuration - behat.yml

Sometimes, Behat’s default configuration is not enough. Some day you’ll need some extended tools to configure your feature suite. For that day, Behat has a very powerful configuration system based on YAML configuration files and profiles.


All configuration happens inside a single configuration file in the YAML format. Behat tries to load behat.yml or config/behat.yml by default, or you can tell Behat where your config file is with the --config option:

$ behat --config custom-config.yml

All configuration parameters in that file are defined under a profile name root (default: for example). A profile is just a custom name you can use to quickly switch testing configuration by using the --profile option when executing your feature suite.

The default profile is always default. All other profiles inherit parameters from the default profile. If you only need one profile, define all of your parameters under the default: root:

# behat.yml


The first configuration block is paths. Parameters under this configuration block tell Behat where to find your feature and bootstrap files:

# behat.yml
        features: features
        bootstrap: %behat.paths.features%/bootstrap
  • The features parameter defines where Behat will look for your *.feature files. The given directory will be scanned recursivly.
  • The bootstrap parameter defines the directory from which Behat will automatically load all *.php files.


Notice the %behat.paths.features% placeholder. These strings are predefined configuration variables, that you can use to build very flexible configurations.

A variable is a placeholder that consists of lower-case letters and starts/ends with a single %. These variables are your current configuration parameters, which you can use to nest configurations. Usable variables are:

  1. %behat.paths.base% - current working dir or configuration path (if configuration file exists and loaded).
  2. %behat.paths.features% - features path.
  3. %behat.paths.bootstrap% - bootstrap path.


Another very useful configuration block is the filters block. This block defines default filters (name or tag) for your features. If you find yourself typing the same filters again and again from run to run, it would be more efficient for you to define them as parameters:

# behat.yml
        tags: "@wip"

These filter parameters (name and tags) accept the same strings as the Behat --name or --tags parameters do.


If you need to customize your output formatter, the formatter block is right for you:

# behat.yml
        name:                       pretty
            decorated:              true
            verbose:                false
            time:                   true
            language:               en
            output_path:            null
            multiline_arguments:    true
  • name defines the default output formatter name to use for your features. You could write a class name here so Behat will use your custom class as the default output formatter, but be careful - this class should be accessible by Behat and implement Behat\Behat\Formatter\FormatterInterface.
  • The parameters section defines additional parameters which will be provided into the formatter instance. As you can see, all parameters from this section duplicate behat tool options. You can redefine behat formatter defaults here. Also, this is the place to specify parameters for your custom formatters.

The YAML configuration file supports the same formatter parameters as the behat tool, so you can give multiple options for e.g. different formatters. This is useful when run in a continuous integration (CI) environment, so you get machine-readable output for JUnit as well as human-readable text in one single run.

An example that generates multiple output formats could look like this:

# behat.yml
    name:                   pretty,junit,html
      output_path:          null,junit,behat_report.html

This will write pretty text output to the console, one XML file per feature to the junit directory and an HTML report to the file behat_report.html. See each formatter’s documentation for details on what parameters are available, optional or mandatory.


New in version 2.2.

As of version 2.2, you can configure Behat formatters to use specific output styles (colors).

        name:               pretty
                comment: [ black, white, [ underscore ] ]

this will force Behat to print comments (key of the style) with black foreground (first parameter), white background (second parameter) and as underscore (list of options - third parameter).

Styles available for redefinition:

  • undefined - style of undefined step
  • pending - style of pending step
  • pending_param - style of param in pending step
  • failed - style of failed step
  • failed_param - style of param in failed step
  • passed - style of passed step
  • passed_param - style of param in passed step
  • skipped - style of skipped step
  • skipped_param - style of param in skipped step
  • comment - style of comment
  • tag - style of scenario/feature tag

Available colors for first two arguments (fg and bg) are: black, red, green, yellow, blue, magenta, cyan, white

Available options are: bold, underscore, blink, reverse, conceal


Sometimes you may want to use a different default context class or provide useful parameters for the context constructor from your behat.yml. Use the context block to set these options:

# behat.yml
        class:          Your\Custom\Context
            base_url:   http://test.mink.loc
  • class defines which class you want to use as the environment. This class should be accessible by Behat and implement Behat\Behat\Context\ContextInterface.
  • parameters parameters is a simple array that will be passed into the constructor of your context class when instantiated, which happens before each scenario.


Profiles help you define different configurations for running your feature suite. Let’s say we need 2 different configurations that share common options, but use different formatters. Our behat.yml might look like this:

# behat.yml
        class:      Your\Custom\Context
        tags:       "@wip"
        name:       progress
        name:       junit
            output_path: /var/tmp/junit

This file defines 2 additional profiles (additional to default). Every profile will use Your\Custom\Context as its environment object, but the wip profile will run only scenarios with the @wip (work in progress) tag and will output them with the progress formatter. The ci profile will run all features and output them with the junit formatter to the /var/tmp/junit path.

To run each of these custom profiles, use the --profile option:

behat --profile wip
behat --profile ci


The extensions block allows you to activate extensions for your suite or for specific profile of the suite:

# behat.yml
    Behat\Symfony2Extension\Extension: ~



In the example above, we activate 2 extensions depending on profile. mink profile will have activate MinkExtension and api profile will have WebApiExtension, but both of them will also have Symfony2Extension activated as any profile always inherit from default profile.

Extensions help you integrate Behat with frameworks and tools, that you might need to ease your test suite building.


The imports block allows you to share your feature suite configuration between projects and their test suites:

# behat.yml
    - some_installed_pear_package_or_lib/behat.yml
    - /full/path/to/custom_behat_config.yml

All files from the imports block will be loaded by Behat and merged into your behat.yml config.

Environment Variable

New in version 2.2.5.

If you want to configure some system-wide Behat defaults, then BEHAT_PARAMS environment variable is right for you:

export BEHAT_PARAMS="formatter[name]=progress&context[parameters][base_url]=http://localhost"

You could setup default value for any option, that available for you in behat.yml. Just provide options in url format (parseable by parse_str() php function). Behat will use those options as default ones and you will always be able to redefine them with project behat.yml (it has higher priority).