Change Locust/SubLocust API

[heyman]

I've been thinking about how we can improve the Locust API when it comes to the task scheduling/Locust/SubLocust parts. I think the current API is really good for realistically simulating real users with few lines of code. However, I think that the naming is a bit confusing, and that it can be an obstacle for new users to understand Locust.

This issue is very much related to #16

Here is an idea for a slightly changed API which I think could make it much clearer:

from locust import Locust, TaskSet, task

class WebsiteUser(Locust):
    host = "http://127.0.0.1"
    min_wait = 3000
    max_wait = 90000
    task_set = IndexPage

class IndexPage(TaskSet):
    @task
    def index(self)
        self.client.get("/")

    @task
    def some_other_task(self):
        pass

It makes for a slightly more complicated "Hello World" locustfile, but at the same time it separates the purpose of Locust from the purpose of TaskSet.

A few points about the above idea:

• TaskSets can be nested, just like SubLocusts currently can
• client is created on the Locust class but is also available as an attribute in the TaskSet instances
• All TaskSets (no matter how long down in the hierarchy) can access the Locust instance through a locust attribute
• min_wait and max_wait can be overridden in a TaskSet

What do you think? This is just an idea, and it would be great with feedback :)!

[cgbystrom]

Sure, the TaskSet style has been discussed a few times (at least in the corridors at ESN).
I think it would be a good idea.

But renaming Locust to User would a lose a bit heritage of the project. The idea behind the name was locusts swarming your site/application, which makes the concept of Locusts quite easy to explain as many can relate to the real world analogy.

Something like this:

Changing would require to rename the "hatch" related concepts, as they would make no sense for "Users" (they probably are supposed to represent humans). Having a more vague definition of the test base class would also be useful when not modeling users. For example, modeling a server representation rather than a user.

[heyman]

Good point with a more vague base class and testing something that isn't exactly "users". I'm fine with keeping it. I'll update my above example code.

[heyman]

I've implemented the API described above. All tests (including a few new ones) passes and the documentation has been updated (and gotten a few general improvements).

I'm going to go ahead and merge this if no one objects. Please feel free to look at it and give feedback. I'm pretty sure there are typos and grammar errors in the docs, but in general the documentation should be in an improved state :).

[heyman]

Merged it! If someone has feedback, add commit comments :).