CLI: Add --jobs/--parallel option

* RESERVED FOR: Future use
* Only supported by test runners that support parallel execution

behave/configuration.py

@@ -69,6 +69,14 @@ def to_string(level):
         return logging.getLevelName(level)
 
 
+def positive_number(text):
+    """Converts a string into a positive integer number."""
+    value = int(text)
+    if value < 0:
+        raise ValueError("POSITIVE NUMBER, but was: %s" % text)
+    return value
+
+
 # -----------------------------------------------------------------------------
 # CONFIGURATION SCHEMA:
 # -----------------------------------------------------------------------------
@@ -120,9 +128,14 @@ def to_string(level):
           default="reports",
           help="""Directory in which to store JUnit reports.""")),
 
+    (("-j", "--jobs", "--parallel"),
+     dict(metavar="NUMBER", dest="jobs", default=1, type=positive_number,
+          help="""Number of concurrent jobs to use (default: %(default)s).
+                  Only supported by test runners that support parallel execution.""")),
+
     ((),  # -- CONFIGFILE only
-     dict(dest="default_format",
-          help="Specify default formatter (default: pretty).")),
+     dict(dest="default_format", default="pretty",
+          help="Specify default formatter (default: %(default)s).")),
 
 
     (("-f", "--format"),
@@ -500,6 +513,7 @@ class Configuration(object):
     # pylint: disable=too-many-instance-attributes
     defaults = dict(
         color='never' if sys.platform == "win32" else os.getenv('BEHAVE_COLOR', 'auto'),
+        jobs=1,
         show_snippets=True,
         show_skipped=True,
         dry_run=False,

docs/behave.rst

@@ -55,6 +55,11 @@ You may see the same information presented below at any time using ``behave
 
     Directory in which to store JUnit reports.
 
+.. option:: -j, --jobs, --parallel
+
+    Number of concurrent jobs to use (default: 1). Only supported by test
+    runners that support parallel execution.
+
 .. option:: -f, --format
 
     Specify a formatter. If none is specified the default formatter is
@@ -388,6 +393,14 @@ Configuration Parameters
 
     Directory in which to store JUnit reports.
 
+.. index::
+    single: configuration param; jobs
+
+.. describe:: jobs : positive_number
+
+    Number of concurrent jobs to use (default: 1). Only supported by test
+    runners that support parallel execution.
+
 .. index::
     single: configuration param; default_format
 

docs/update_behave_rst.py

@@ -17,6 +17,8 @@
 from behave import configuration
 from behave.__main__ import TAG_HELP
 
+
+positive_number = configuration.positive_number
 cmdline = []
 config = []
 indent = "    "
@@ -51,9 +53,31 @@
                 assert len(opt) == 2
                 dest = opt[1:]
 
+    # -- COMMON PART:
+    action = keywords.get("action", "store")
+    data_type = keywords.get("type", None)
+    default_value = keywords.get("default", None)
+    if action == "store":
+        type = "text"
+        if data_type is positive_number:
+            type = "positive_number"
+        if data_type is int:
+            type = "number"
+    elif action in ("store_true","store_false"):
+        type = "bool"
+        default_value = False
+        if action == "store_true":
+            default_value = True
+    elif action == "append":
+        type = "sequence<text>"
+    else:
+        raise ValueError("unknown action %s" % action)
+
     # -- CASE: command-line option
     text = re.sub(r"\s+", " ", keywords["help"]).strip()
     text = text.replace("%%", "%")
+    if default_value and "%(default)s" in text:
+        text = text.replace("%(default)s", str(default_value))
     text = textwrap.fill(text, 70, initial_indent="", subsequent_indent=indent)
     if fixed:
         # -- COMMAND-LINE OPTIONS (CONFIGFILE only have empty fixed):
@@ -66,22 +90,14 @@
         continue
 
     # -- CASE: configuration-file parameter
-    action = keywords.get("action", "store")
-    if action == "store":
-        type = "text"
-    elif action in ("store_true","store_false"):
-        type = "bool"
-    elif action == "append":
-        type = "sequence<text>"
-    else:
-        raise ValueError("unknown action %s" % action)
-
     if action == "store_false":
         # -- AVOID: Duplicated descriptions, use only case:true.
         continue
 
     text = re.sub(r"\s+", " ", keywords.get("config_help", keywords["help"])).strip()
     text = text.replace("%%", "%")
+    if default_value and "%(default)s" in text:
+        text = text.replace("%(default)s", str(default_value))
     text = textwrap.fill(text, 70, initial_indent="", subsequent_indent=indent)
     config.append(config_param_schema.format(param=dest, type=type, text=text))