Permalink
Browse files

Merge pull request #501 from pwnage101/docs-invocation-from-root

docs: clarify locust invocation norms
  • Loading branch information...
2 parents a33fdd2 + dad1e78 commit 3cddb18621f2ca905cc9d6f239f0f7e95b230143 @justiniso justiniso committed on GitHub Dec 13, 2016
Showing with 68 additions and 9 deletions.
  1. +10 −8 docs/quickstart.rst
  2. +58 −1 docs/writing-a-locustfile.rst
View
@@ -74,28 +74,30 @@ 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::
+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::
@@ -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 <locust.clients.HttpSession>`
in the *client* attribute. The HttpSession class is actually a subclass of
@@ -364,3 +364,60 @@ 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
+
+ * ``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``. This approach does not
+cleanly separate common libraries from locust files, however.
+
+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
+
+ * ``__init__.py``
+
+ * ``common/``
+
+ * ``__init__.py``
+
+ * ``config.py``
+
+ * ``auth.py``
+
+ * ``locustfiles/``
+
+ * ``__init__.py``
+
+ * ``web_app.py``
+
+ * ``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

0 comments on commit 3cddb18

Please sign in to comment.