Merge pull request #2851 from locustio/improve-docs-for---config-user…

…s-and-give-better-error-messages-if-json-is-bad

Improve docs for --class-picker/--config-users and give better error messages if json is bad

docs/configuration.rst

@@ -159,15 +159,13 @@ Example:
 
 .. _class-picker:
 
-Running Locust with User class UI picker
-========================================
+Pick User classes, Shapes and tasks from the UI
+===============================================
 
 You can select which Shape class and which User classes to run in the WebUI when running locust with the ``--class-picker`` flag.
 No selection uses all the available User classes.
 
-Example:
-
-With the following file structure:
+For example, with a file structure like this:
 
 .. code-block::
 
@@ -194,7 +192,7 @@ The Web UI will display:
 
 The class picker additionally allows for disabling individual User tasks, changing the weight or fixed count, and configuring the host.
 
-It is even possible to add custom arguments that you wish to be configurable for each user. Simply add a ``json`` classmethod
+It is even possible to add custom attributes that you wish to be configurable for each User. Simply add a ``json`` classmethod
 to your user:
 
 .. code-block:: python
@@ -211,24 +209,28 @@ to your user:
                 "some_custom_arg": "example"
             }
 
-Configuration for the User classes
-==================================
+Configure Users from command line
+=================================
 
-You can configure any settings you may wish for each user on the command line, the same as you may in the UI.
-Using the ``--config-users`` argument, you can also pass a JSON string or file with your user configuration. To configure
-multiple users you pass multiple arguments to ``--config-users`` or use a JSON Array.
+You can update User class attributes from the command line too, using the ``--config-users`` argument:
 
-Each user settings object must contain a key ``user_class_name``. This key corresponds to the class that you wish
-to configure.
+.. code-block:: console
 
-Example:
+    $ locust --config-users '{"user_class_name": "Example", "fixed_count": 1, "some_custom_attribute": false}'
+
+To configure multiple users you pass multiple arguments to ``--config-users``, or use a JSON Array. You can also pass a path to a JSON file.
 
 .. code-block:: console
 
-    $ locust --config-users '{"user_class_name": "Example", "fixed_count": 1}'
-    $ locust --config-users '[{"user_class_name": "Example", "fixed_count": 1}, {"user_class_name": "ExampleTwo", "fixed_count": 2}]'
     $ locust --config-users '{"user_class_name": "Example", "fixed_count": 1}' '{"user_class_name": "ExampleTwo", "fixed_count": 2}'
-    $ locust --config-users config_users.json
+    $ locust --config-users '[{"user_class_name": "Example", "fixed_count": 1}, {"user_class_name": "ExampleTwo", "fixed_count": 2}]'
+    $ locust --config-users my_user_config.json
+
+When using this way to configure your users, you can set any attribute.
+
+.. note::
+
+    ``--config-users`` is a somewhat experimental feature and the json format may change even between minor Locust revisions.
 
 Custom arguments
 ================

locust/main.py

@@ -391,9 +391,17 @@ def ensure_user_class_name(config):
                     ensure_user_class_name(user_config)
 
                     environment.update_user_class(user_config)
-            except Exception as e:
+            except json.decoder.JSONDecodeError as e:
                 logger.error(f"The --config-users argument must be in valid JSON string or file: {e}")
                 sys.exit(-1)
+            except KeyError as e:
+                logger.error(
+                    f"Error applying user config, probably you tried to specify config for a User not present in your locustfile: {e}"
+                )
+                sys.exit(-1)
+            except Exception as e:
+                logger.exception(e)
+                sys.exit(-1)
 
     if (
         shape_class