locust-cloud 1.19.4__py3-none-any.whl → 1.19.6.dev10__py3-none-any.whl

docs/.gitignore

@@ -0,0 +1 @@
+_build/**

docs/examples.rst

@@ -0,0 +1,157 @@
+########
+Examples
+########
+
+Locustfile and mock server
+==========================
+
+If you're learning Locust and want to try it out, Locust Cloud has its own demo mock server you can test against, using the locustfile below. Pass ``--mock-server`` to spawn the mock next to your load generators and set Locust target hostname accordingly.
+
+.. code-block:: console
+
+    $ locust --cloud -f my_locustfile.py --users 100 --mock-server
+
+
+.. code-block:: python
+
+    from locust import HttpUser, task
+
+    class MyUser(HttpUser):
+        @task
+        def t(self):
+            self.client.post("/authenticate", json={"username": "foo", "password": "bar"})
+            for product_id in [1, 2, 42]:
+                self.client.get(f"/product/{product_id}", name="/product/{product_id}")
+                self.client.post("/cart/add", json={"productId": product_id})
+            self.client.post("/checkout/confirm")
+            self.client.get("/this_does_not_exist")
+
+
+Your results should be something like this (the mock intentionally has some concurrency issues, so you'll get steadily rising response times as the load increases):
+
+.. image:: images/locust-cloud-screenshot.png
+
+.. note::
+    Don't use the mock server option when you are doing normal load tests. It is only meant as an example and serves no other purpose.
+
+
+Passing options to Locust
+=========================
+
+Any parameters specified on command line that are not recognized by ``locust-cloud`` will be passed along to Locust. This allows for a seamless transition from local runs to cloud runs.
+
+Here's how to run a 100 User test, start immediately, run for 60 seconds,
+quit 1s after finishing and print statistics to the console while running:
+
+.. code-block:: console
+
+    $ locust --cloud --users 100 --autostart --run-time 60s --autoquit 1 --print-stats
+    [LOCUST-CLOUD] INFO: Authenticating (eu-north-1, v1.11.2.dev23)
+    [LOCUST-CLOUD] INFO: Deploying load generators
+    [LOCUST-CLOUD] INFO: Waiting for pods to be ready...
+    [2024-11-22 11:49:20,833] master-lb6vv-zxp64/INFO/locust.main: Starting Locust 2.32.4.dev14 (locust-cloud 1.11.2.dev23)
+    [2024-11-22 11:49:20,835] master-lb6vv-zxp64/INFO/locust.main: Starting web interface at https://locust.webui.locust.cloud/702ca98c-60e1-706c-9523-77d5c10ba5d4-free
+    [2024-11-22 11:49:23,515] master-lb6vv-zxp64/INFO/locust.runners: worker-xn7mv-4zkh5_3b4ee8708ea140eda830ff00364af204 (index 0) reported as ready. 1 workers connected.
+    [2024-11-22 11:49:24,018] master-lb6vv-zxp64/INFO/locust.main: Run time limit set to 60 seconds
+    [2024-11-22 11:49:24,019] master-lb6vv-zxp64/INFO/locust.runners: Sending spawn jobs of 100 users at 1.00 spawn rate to 1 ready workers
+    Type     Name                                         # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
+    --------|-------------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
+    POST     /authenticate                                     2     0(0.00%) |   1012    1010    1014   1010 |    0.00        0.00
+    GET      /product/{product_id}                             1     0(0.00%) |    505     505     505    505 |    0.00        0.00
+    --------|-------------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
+            Aggregated                                        3     0(0.00%) |    843     505    1014   1000 |    0.00        0.00
+    Type     Name                                         # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
+    --------|-------------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
+    POST     /authenticate                                     5     0(0.00%) |   1015    1010    1021   1010 |    0.67        0.00
+    POST     /cart/add                                         5     0(0.00%) |   1005    1004    1007   1004 |    0.33        0.00
+    GET      /product/{product_id}                             8     0(0.00%) |    508     504     520    510 |    0.67        0.00
+    --------|-------------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
+            Aggregated                                       18     0(0.00%) |    787     504    1021   1000 |    1.67        0.00
+    Type     Name                                         # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
+    --------|-------------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
+    POST     /authenticate                                     9     0(0.00%) |   1013    1005    1021   1005 |    0.83        0.00
+    POST     /cart/add                                        14     0(0.00%) |   1005    1003    1007   1003 |    1.17        0.00
+    POST     /checkout/confirm                                 2     0(0.00%) |   1005    1005    1005   1005 |    0.00        0.00
+    GET      /product/{product_id}                            18     0(0.00%) |    507     503     520    510 |    1.67        0.00
+    GET      /this_does_not_exist                              2   2(100.00%) |      4       3       6      3 |    0.00        0.00
+    ...
+    [2024-11-22 11:50:24,019] master-lb6vv-zxp64/INFO/locust.main: --run-time limit reached, stopping test
+    [2024-11-22 11:50:27,151] master-lb6vv-zxp64/INFO/locust.main: Shutting down (exit code 0)
+    Type     Name                                         # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
+    --------|-------------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
+    POST     /authenticate                                   112     0(0.00%) |   2586    1003    4553   2500 |    1.89        0.00
+    POST     /cart/add                                       239     0(0.00%) |   2674    1003    4989   2500 |    4.03        0.00
+    POST     /checkout/confirm                                60     0(0.00%) |   2633    1003    4521   2500 |    1.01        0.00
+    GET      /product/{product_id}                           262     0(0.00%) |   2156     503    4489   2000 |    4.41        0.00
+    GET      /this_does_not_exist                             60  60(100.00%) |      4       2       8      4 |    1.01        1.01
+    --------|-------------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
+            Aggregated                                      733    60(8.19%) |   2254       2    4989   2100 |   12.35        1.01
+    ...
+    Error report
+    # occurrences      Error
+    ------------------|------------------------------------------------------------------------------------------------------------
+    60                 GET /this_does_not_exist: HTTPError('404 Client Error: NOT FOUND for url: /this_does_not_exist')
+    ------------------|------------------------------------------------------------------------------------------------------------
+    [LOCUST-CLOUD] INFO: Tearing down Locust cloud...
+    [LOCUST-CLOUD] INFO: Done! ✨
+
+You can also use standard Locust env vars in the same fashion:
+
+.. code-block::
+
+    LOCUST_USERS=100 LOCUST_AUTOSTART=1 ... locust --cloud
+
+
+Automated runs (CI)
+===================
+
+If you want to run ``locust-cloud`` in a CI/CD environment, where an interactive login is not possible, you can set the ``--non-interactive`` flag or ``LOCUSTCLOUD_NON_INTERACTIVE`` environment variable. Then ``locust-cloud`` will use credentials specified environment variables instead.
+
+Simply make sure to export the corrent environment variables before running the command and things will work.
+
+.. code-block:: console
+
+    export LOCUSTCLOUD_NON_INTERACTIVE=1
+    export LOCUSTCLOUD_USERNAME='your@email.com'
+    export LOCUSTCLOUD_PASSWORD='yourpassword'
+    export LOCUSTCLOUD_REGION='us-east-1'
+    ...
+
+Typically you will also want to specify the standard Locust parameters ``--headless`` (or ``--autostart``) and ``--run-time`` as shown in the previous example. Here's a full example of how you might set it up in a GitHub action:
+
+.. code-block:: yaml
+
+    env:
+        LOCUSTCLOUD_USERNAME: ${{ secrets.LOCUSTCLOUD_USERNAME }}
+        LOCUSTCLOUD_PASSWORD: ${{ secrets.LOCUSTCLOUD_PASSWORD }}
+        LOCUSTCLOUD_REGION: eu-north-1
+        LOCUSTCLOUD_NON_INTERACTIVE: 1
+        PYTHONUNBUFFERED: 1 # ensure we see output right away
+
+    jobs:
+        build:
+            runs-on: ubuntu-latest
+            timeout-minutes: 15
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.11' 
+            - run: pip install locust
+            - run: locust --cloud -f my_locustfile.py --headless --run-time 5m
+
+
+Extra python packages
+=====================
+
+If your locustfile needs some additional Python packages, you can install them by specifying a `requirements.txt <https://pip.pypa.io/en/stable/reference/requirements-file-format/>`_ file:
+
+.. code-block:: console
+
+    locust --cloud -f my_locustfile.py --requirements requirements.txt
+
+
+View dashboard / previous test runs
+===================================
+
+You can examine the results from previous test runs (without needing to start your load generators) from your `Locust Cloud dashboard <https://auth.eu-north-1.locust.cloud/region-select>`_.

docs/first-run.rst

@@ -0,0 +1,30 @@
+#########
+First run
+#########
+
+1. Log in
+
+.. code-block:: console
+
+    $ locust --cloud --login
+    Enter the number for the region to authenticate against
+
+    1. us-east-1
+    2. eu-north-1
+
+    > 1
+
+    Attempting to automatically open the SSO authorization page in your default browser.
+    ...
+
+.. note::
+    After logging in, an API token will be stored on your machine, and you will not need to log in until it expires.
+
+2. Run a load test
+
+.. code-block:: console
+
+    $ locust --cloud -f my_locustfile.py --users 100 # ... other regular locust parameters
+    [LOCUST-CLOUD] INFO: Deploying load generators
+    [LOCUST-CLOUD] INFO: Waiting for load generators to be ready...
+    ...

docs/list-available-options.rst

@@ -0,0 +1,13 @@
+#################
+Available options
+#################
+
+Command Line Options
+====================
+
+Locust Cloud is configured mainly through command line arguments.
+
+Here's a list of all the available options:
+
+.. this file is generated from locust core
+.. include:: locust-cloud-options.txt

locust_cloud/args.py

@@ -113,7 +113,7 @@ cloud_parser = configargparse.ArgumentParser(add_help=False)
 cloud_parser.add_argument(
     "--login",
     action="store_true",
-    help="Launch an interactive session to authenticate your user.\nOnce completed your credentials will be stored and automatically refreshed for quite a long time.\nOnce those expires you will be prompted to perform another login.",
+    help="Launch an interactive session to authenticate your user.\nOnce completed your credentials will be stored and automatically refreshed for quite a long time.\nOnce those expire you will be prompted to perform another login.",
 )
 cloud_parser.add_argument(
     "--delete",
@@ -149,20 +149,20 @@ cloud_parser.add_argument(
     "--mock-server",
     action="store_true",
     default=False,
-    help="Start a demo mock service and set --host parameter to point Locust towards it",
+    help="Start a demo mock service and set --host parameter to point Locust towards it.",
 )
 cloud_parser.add_argument(
     "--extra-files",
     action=MergeToTransferEncodedZip,
     nargs="*",
     type=valid_extra_files_path,
-    help="A list of extra files or directories to upload. Space-separated, e.g. --extra-files testdata.csv *.py my-directory/",
+    help="A list of extra files or directories to upload. Space-separated, e.g. `--extra-files testdata.csv *.py my-directory/`.",
 )
 cloud_parser.add_argument(
     "--testrun-tags",
     nargs="*",
     default=None,
-    help="A list of tags that can be used to filter testruns",
+    help="A list of tags that can be used to filter testruns.",
 )
 
 combined_cloud_parser = configargparse.ArgumentParser(

{locust_cloud-1.19.4.dist-info → locust_cloud-1.19.6.dev10.dist-info}/METADATA

@@ -1,20 +1,16 @@
 Metadata-Version: 2.4
 Name: locust-cloud
-Version: 1.19.4
+Version: 1.19.6.dev10
 Summary: Locust Cloud
 Project-URL: homepage, https://locust.cloud
 Project-URL: repository, https://github.com/locustcloud/locust-cloud
 License: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
-Requires-Dist: configargparse==1.7
-Requires-Dist: gevent>=24.11.1
 Requires-Dist: locust>=2.35.0
-Requires-Dist: platformdirs>=4.3.6
-Requires-Dist: pyjwt>=2.0
-Requires-Dist: python-socketio[client]==5.11.4
-Requires-Dist: requests==2.32.3
-Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Requires-Dist: platformdirs<5.0.0,>=4.3.6
+Requires-Dist: pyjwt<3.0,>=2.0
+Requires-Dist: python-socketio[client]==5.13.0
 Description-Content-Type: text/markdown
 
 # Locust Cloud

locust_cloud-1.19.6.dev10.dist-info/RECORD

@@ -0,0 +1,18 @@
+docs/.gitignore,sha256=ghNPcjYkjQXNS_eVmu2hQFhq6FIUliAD1O2CJhulS2o,10
+docs/examples.rst,sha256=RublnAK3jHRsEtbJAr1y2NEEoN0YAjkzP1np-7tJ3aE,9565
+docs/first-run.rst,sha256=dYYVxVb1RlWPNvhE98H1D_mzTJ1H2NWNn435nag3_jA,691
+docs/list-available-options.rst,sha256=2bbVkWFT_PePixQtdppZ2AWc_uPi4vBv9p1M5jbdxFM,291
+docs/images/locust-cloud-screenshot.png,sha256=ag0IxBi-40VexC84MApol1GCgRCL2h-l8NQDTMaeTyE,477350
+locust_cloud/__init__.py,sha256=9USe4yHuvpP5xrXm0dVsi08pu2l5TcjxQl6Pei8w3lk,713
+locust_cloud/apisession.py,sha256=kCr271_l0IeMGw0L563mOecqPJj4OD9h2J3vxCM5zYQ,4015
+locust_cloud/args.py,sha256=jBAKDNckEfP5v_2rKEMWWiWK_sjW6kX3sNgzgQkGk0Q,6974
+locust_cloud/cloud.py,sha256=Ox2BNQfeVSbLN67mp5yl4ZeSFqfEsPef0H5Jxy5QMU8,6071
+locust_cloud/common.py,sha256=cFrDVKpi9OEmH6giOuj9HoIUFSBArixNtNHzZIgDvPE,992
+locust_cloud/input_events.py,sha256=MyxccgboHByICuK6VpQCCJhZQqTZAacNmkSpw-gxBEw,3420
+locust_cloud/web_login.py,sha256=1j2AQoEM6XVSDtE1q0Ryrs4jFEx07r9IQfZCoFAQXJg,2400
+locust_cloud/websocket.py,sha256=9Q7nTFuAwVhgW74DlJNcHTZXOQ1drsXi8hX9ciZhWlQ,8998
+locust_cloud-1.19.6.dev10.dist-info/METADATA,sha256=ErlJa_zEhG47vHphZUWGjAK3q1lqN7Q51ceNhW7KFGc,582
+locust_cloud-1.19.6.dev10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+locust_cloud-1.19.6.dev10.dist-info/entry_points.txt,sha256=PGyAb4e3aTsGS3N3VGShDl6VzJaXy7QwsEgsLOC7V00,57
+locust_cloud-1.19.6.dev10.dist-info/licenses/LICENSE,sha256=Ow6fY6ta4KIjdlWalmxGvRP8yLmetvkbkl-SdHMjPIs,1093
+locust_cloud-1.19.6.dev10.dist-info/RECORD,,

locust_cloud-1.19.4.dist-info/RECORD

@@ -1,13 +0,0 @@
-locust_cloud/__init__.py,sha256=9USe4yHuvpP5xrXm0dVsi08pu2l5TcjxQl6Pei8w3lk,713
-locust_cloud/apisession.py,sha256=kCr271_l0IeMGw0L563mOecqPJj4OD9h2J3vxCM5zYQ,4015
-locust_cloud/args.py,sha256=6PLJYmy1lr1qYQR4elsIhws0wJwc4_heS_xbTibO4Yw,6970
-locust_cloud/cloud.py,sha256=Ox2BNQfeVSbLN67mp5yl4ZeSFqfEsPef0H5Jxy5QMU8,6071
-locust_cloud/common.py,sha256=cFrDVKpi9OEmH6giOuj9HoIUFSBArixNtNHzZIgDvPE,992
-locust_cloud/input_events.py,sha256=MyxccgboHByICuK6VpQCCJhZQqTZAacNmkSpw-gxBEw,3420
-locust_cloud/web_login.py,sha256=1j2AQoEM6XVSDtE1q0Ryrs4jFEx07r9IQfZCoFAQXJg,2400
-locust_cloud/websocket.py,sha256=9Q7nTFuAwVhgW74DlJNcHTZXOQ1drsXi8hX9ciZhWlQ,8998
-locust_cloud-1.19.4.dist-info/METADATA,sha256=D4h_fWHJxqnhrRcxdUKq73bZVy1hb7lbMTbylAaxejw,715
-locust_cloud-1.19.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-locust_cloud-1.19.4.dist-info/entry_points.txt,sha256=PGyAb4e3aTsGS3N3VGShDl6VzJaXy7QwsEgsLOC7V00,57
-locust_cloud-1.19.4.dist-info/licenses/LICENSE,sha256=Ow6fY6ta4KIjdlWalmxGvRP8yLmetvkbkl-SdHMjPIs,1093
-locust_cloud-1.19.4.dist-info/RECORD,,