==============
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``.

{cmdline}


Tag Expression
--------------

{tag_expression}


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:

.. code-block:: ini

    [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:

    .. code-block:: ini

        tags=@foo,~@bar
            @zap

    which is the equivalent of the command-line usage::

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



Configuration Parameters
-----------------------------

{config}


