Add --worker-file option in tempest

This patch add the option --worker-file on tempest run command.
This will enable users to specify a worker file that will be used
by stestr to manually schedule how the tests will run.

Change-Id: I747f3abe179492da063fcaaf1123ffcf6362f966

releasenotes/notes/add-worker-file-option-d949121a61156968.yaml

@@ -0,0 +1,10 @@
+---
+features:
+  - |
+    Add the option --worker-file in ``tempest run`` command. This is to give
+    tempest more granularity to manually configure how the different sets of
+    tests can be grouped to run with the different worker. You can configure
+    tests regex to run under workers. You can also mix manual scheduling with
+    standard one by mentioning concurrency.
+    For example, the user can setup tempest to run with different concurrences,
+    to be used with different regexps.

tempest/cmd/run.py

@@ -47,6 +47,42 @@ tests generated by the ``--list-tests`` option. You can specify target tests
 by removing unnecessary tests from a list file which is generated from
 ``--list-tests`` option.
 
+You can also use ``--worker-file`` option that let you pass a filepath to a
+worker yaml file, allowing you to manually schedule the tests run.
+For example, you can setup a tempest run with
+different concurrences to be used with different regexps.
+An example of worker file is showed below::
+
+    # YAML Worker file
+    - worker:
+      # you can have more than one regex per worker
+      - tempest.api.*
+      - neutron_tempest_tests
+    - worker:
+      - tempest.scenario.*
+
+This will run test matching with 'tempest.api.*' and 'neutron_tempest_tests'
+against worker 1. Run tests matching with 'tempest.scenario.*' under worker 2.
+
+You can mix manual scheduling with the standard scheduling mechanisms by
+concurrency field on a worker. For example::
+
+    # YAML Worker file
+    - worker:
+      # you can have more than one regex per worker
+      - tempest.api.*
+      - neutron_tempest_tests
+      concurrency: 3
+    - worker:
+      - tempest.scenario.*
+      concurrency: 2
+
+This will run tests matching with 'tempest.scenario.*' against 2 workers.
+
+This worker file is passed into stestr. For some more details on how it
+operates please refer to the stestr scheduling docs:
+https://stestr.readthedocs.io/en/stable/MANUAL.html#test-scheduling
+
 Test Execution
 ==============
 There are several options to control how the tests are executed. By default
@@ -185,6 +221,7 @@ class TempestRun(command.Command):
                 blacklist_file=parsed_args.blacklist_file,
                 whitelist_file=parsed_args.whitelist_file,
                 black_regex=parsed_args.black_regex,
+                worker_path=parsed_args.worker_file,
                 load_list=parsed_args.load_list, combine=parsed_args.combine)
             if return_code > 0:
                 sys.exit(return_code)
@@ -254,6 +291,10 @@ class TempestRun(command.Command):
                                  'on each newline. This command '
                                  'supports files created by the tempest '
                                  'run ``--list-tests`` command')
+        parser.add_argument('--worker-file', '--worker_file',
+                            help='Optional path to a worker file. This file '
+                            'contains each worker configuration to be '
+                            'used to schedule the tests run')
         # list only args
         parser.add_argument('--list-tests', '-l', action='store_true',
                             help='List tests',

tempest/tests/cmd/test_run.py

@@ -153,6 +153,15 @@ class TestRunReturnCode(base.TestCase):
             result = ["b\'" + x + "\'" for x in result]
         self.assertEqual(result, tests)
 
+    def test_tempest_run_with_worker_file(self):
+        fd, path = tempfile.mkstemp()
+        self.addCleanup(os.remove, path)
+        worker_file = os.fdopen(fd, 'wb', 0)
+        self.addCleanup(worker_file.close)
+        worker_file.write(
+            '- worker:\n  - passing\n  concurrency: 3'.encode('utf-8'))
+        self.assertRunExit(['tempest', 'run', '--worker-file=%s' % path], 0)
+
     def test_tempest_run_with_whitelist(self):
         fd, path = tempfile.mkstemp()
         self.addCleanup(os.remove, path)