# Using behave

The command-line tool behave has a bunch of command-line arguments and is also configurable using configuration files.

Values defined in the configuration files are used as defaults which the command-line arguments may override.

## Command-Line Arguments

You may see the same information presented below at any time using `behave -h`.

-c, --no-color

  Disable the use of ANSI color escapes.

--color

  Use ANSI color escapes. This is the default behaviour. This switch is used to override a configuration file setting.

-d, --dry-run

  Invokes formatters without executing the steps.

-D, --define

  Define user-specific data for the config.userdata dictionary. Example: -D foo=bar to store it in config.userdata[“foo”].

-e, --exclude

  Don’t run feature files matching regular expression PATTERN.

-i, --include

  Only run feature files matching regular expression PATTERN.

--no-junit

  Don’t output JUnit-compatible reports.

--junit

  Output JUnit-compatible reports. When junit is enabled, all stdout and stderr will be redirected and dumped to the junit report, regardless of the “–capture” and “–no-capture” options.

--junit-directory

  Directory in which to store JUnit reports.

-f, --format

  Specify a formatter. If none is specified the default formatter is used. Pass “–format help” to get a list of available formatters.

--steps-catalog

  Show a catalog of all available step definitions. SAME AS: –format=steps.catalog –dry-run –no-summary -q

-k, --no-skipped

  Don’t print skipped steps (due to tags).

--show-skipped

  Print skipped steps. This is the default behaviour. This switch is used to override a configuration file setting.

--no-snippets

  Don’t print snippets for unimplemented steps.

--snippets

  Print snippets for unimplemented steps. This is the default behaviour. This switch is used to override a configuration file setting.

-m, --no-multiline

  Don’t print multiline strings and tables under steps.

--multiline

  Print multiline strings and tables under steps. This is the default behaviour. This switch is used to override a configuration file setting.

-n, --name

  Only execute the feature elements which match part of the given name. If this option is given more than once, it will match against all the given names.

--no-capture

  Don’t capture stdout (any stdout output will be printed immediately.)

--capture

  Capture stdout (any stdout output will be printed if there is a failure.) This is the default behaviour. This switch is used to override a configuration file setting.

--no-capture-stderr

  Don’t capture stderr (any stderr output will be printed immediately.)

--capture-stderr

  Capture stderr (any stderr output will be printed if there is a failure.) This is the default behaviour. This switch is used to override a configuration file setting.

--no-logcapture

  Don’t capture logging. Logging configuration will be left intact.

--logcapture

  Capture logging. All logging during a step will be captured and displayed in the event of a failure. This is the default behaviour. This switch is used to override a configuration file setting.

--logging-level

  Specify a level to capture logging at. The default is INFO - capturing everything.

--logging-format

  Specify custom format to print statements. Uses the same format as used by standard logging handlers. The default is “%(levelname)s:%(name)s:%(message)s”.

--logging-datefmt

  Specify custom date/time format to print statements. Uses the same format as used by standard logging handlers.

--logging-filter

  Specify which statements to filter in/out. By default, everything is captured. If the output is too verbose, use this option to filter out needless output. Example: –logging-filter=foo will capture statements issued ONLY to foo or foo.what.ever.sub but not foobar or other logger. Specify multiple loggers with comma: filter=foo,bar,baz. If any logger name is prefixed with a minus, eg filter=-foo, it will be excluded rather than included.

--logging-clear-handlers

  Clear all other logging handlers.

--no-summary

  Don’t display the summary at the end of the run.

--summary

  Display the summary at the end of the run.

-o, --outfile

  Write to specified file instead of stdout.

-q, --quiet

  Alias for –no-snippets –no-source.

-s, --no-source

  Don’t print the file and line of the step definition with the steps.

--show-source

  Print the file and line of the step definition with the steps. This is the default behaviour. This switch is used to override a configuration file setting.

--stage

  Defines the current test stage. The test stage name is used as name prefix for the environment file and the steps directory (instead of default path names).

--stop

  Stop running tests at the first failure.

-t, --tags

  Only execute features or scenarios with tags matching TAG_EXPRESSION. Pass “–tags-help” for more information.

-T, --no-timings

  Don’t print the time taken for each step.

--show-timings

  Print the time taken, in seconds, of each step after the step has completed. This is the default behaviour. This switch is used to override a configuration file setting.

-v, --verbose

  Show the files and features loaded.

-w, --wip

  Only run scenarios tagged with “wip”. Additionally: use the “plain” formatter, do not capture stdout or logging output and stop at the first failure.

-x, --expand

  Expand scenario outline tables in output.

--lang

  Use keywords for a language other than English.

--lang-list

  List the languages available for –lang.

--lang-help

  List the translations accepted for one language.

--tags-help

  Show help for tag expressions.

--version

  Show version.

### Tag Expression

Scenarios inherit tags declared on the Feature level. The simplest TAG_EXPRESSION is simply a tag:

    --tags @dev

You may even leave off the “@” - behave doesn’t mind.

When a tag in a tag expression starts with a ~, this represents boolean NOT:

    --tags ~@dev

A tag expression can have several tags separated by a comma, which represents logical OR:

    --tags @dev,@wip

The –tags option can be specified several times, and this represents logical AND, for instance this represents the boolean expression “(@foo or not @bar) and @zap”:

    --tags @foo,~@bar --tags @zap.

Beware that if you want to use several negative tags to exclude several tags you have to use logical AND:

    --tags ~@fixme --tags ~@buggy.

## Configuration Files

Configuration files for behave are called either “.behaverc”, “behave.ini”, “setup.cfg” or “tox.ini” (your preference) and are located in one of three places:

1. the current working directory (good for per-project settings),

2. your home directory ($HOME), or

3. on Windows, in the %APPDATA% directory.

If you are wondering where behave is getting its configuration defaults from you can use the “-v” command-line argument and it’ll tell you.

Configuration files must start with the label “[behave]” and are formatted in the Windows INI style, for example:

    [behave]
    format=plain
    logging_clear_handlers=yes
    logging_filter=-suds

### Configuration Parameter Types

The following types are supported (and used):

text

  This just assigns whatever text you supply to the configuration setting.

bool

  This assigns a boolean value to the configuration setting. The text describes the functionality when the value is true. True values are “1”, “yes”, “true”, and “on”. False values are “0”, “no”, “false”, and “off”.

sequence<text>

  These fields accept one or more values on new lines, for example a tag expression might look like:

      tags=@foo,~@bar
          @zap

  which is the equivalent of the command-line usage:

      --tags @foo,~@bar --tags @zap

### Configuration Parameters

color : bool

  Use ANSI color escapes. This is the default behaviour. This switch is used to override a configuration file setting.

dry_run : bool

  Invokes formatters without executing the steps.

userdata_defines : sequence<text>

  Define user-specific data for the config.userdata dictionary. Example: -D foo=bar to store it in config.userdata[“foo”].

exclude_re : text

  Don’t run feature files matching regular expression PATTERN.

include_re : text

  Only run feature files matching regular expression PATTERN.

junit : bool

  Output JUnit-compatible reports. When junit is enabled, all stdout and stderr will be redirected and dumped to the junit report, regardless of the “–capture” and “–no-capture” options.

junit_directory : text

  Directory in which to store JUnit reports.

default_format : text

  Specify default formatter (default: pretty).

format : sequence<text>

  Specify a formatter. If none is specified the default formatter is used. Pass “–format help” to get a list of available formatters.

steps_catalog : bool

  Show a catalog of all available step definitions. SAME AS: –format=steps.catalog –dry-run –no-summary -q

scenario_outline_annotation_schema : text

  Specify name annotation schema for scenario outline (default=”{name} – @{row.id} {examples.name}”).

show_skipped : bool

  Print skipped steps. This is the default behaviour. This switch is used to override a configuration file setting.

show_snippets : bool

  Print snippets for unimplemented steps. This is the default behaviour. This switch is used to override a configuration file setting.

show_multiline : bool

  Print multiline strings and tables under steps. This is the default behaviour. This switch is used to override a configuration file setting.

name : sequence<text>

  Only execute the feature elements which match part of the given name. If this option is given more than once, it will match against all the given names.

stdout_capture : bool

  Capture stdout (any stdout output will be printed if there is a failure.) This is the default behaviour. This switch is used to override a configuration file setting.

stderr_capture : bool

  Capture stderr (any stderr output will be printed if there is a failure.) This is the default behaviour. This switch is used to override a configuration file setting.

log_capture : bool

  Capture logging. All logging during a step will be captured and displayed in the event of a failure. This is the default behaviour. This switch is used to override a configuration file setting.

logging_level : text

  Specify a level to capture logging at. The default is INFO - capturing everything.

logging_format : text

  Specify custom format to print statements. Uses the same format as used by standard logging handlers. The default is “%(levelname)s:%(name)s:%(message)s”.

logging_datefmt : text

  Specify custom date/time format to print statements. Uses the same format as used by standard logging handlers.

logging_filter : text

  Specify which statements to filter in/out. By default, everything is captured. If the output is too verbose, use this option to filter out needless output. Example: `logging_filter = foo` will capture statements issued ONLY to “foo” or “foo.what.ever.sub” but not “foobar” or other logger. Specify multiple loggers with comma: `logging_filter = foo,bar,baz`. If any logger name is prefixed with a minus, eg `logging_filter = -foo`, it will be excluded rather than included.

logging_clear_handlers : bool

  Clear all other logging handlers.

summary : bool

  Display the summary at the end of the run.

outfiles : sequence<text>

  Write to specified file instead of stdout.

paths : sequence<text>

  Specify default feature paths, used when none are provided.

quiet : bool

  Alias for –no-snippets –no-source.

show_source : bool

  Print the file and line of the step definition with the steps. This is the default behaviour. This switch is used to override a configuration file setting.

stage : text

  Defines the current test stage. The test stage name is used as name prefix for the environment file and the steps directory (instead of default path names).

stop : bool

  Stop running tests at the first failure.

default_tags : text

  Define default tags when non are provided. See –tags for more information.

tags : sequence<text>

  Only execute certain features or scenarios based on the tag expression given. See below for how to code tag expressions in configuration files.

show_timings : bool

  Print the time taken, in seconds, of each step after the step has completed. This is the default behaviour. This switch is used to override a configuration file setting.

verbose : bool

  Show the files and features loaded.

wip : bool

  Only run scenarios tagged with “wip”. Additionally: use the “plain” formatter, do not capture stdout or logging output and stop at the first failure.

expand : bool

  Expand scenario outline tables in output.

lang : text

  Use keywords for a language other than English.