From 42e884dc2e6b1eebb71717a4dabc83c8c6e321eb Mon Sep 17 00:00:00 2001 From: Troy Sankey Date: Tue, 8 Nov 2016 19:07:14 -0500 Subject: [PATCH 1/4] docs: clarify locust invocation norms Push for the following norm: all module imports either reference installed modules, or modules beneath the "project root" (i.e. the CWD). To that end, remove any examples where the locustfile is not beneath the CWD. Also, provide some example project directory structures. --- docs/quickstart.rst | 15 +++++----- docs/writing-a-locustfile.rst | 55 ++++++++++++++++++++++++++++++++++- 2 files changed, 62 insertions(+), 8 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 1de39678a4..85d9585ce6 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -74,28 +74,29 @@ as well as other user behaviours. Start Locust ============ -To run Locust with the above locust file, if it was named *locustfile.py*, we could run -(in the same directory as locustfile.py):: +To run Locust with the above locust file, if it was named *locustfile.py* and located in the current working +directory, we could run:: locust --host=http://example.com -or if the locust file is located elsewhere we could run:: +If the locust file is located under a subdirectory and/or named different than *locustfile.py*, specify +it using `-f`:: - locust -f ../locust_files/my_locust_file.py --host=http://example.com + locust -f locust_files/my_locust_file.py --host=http://example.com To run Locust distributed across multiple processes we would start a master process by specifying --master:: - locust -f ../locust_files/my_locust_file.py --master --host=http://example.com + locust -f locust_files/my_locust_file.py --master --host=http://example.com and then we would start an arbitrary number of slave processes:: - locust -f ../locust_files/my_locust_file.py --slave --host=http://example.com + locust -f locust_files/my_locust_file.py --slave --host=http://example.com If we want to run locust distributed on multiple machines we would also have to specify the master host when starting the slaves (this is not needed when running locust distributed on a single machine, since the master host defaults to 127.0.0.1):: - locust -f ../locust_files/my_locust_file.py --slave --master-host=192.168.0.100 --host=http://example.com + locust -f locust_files/my_locust_file.py --slave --master-host=192.168.0.100 --host=http://example.com .. note:: diff --git a/docs/writing-a-locustfile.rst b/docs/writing-a-locustfile.rst index 9422d04b01..a528526bd6 100644 --- a/docs/writing-a-locustfile.rst +++ b/docs/writing-a-locustfile.rst @@ -292,7 +292,7 @@ called client that simply returns self.locust.client. Using the HTTP client -====================== +---------------------- Each instance of HttpLocust has an instance of :py:class:`HttpSession ` in the *client* attribute. The HttpSession class is actually a subclass of @@ -364,3 +364,56 @@ Example:: # Statistics for these requests will be grouped under: /blog/?id=[id] for i in range(10): client.get("/blog?id=%i" % i, name="/blog?id=[id]") + +Common libraries +================= + +Often, people wish to group multiple locustfiles that share common libraries. In that case, it is important +to define the *project root* to be the directory where you invoke locust, and it is suggested that all +locustfiles live somewhere beneath the project root. + +A flat file structure works out of the box: + +* project root + + * `__init__.py` + + * `commonlib_config.py` + + * `commonlib_auth.py` + + * `locustfile_web_app.py` + + * `locustfile_api.py` + + * `locustfile_ecommerce.py` + +The locustfiles may import common libraries using, e.g. `import commonlib_auth.py`. This approach does not +cleanly separate common libraries from locustfiles, however. + +Subdirectories can be a cleaner approach, but locust cannot currenly cope with importing modules which live +outside the locustfile directory. Current workaround: for every locustfile, make sure to write +`sys.path.append(os.getcwd())` before importing any common libraries---this will ensure that the project root +(i.e. the current working directory) is always importable. + +* project root + + * `__init__.py` + + * `common/` + + * `__init__.py` + + * `config.py` + + * `auth.py` + + * `locustfiles/` + + * `__init__.py` + + * `web_app.py` + + * `api.py` + + * `ecommerce.py` From 128941f2ae451e62d424f901ba15028b9d57df74 Mon Sep 17 00:00:00 2001 From: Troy Sankey Date: Tue, 8 Nov 2016 19:39:19 -0500 Subject: [PATCH 2/4] squash me 1 * fix formatting --- docs/quickstart.rst | 5 +++-- docs/writing-a-locustfile.rst | 34 ++++++++++++++++------------------ 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 85d9585ce6..b96071e588 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -80,11 +80,12 @@ directory, we could run:: locust --host=http://example.com If the locust file is located under a subdirectory and/or named different than *locustfile.py*, specify -it using `-f`:: +it using ``-f``:: locust -f locust_files/my_locust_file.py --host=http://example.com -To run Locust distributed across multiple processes we would start a master process by specifying --master:: +To run Locust distributed across multiple processes we would start a master process by specifying +``--master``:: locust -f locust_files/my_locust_file.py --master --host=http://example.com diff --git a/docs/writing-a-locustfile.rst b/docs/writing-a-locustfile.rst index a528526bd6..d235e3664d 100644 --- a/docs/writing-a-locustfile.rst +++ b/docs/writing-a-locustfile.rst @@ -376,19 +376,17 @@ A flat file structure works out of the box: * project root - * `__init__.py` + * ``commonlib_config.py`` - * `commonlib_config.py` + * ``commonlib_auth.py`` - * `commonlib_auth.py` + * ``locustfile_web_app.py`` - * `locustfile_web_app.py` + * ``locustfile_api.py`` - * `locustfile_api.py` + * ``locustfile_ecommerce.py`` - * `locustfile_ecommerce.py` - -The locustfiles may import common libraries using, e.g. `import commonlib_auth.py`. This approach does not +The locustfiles may import common libraries using, e.g. ``import commonlib_auth.py``. This approach does not cleanly separate common libraries from locustfiles, however. Subdirectories can be a cleaner approach, but locust cannot currenly cope with importing modules which live @@ -398,22 +396,22 @@ outside the locustfile directory. Current workaround: for every locustfile, mak * project root - * `__init__.py` + * ``__init__.py`` - * `common/` + * ``common/`` - * `__init__.py` + * ``__init__.py`` - * `config.py` + * ``config.py`` - * `auth.py` + * ``auth.py`` - * `locustfiles/` + * ``locustfiles/`` - * `__init__.py` + * ``__init__.py`` - * `web_app.py` + * ``web_app.py`` - * `api.py` + * ``api.py`` - * `ecommerce.py` + * ``ecommerce.py`` From 5fb57c69e94c8143fe6949e483c322e05f64a22b Mon Sep 17 00:00:00 2001 From: Troy Sankey Date: Wed, 9 Nov 2016 14:24:53 -0500 Subject: [PATCH 3/4] squash me 2 * clarify workaround with code snippet * fix typos * use double backticks correctly * consistently refer to "locust files" using two words --- docs/writing-a-locustfile.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/writing-a-locustfile.rst b/docs/writing-a-locustfile.rst index d235e3664d..ff5a0e39cd 100644 --- a/docs/writing-a-locustfile.rst +++ b/docs/writing-a-locustfile.rst @@ -386,13 +386,13 @@ A flat file structure works out of the box: * ``locustfile_ecommerce.py`` -The locustfiles may import common libraries using, e.g. ``import commonlib_auth.py``. This approach does not -cleanly separate common libraries from locustfiles, however. +The locustfiles may import common libraries using, e.g. ``import commonlib_auth``. This approach does not +cleanly separate common libraries from locust files, however. -Subdirectories can be a cleaner approach, but locust cannot currenly cope with importing modules which live -outside the locustfile directory. Current workaround: for every locustfile, make sure to write -`sys.path.append(os.getcwd())` before importing any common libraries---this will ensure that the project root -(i.e. the current working directory) is always importable. +Subdirectories can be a cleaner approach (see example below), but locust cannot currently cope with importing +modules which live outside the locustfiles directory. Current workaround: for every locust file, make sure to +write ``sys.path.append(os.getcwd())`` before importing any common libraries---this will ensure that the +project root (i.e. the current working directory) is always importable. * project root @@ -415,3 +415,8 @@ outside the locustfile directory. Current workaround: for every locustfile, mak * ``api.py`` * ``ecommerce.py`` + +With the above project structure, your locust files can import common libraries using:: + + sys.path.append(os.getcwd()) + import common.auth From dad1e78d2f717391d74e33cf4c2c3888e144efbd Mon Sep 17 00:00:00 2001 From: Troy Sankey Date: Mon, 12 Dec 2016 09:57:15 -0500 Subject: [PATCH 4/4] squash me 3 * clarify exactly why locust cannot cope with locustfiles in subdirectories which import libraries in a different subdirectories. --- docs/writing-a-locustfile.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/writing-a-locustfile.rst b/docs/writing-a-locustfile.rst index ff5a0e39cd..d27c046bd6 100644 --- a/docs/writing-a-locustfile.rst +++ b/docs/writing-a-locustfile.rst @@ -389,10 +389,11 @@ A flat file structure works out of the box: The locustfiles may import common libraries using, e.g. ``import commonlib_auth``. This approach does not cleanly separate common libraries from locust files, however. -Subdirectories can be a cleaner approach (see example below), but locust cannot currently cope with importing -modules which live outside the locustfiles directory. Current workaround: for every locust file, make sure to -write ``sys.path.append(os.getcwd())`` before importing any common libraries---this will ensure that the -project root (i.e. the current working directory) is always importable. +Subdirectories can be a cleaner approach (see example below), but locust will only import modules relative to +the directory in which the running locustfile is placed. If you wish to import from your project root (i.e. the +location where you are running the locust command), make sure to write ``sys.path.append(os.getcwd())`` in your +locust file(s) before importing any common libraries---this will make the project root (i.e. the current +working directory) importable. * project root