busser-behave 0.1.3

data/vendor/behave/docs/appendix.rst

@@ -0,0 +1,19 @@
+.. _id.appendix:
+
+==============================================================================
+Appendix
+==============================================================================
+
+**Contents:**
+
+.. toctree::
+    :maxdepth: 1
+
+    formatters
+    context_attributes
+    parse_builtin_types
+    regular_expressions
+    test_domains
+    behave_ecosystem
+    related
+

data/vendor/behave/docs/behave.rst

@@ -0,0 +1,640 @@
+==============
+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``.
+
+.. option:: -c, --no-color
+
+    Disable the use of ANSI color escapes.
+
+.. option:: --color
+
+    Use ANSI color escapes. This is the default behaviour. This switch is
+    used to override a configuration file setting.
+
+.. option:: -d, --dry-run
+
+    Invokes formatters without executing the steps.
+
+.. option:: -D, --define
+
+    Define user-specific data for the config.userdata dictionary. Example:
+    -D foo=bar to store it in config.userdata["foo"].
+
+.. option:: -e, --exclude
+
+    Don't run feature files matching regular expression PATTERN.
+
+.. option:: -i, --include
+
+    Only run feature files matching regular expression PATTERN.
+
+.. option:: --no-junit
+
+    Don't output JUnit-compatible reports.
+
+.. option:: --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.
+
+.. option:: --junit-directory
+
+    Directory in which to store JUnit reports.
+
+.. option:: -f, --format
+
+    Specify a formatter. If none is specified the default formatter is
+    used. Pass "--format help" to get a list of available formatters.
+
+.. option:: --steps-catalog
+
+    Show a catalog of all available step definitions. SAME AS:
+    --format=steps.catalog --dry-run --no-summary -q
+
+.. option:: -k, --no-skipped
+
+    Don't print skipped steps (due to tags).
+
+.. option:: --show-skipped
+
+    Print skipped steps. This is the default behaviour. This switch is
+    used to override a configuration file setting.
+
+.. option:: --no-snippets
+
+    Don't print snippets for unimplemented steps.
+
+.. option:: --snippets
+
+    Print snippets for unimplemented steps. This is the default behaviour.
+    This switch is used to override a configuration file setting.
+
+.. option:: -m, --no-multiline
+
+    Don't print multiline strings and tables under steps.
+
+.. option:: --multiline
+
+    Print multiline strings and tables under steps. This is the default
+    behaviour. This switch is used to override a configuration file
+    setting.
+
+.. option:: -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.
+
+.. option:: --no-capture
+
+    Don't capture stdout (any stdout output will be printed immediately.)
+
+.. option:: --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.
+
+.. option:: --no-capture-stderr
+
+    Don't capture stderr (any stderr output will be printed immediately.)
+
+.. option:: --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.
+
+.. option:: --no-logcapture
+
+    Don't capture logging. Logging configuration will be left intact.
+
+.. option:: --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.
+
+.. option:: --logging-level
+
+    Specify a level to capture logging at. The default is INFO - capturing
+    everything.
+
+.. option:: --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".
+
+.. option:: --logging-datefmt
+
+    Specify custom date/time format to print statements. Uses the same
+    format as used by standard logging handlers.
+
+.. option:: --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.
+
+.. option:: --logging-clear-handlers
+
+    Clear all other logging handlers.
+
+.. option:: --no-summary
+
+    Don't display the summary at the end of the run.
+
+.. option:: --summary
+
+    Display the summary at the end of the run.
+
+.. option:: -o, --outfile
+
+    Write to specified file instead of stdout.
+
+.. option:: -q, --quiet
+
+    Alias for --no-snippets --no-source.
+
+.. option:: -s, --no-source
+
+    Don't print the file and line of the step definition with the steps.
+
+.. option:: --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.
+
+.. option:: --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).
+
+.. option:: --stop
+
+    Stop running tests at the first failure.
+
+.. option:: -t, --tags
+
+    Only execute features or scenarios with tags matching TAG_EXPRESSION.
+    Pass "--tags-help" for more information.
+
+.. option:: -T, --no-timings
+
+    Don't print the time taken for each step.
+
+.. option:: --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.
+
+.. option:: -v, --verbose
+
+    Show the files and features loaded.
+
+.. option:: -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.
+
+.. option:: -x, --expand
+
+    Expand scenario outline tables in output.
+
+.. option:: --lang
+
+    Use keywords for a language other than English.
+
+.. option:: --lang-list
+
+    List the languages available for --lang.
+
+.. option:: --lang-help
+
+    List the translations accepted for one language.
+
+.. option:: --tags-help
+
+    Show help for tag expressions.
+
+.. option:: --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:
+
+.. 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
+-----------------------------
+
+.. index::
+    single: configuration param; color
+
+.. describe:: color : bool
+
+    Use ANSI color escapes. This is the default behaviour. This switch is
+    used to override a configuration file setting.
+
+.. index::
+    single: configuration param; dry_run
+
+.. describe:: dry_run : bool
+
+    Invokes formatters without executing the steps.
+
+.. index::
+    single: configuration param; userdata_defines
+
+.. describe:: userdata_defines : sequence<text>
+
+    Define user-specific data for the config.userdata dictionary. Example:
+    -D foo=bar to store it in config.userdata["foo"].
+
+.. index::
+    single: configuration param; exclude_re
+
+.. describe:: exclude_re : text
+
+    Don't run feature files matching regular expression PATTERN.
+
+.. index::
+    single: configuration param; include_re
+
+.. describe:: include_re : text
+
+    Only run feature files matching regular expression PATTERN.
+
+.. index::
+    single: configuration param; junit
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; junit_directory
+
+.. describe:: junit_directory : text
+
+    Directory in which to store JUnit reports.
+
+.. index::
+    single: configuration param; default_format
+
+.. describe:: default_format : text
+
+    Specify default formatter (default: pretty).
+
+.. index::
+    single: configuration param; format
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; steps_catalog
+
+.. describe:: steps_catalog : bool
+
+    Show a catalog of all available step definitions. SAME AS:
+    --format=steps.catalog --dry-run --no-summary -q
+
+.. index::
+    single: configuration param; scenario_outline_annotation_schema
+
+.. describe:: scenario_outline_annotation_schema : text
+
+    Specify name annotation schema for scenario outline (default="{name}
+    -- @{row.id} {examples.name}").
+
+.. index::
+    single: configuration param; show_skipped
+
+.. describe:: show_skipped : bool
+
+    Print skipped steps. This is the default behaviour. This switch is
+    used to override a configuration file setting.
+
+.. index::
+    single: configuration param; show_snippets
+
+.. describe:: show_snippets : bool
+
+    Print snippets for unimplemented steps. This is the default behaviour.
+    This switch is used to override a configuration file setting.
+
+.. index::
+    single: configuration param; show_multiline
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; name
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; stdout_capture
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; stderr_capture
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; log_capture
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; logging_level
+
+.. describe:: logging_level : text
+
+    Specify a level to capture logging at. The default is INFO - capturing
+    everything.
+
+.. index::
+    single: configuration param; logging_format
+
+.. describe:: 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".
+
+.. index::
+    single: configuration param; logging_datefmt
+
+.. describe:: logging_datefmt : text
+
+    Specify custom date/time format to print statements. Uses the same
+    format as used by standard logging handlers.
+
+.. index::
+    single: configuration param; logging_filter
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; logging_clear_handlers
+
+.. describe:: logging_clear_handlers : bool
+
+    Clear all other logging handlers.
+
+.. index::
+    single: configuration param; summary
+
+.. describe:: summary : bool
+
+    Display the summary at the end of the run.
+
+.. index::
+    single: configuration param; outfiles
+
+.. describe:: outfiles : sequence<text>
+
+    Write to specified file instead of stdout.
+
+.. index::
+    single: configuration param; paths
+
+.. describe:: paths : sequence<text>
+
+    Specify default feature paths, used when none are provided.
+
+.. index::
+    single: configuration param; quiet
+
+.. describe:: quiet : bool
+
+    Alias for --no-snippets --no-source.
+
+.. index::
+    single: configuration param; show_source
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; stage
+
+.. describe:: 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).
+
+.. index::
+    single: configuration param; stop
+
+.. describe:: stop : bool
+
+    Stop running tests at the first failure.
+
+.. index::
+    single: configuration param; default_tags
+
+.. describe:: default_tags : text
+
+    Define default tags when non are provided. See --tags for more
+    information.
+
+.. index::
+    single: configuration param; tags
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; show_timings
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; verbose
+
+.. describe:: verbose : bool
+
+    Show the files and features loaded.
+
+.. index::
+    single: configuration param; wip
+
+.. describe:: 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.
+
+.. index::
+    single: configuration param; expand
+
+.. describe:: expand : bool
+
+    Expand scenario outline tables in output.
+
+.. index::
+    single: configuration param; lang
+
+.. describe:: lang : text
+
+    Use keywords for a language other than English.
+
+
+