--config command line argument

docs/configuration.rst

@@ -27,3 +27,33 @@ Most of the configuration that can be set through command line arguments can als
 environment variables. Here's a table of all the available environment variables:
 
 .. include:: env-options.rst
+
+
+
+.. _configuration-files:
+
+Configuration files
+-------------------
+
+Any of the configuration that can be set through command line arguments can also be set by a
+configuration file in the `config file <https://github.com/bw2/ConfigArgParse#config-file-syntax>`_
+format.
+Locust will look for ``locust.conf`` or ``~/.locust.conf`` by default, or a file may be specified
+with the ``--config`` flag. Parameters passed as command line arguments will override the settings
+from the config file.
+
+
+.. code-block::
+
+    # step_mode.conf in current directory
+    locustfile locust_files/my_locust_file.py
+    host localhost
+    users 100
+    hatch-rate 10
+    step-load
+    step-users 20
+    step-time 60
+
+.. code-block:: console
+
+    $ locust --config=step_mode.conf

docs/quickstart.rst

@@ -144,8 +144,10 @@ host defaults to 127.0.0.1):
     $ locust -f locust_files/my_locust_file.py --worker --master-host=192.168.0.100
 
 
-Parameters can also be set as :ref:`environment variables <environment-variables>`, or in a 
-`config file <https://github.com/bw2/ConfigArgParse#config-file-syntax>`_ (``locust.conf`` or ``~/.locust.conf``).
+Parameters can also be set as :ref:`environment variables <environment-variables>`, or in a
+`config file <https://github.com/bw2/ConfigArgParse#config-file-syntax>`_.
+Locust will look for ``locust.conf`` or ``~/.locust.conf`` by default, or a file may be specified
+with the ``--config`` flag.
 
 For example: (this will do the same thing as the previous command)
 

locust/argument_parser.py

@@ -76,6 +76,8 @@ def get_empty_argument_parser(add_help=True, default_config_files=DEFAULT_CONFIG
         help="Python module file to import, e.g. '../other.py'. Default: locustfile",
         env_var="LOCUST_LOCUSTFILE",
     )
+    parser.add_argument('--config', is_config_file_arg=True, help='Config file path')
+
     return parser
 
 

locust/test/test_main.py

@@ -77,6 +77,40 @@ def test_create_environment(self):
         self.assertEqual(None, env.host)
         self.assertFalse(env.reset_stats)
 
+    def test_specify_config_file(self):
+        with temporary_file(textwrap.dedent("""
+            host = localhost  # With "="
+            u 100             # Short form
+            hatch-rate 5      # long form
+            headless          # boolean
+        """), suffix=".conf") as conf_file_path:
+            options = parse_options(args=[
+                "--config", conf_file_path,
+            ])
+            self.assertEqual(conf_file_path, options.config)
+            self.assertEqual("localhost", options.host)
+            self.assertEqual(100, options.num_users)
+            self.assertEqual(5, options.hatch_rate)
+            self.assertTrue(options.headless)
+
+    def test_command_line_arguments_override_config_file(self):
+        with temporary_file("host=from_file", suffix=".conf") as conf_file_path:
+            options = parse_options(args=[
+                "--config", conf_file_path,
+                "--host", "from_args",
+            ])
+            self.assertEqual("from_args", options.host)
+
+    def test_locustfile_can_be_set_in_config_file(self):
+        with temporary_file(
+            "locustfile my_locust_file.py",
+            suffix=".conf",
+        ) as conf_file_path:
+            options = parse_options(args=[
+                "--config", conf_file_path,
+            ])
+            self.assertEqual("my_locust_file.py", options.locustfile)
+
 
 class LocustProcessIntegrationTest(TestCase):
     def setUp(self):