Alternative grouping

docs/testing-other-systems.rst

@@ -1,7 +1,7 @@
 .. _testing-other-systems:
 
 ========================
-Testing non-HTTP systems 
+Testing other systems 
 ========================
 
 Locust only comes with built-in support for HTTP/HTTPS but it can be extended to load test almost any system. You do this by writing a custom client that triggers :py:attr:`request <locust.event.Events.request>`
@@ -44,4 +44,13 @@ gRPC client, base User and example usage:
 
 .. literalinclude:: ../examples/grpc/locustfile.py
 
+
+Example: Patching over SDK's that wrap around Session objects
+=============================================================
+
+If you have a prebuilt SDK for a target system that is a essentially a wrapper for Session object. You can use the a pattern of patching over the internal session object with the locust provided one:
+
+.. literalinclude:: ../examples/sdk_session_patching/session_patch_locustfile.py
+
+
 For more examples of user types, see `locust-plugins <https://github.com/SvenskaSpel/locust-plugins#users>`_ (it has users for WebSocket/SocketIO, Kafka, Selenium/WebDriver and more) 

docs/writing-a-locustfile.rst

@@ -546,6 +546,35 @@ Example:
     for i in range(10):
         self.client.get("/blog?id=%i" % i, name="/blog?id=[id]")
 
+There may be situations where passing in a parameter into request function is not possible, such as when interacting with libraries/SDK's that
+wrap a Requests session. An alternative say of grouping requests is provided By setting the ``client.group_name`` attribute
+
+.. code-block:: python
+
+    # Statistics for these requests will be grouped under: /blog/?id=[id]
+    self.client.group_name="/blog?id=[id]"
+    for i in range(10):
+        self.client.get("/blog?id=%i" % i)
+    self.client.group_name=None
+
+If You want to chain multiple groupings with minimal boilerplate, you can use the ``client.group()`` context manager. 
+
+.. code-block:: python
+
+    @task
+    def multiple_groupings_example(self): 
+
+        # Statistics for these requests will be grouped under: /blog/?id=[id]
+        with self.client.group(name="/blog?id=[id]"):
+            for i in range(10):
+                self.client.get("/blog?id=%i" % i)
+
+        # Statistics for these requests will be grouped under: /article/?id=[id]
+        with self.client.group(name="/article?id=[id]"):
+            for i in range(10):
+                self.client.get("/article?id=%i" % i)
+
+
 
 HTTP Proxy settings
 -------------------

examples/sdk_session_patching/session_patch_locustfile.py

@@ -0,0 +1,24 @@
+import locust
+from locust.user import task
+from archivist.archivist import Archivist   # Example SDK under test
+
+
+class ArchivistUser(locust.HttpUser):
+
+    def on_start(self):
+        AUTH_TOKEN = None
+
+        with open("auth.text", "r") as f:
+            AUTH_TOKEN = f.read()
+
+        # Start an instance of of the SDK
+        self.arch: Archivist = Archivist(url=self.host, auth=AUTH_TOKEN)
+        # overwrite the internal _session attribute with the locust session
+        self.arch._session = self.client
+
+    @task
+    def Create_assets(self):
+        """ User creates assets as fast as possible"""
+
+        while True:
+            self.arch.assets.create(behaviours=[], attrs={})

locust/clients.py

@@ -5,6 +5,7 @@
 from requests import Request, Response
 from requests.auth import HTTPBasicAuth
 from requests.exceptions import InvalidSchema, InvalidURL, MissingSchema, RequestException
+from contextlib import contextmanager
 
 from urllib.parse import urlparse, urlunparse
 
@@ -51,6 +52,10 @@ def __init__(self, base_url, request_event, user, *args, **kwargs):
         self.request_event = request_event
         self.user = user
 
+        # User can group name, or use the group context manager to gather performance statistics under a specific name
+        # This is an alternative to passing in the "name" parameter to the requests function
+        self.group_name = None
+
         # Check for basic authentication
         parsed_url = urlparse(self.base_url)
         if parsed_url.username and parsed_url.password:
@@ -72,6 +77,16 @@ def _build_url(self, path):
         else:
             return "%s%s" % (self.base_url, path)
 
+    @contextmanager
+    def group(self, *, name: str):
+        """Group requests using the "with" keyword"""
+
+        self.group_name = name
+        try:
+            yield
+        finally:
+            self.group_name = None
+
     def request(self, method, url, name=None, catch_response=False, context={}, **kwargs):
         """
         Constructs and sends a :py:class:`requests.Request`.
@@ -102,6 +117,10 @@ def request(self, method, url, name=None, catch_response=False, context={}, **kw
         :param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair.
         """
 
+        # if group name has been set and no name parameter has been passed in; set the name parameter to group_name
+        if self.group_name and not name:
+            name = self.group_name
+
         # prepend url with hostname unless it's already an absolute URL
         url = self._build_url(url)
         start_time = time.perf_counter()