Merge branch 'master' into geventhttpclientmergeconflicts

.coveragerc

@@ -1,6 +1,7 @@
 [run]
 branch = True
 source = locust
+concurrency = gevent
 
 [report]
 exclude_lines =

.github/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+## Release Process
+
+ * Run github_changelog_generator to update `CHANGELOG.md`
+  - `github_changelog_generator -u Locustio -p Locust -t $CHANGELOG_GITHUB_TOKEN`
+ * Add highlights to changelog in docs: `locust/docs/changelog.rst`
+ * Update `locust/__init__.py` with new version number: `__version__ = "VERSION"`
+ * Tag master as "VERSION" in git
+ * Build VERSION package and upload to PyPI

.github/ISSUE_TEMPLATE.md

@@ -1,7 +1,7 @@
 <!-- For general questions about how to use Locust, use either the Slack link provided in the Readme or [ask a question on Stack Overflow](https://stackoverflow.com/questions/ask) tagged Locust.-->
 
 
-### Description of issue / feature request
+### Description of issue
 
 TBD
 
@@ -13,12 +13,12 @@ TBD
 
 TBD
 
-### Environment settings (for bug reports)
+### Environment settings
 
 - OS:
 - Python version:
 - Locust version:
 
 ### Steps to reproduce (for bug reports)
 
-TBD - [example code appreciated](https://stackoverflow.com/help/mcve)
+TBD - [please provide example code](https://stackoverflow.com/help/mcve)

.travis.yml

@@ -3,6 +3,10 @@ language: python
 cache: pip
 matrix:
   include:
+    - python: 3.7
+      env: TOXENV=py37
+      dist: xenial
+      sudo: true
     - python: 3.6
       env: TOXENV=py36
     - python: 3.5
@@ -11,6 +15,8 @@ matrix:
       env: TOXENV=py34
     - python: 2.7
       env: TOXENV=py27
+    - stage: Verify Docker image builds
+      script: docker build -t locustio/locust .
 addons:
   apt:
     packages:

Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.6.6-alpine3.8
+
+RUN apk --no-cache add g++ \ 
+      && apk --no-cache add zeromq-dev \
+      && pip install locustio pyzmq
+
+EXPOSE 8089 5557 5558
+
+ENTRYPOINT ["/usr/local/bin/locust"]

MANIFEST.in

@@ -1,2 +1,3 @@
+include LICENSE
 recursive-include locust/static *
 recursive-include locust/templates *

Makefile

@@ -4,8 +4,11 @@ coverage:
 test:
 	tox
 
-release:
-	rm dist/* && python setup.py sdist && twine upload dist/*
+build:
+	rm -f dist/* && python setup.py sdist bdist_wheel
+
+release: build
+	twine upload dist/*
 
 build_docs:
 	sphinx-build -b html docs/ docs/_build/

README.md

@@ -56,7 +56,7 @@ More info and documentation can be found at: <a href="https://docs.locust.io/">h
 
 For questions about how to use Locust, feel free to stop by the Slack or ask questions on Stack Overflow tagged Locust.
 
-## Bug reporting or feature requests
+## Bug reporting
 
 Open a Github issue and follow the template listed there.
 
@@ -74,4 +74,4 @@ Open source licensed under the MIT license (see _LICENSE_ file for details).
 
 ## Supported Python Versions
 
-Locust supports Python 2.7, 3.4, 3.5, and 3.6.
+Locust is supported on Python 2.7, 3.4, 3.5, 3.6, 3.7.

docker_start.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+if [ -z "${TARGET_URL}" ]; then
+  echo "ERROR: TARGET_URL not configured" >&2
+  exit 1
+fi
+
+LOCUST_MODE="${LOCUST_MODE:=standalone}"
+LOCUST_OPTS="-f ${LOCUSTFILE_PATH:-/locustfile.py} -H ${TARGET_URL}"
+
+if [ "${LOCUST_MODE}" = "master" ]; then
+    LOCUST_OPTS="${LOCUST_OPTS} --master"
+elif [ "${LOCUST_MODE}" = "slave" ]; then
+    if [ -z "${LOCUST_MASTER_HOST}" ]; then
+        echo "ERROR: MASTER_HOST is empty. Slave mode requires a master" >&2
+        exit 1
+    fi
+
+    LOCUST_OPTS="${LOCUST_OPTS} --slave --master-host=${LOCUST_MASTER_HOST} --master-port=${LOCUST_MASTER_PORT:-5557}"
+fi
+
+echo "Starting Locust..."
+echo "$ locust ${LOCUST_OPTS}"
+
+locust ${LOCUST_OPTS}

docs/api.rst

@@ -34,7 +34,7 @@ TaskSequence class
 	:members: locust, parent, min_wait, max_wait, wait_function, client, tasks, interrupt, schedule_task
 
 seq_task decorator
-==============
+==================
 
 .. autofunction:: locust.core.seq_task
 

docs/changelog.rst

@@ -1,6 +1,31 @@
-##########
-Changelog
-##########
+####################
+Changelog Highlights
+####################
+
+For full details of the Locust changelog, please see https://github.com/locustio/locust/blob/master/CHANGELOG.md
+
+
+
+0.10.0
+=====
+
+* Python 3.7 support
+* Added heartbeat to detect down slaves
+* Numerous bugfixes/documentation updates (see detailed changelog)
+
+
+0.9.0
+=====
+
+* Added detailed changelog (https://github.com/locustio/locust/blob/master/CHANGELOG.md)
+* Numerous bugfixes (see detailed changelog)
+* Added sequential task support - https://github.com/locustio/locust/pull/827
+* Added support for user-defined wait_function - https://github.com/locustio/locust/pull/785
+* By default, Locust no longer resets the statistics when the hatching is complete.  
+  Therefore :code:`--no-reset-stats` has been deprected (since it's now the default behaviour), 
+  and instead a new :code:`--reset-stats` option has been added.
+* Dropped support for Python 3.3
+* Updated documentation
 
 0.8.1
 =====

docs/installation.rst

@@ -1,14 +1,27 @@
 Installation
 ============
 
-Locust is available on PyPI and can be installed through pip or easy_install
+Locust is available on `PyPI <https://pypi.org/project/locustio/>`_ and can be installed with `pip <https://pip.pypa.io/>`_.
+
+for Python 2.7:
+
+.. code-block:: console
+
+    $ python -m pip install locustio
+
+for Python 3:
 
 .. code-block:: console
 
-    pip install locustio
+    $ python3 -m pip install locustio
 
+If you want the bleeding edge version, you can use pip to install directly from our Git repository.  For example, to install the master branch using Python 3:
 
-When Locust is installed, a **locust** command should be available in your shell (if you're not using 
+.. code-block:: console
+
+    $ python3 -m pip install -e git://github.com/locustio/locust.git@master#egg=locustio
+
+Once Locust is installed, a **locust** command should be available in your shell. (if you're not using
 virtualenv—which you should—make sure your python script directory is on your path).
 
 To see available options, run:
@@ -21,18 +34,18 @@ To see available options, run:
 Supported Python Versions
 -------------------------
 
-Locust supports Python 2.7, 3.4, 3.5, and 3.6.
+Locust is supported on Python 2.7, 3.4, 3.5, 3.6, 3.7.
 
 
 Installing Locust on Windows
 ----------------------------
 
-On Windows, running ``pip install locustio`` *should* work. 
+On Windows, running ``pip install locustio`` *should* work.
 
 However, if it doesn't, chances are that it can be fixed by first installing
-the pre built binary packages for pyzmq, gevent and greenlet. 
+the pre built binary packages for pyzmq, gevent and greenlet.
 
-You can find an unofficial collection of pre built python packages for windows here: 
+You can find an unofficial collection of pre built python packages for windows here:
 `http://www.lfd.uci.edu/~gohlke/pythonlibs/ <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_
 
 When you've downloaded a pre-built ``.whl`` file, you can install it with:
@@ -41,26 +54,26 @@ When you've downloaded a pre-built ``.whl`` file, you can install it with:
 
     $ pip install name-of-file.whl
 
-Once you've done that you should be able to just ``pip install locustio``. 
+Once you've done that you should be able to just ``pip install locustio``.
 
 .. note::
 
-    Running Locust on Windows should work fine for developing and testing your load testing 
-    scripts. However, when running large scale tests, it's recommended that you do that on 
+    Running Locust on Windows should work fine for developing and testing your load testing
+    scripts. However, when running large scale tests, it's recommended that you do that on
     Linux machines, since gevent's performance under Windows is poor.
 
 
-Installing Locust on OS X
--------------------------
+Installing Locust on macOS
+--------------------------
 
 The following is currently the shortest path to installing gevent on OS X using Homebrew.
 
 #. Install `Homebrew <http://mxcl.github.com/homebrew/>`_.
 #. Install libev (dependency for gevent):
 
-    .. code-block:: console
+.. code-block:: console
 
-        brew install libev
+    brew install libev
 
 #. Then follow the above instructions.
 

docs/running-locust-distributed.rst

@@ -81,6 +81,12 @@ Used when starting the master node with ``--no-web``. The master node will then
 nodes has connected before the test is started.
 
 
+Running distributed with Docker
+=============================================
+
+See :ref:`running-locust-docker`
+
+
 Running Locust distributed without the web UI
 =============================================
 

docs/running-locust-docker.rst

@@ -0,0 +1,43 @@
+.. _running-locust-docker:
+
+=================================
+Running Locust with Docker
+=================================
+
+To keep things simple we provide a single Docker image that can run standalone, as a master, or as a slave. 
+
+
+Environment Variables
+---------------------------------------------
+
+- ``LOCUST_MODE``
+
+One of 'standalone', 'master', or 'slave'. Defaults to 'standalone'.
+
+- ``LOCUSTFILE_PATH``
+
+The path inside the container to the locustfile. Defaults to '/locustfile.py`
+
+- ``LOCUST_MASTER_HOST``
+
+The hostname of the master.
+
+- ``LOCUST_MASTER_PORT``
+
+The port used to communicate with the master. Defaults to 5557.
+
+
+Add your tests
+---------------------------------------------
+
+The easiest way to get your tests running is to build an image with your test file built in. Once you've 
+written your locustfile you can bake it into a Docker image with a simple ``Dockerfile``:
+
+```
+FROM locustio/locust
+ADD locustfile.py locustfile.py
+```
+
+You'll need to push the built image to a Docker repository such as Dockerhub, AWS ECR, or GCR in order for
+distributed infrastructure to be able to pull the image. See your chosen repository's documentation on how
+to authenticate with the repository to pull the image.

docs/writing-a-locustfile.rst

@@ -48,7 +48,9 @@ The *min_wait* and *max_wait* attributes can also be overridden in a TaskSet cla
 The *weight* attribute
 ----------------------
 
-You can run two locusts from the same file like so:
+If more than one locust class exists in the file, and no locusts are specified on the command line,
+each new spawn will choose randomly from the existing locusts. Otherwise, you can specify which locusts
+to use from the same file like so:
 
 .. code-block:: console
 

examples/browse_docs_sequence_test.py

@@ -2,13 +2,13 @@
 # browsing the Locust documentation on https://docs.locust.io/
 
 import random
-from locust import HttpLocust, TaskSquence, seq_task, task
+from locust import HttpLocust, TaskSequence, seq_task, task
 from pyquery import PyQuery
 
 
-class BrowseDocumentationSequence(TaskSquence):
+class BrowseDocumentationSequence(TaskSequence):
     def on_start(self):
-        self.urls_on_current_page = self.toc_urls
+        self.urls_on_current_page = self.toc_urls = None
 
     # assume all users arrive at the index page
     @seq_task(1)

examples/docker-compose/docker-compose.yml

@@ -0,0 +1,25 @@
+version: "3.4"
+
+x-common: &common
+  image: locustio/locust
+  environment: &common-env
+    TARGET_URL: http://locust-master:8089
+    LOCUSTFILE_PATH: /tests/basic.py
+  volumes:
+    - ../:/tests
+
+services:
+  locust-master:
+    <<: *common
+    ports:
+      - 8089:8089
+    environment:
+      <<: *common-env
+      LOCUST_MODE: master
+
+  locust-slave:
+    <<: *common
+    environment:
+      <<: *common-env
+      LOCUST_MODE: slave
+      LOCUST_MASTER_HOST: locust-master

locust/__init__.py

@@ -1,4 +1,4 @@
 from .core import HttpLocust, Locust, TaskSet, TaskSequence, task, seq_task
 from .exception import InterruptTaskSet, ResponseError, RescheduleTaskImmediately
 
-__version__ = "0.8.1"
+__version__ = "0.11.1"

locust/clients.py

@@ -90,7 +90,7 @@ def request(self, method, url, name=None, catch_response=False, **kwargs):
         :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
         :param files: (optional) Dictionary of ``'filename': file-like-objects`` for multipart encoding upload.
         :param auth: (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
-        :param timeout: (optional) How long to wait for the server to send data before giving up, as a float, 
+        :param timeout: (optional) How long in seconds to wait for the server to send data before giving up, as a float, 
             or a (`connect timeout, read timeout <user/advanced.html#timeouts>`_) tuple.
         :type timeout: float or tuple
         :param allow_redirects: (optional) Set to True by default.