Skip to main content

AsyncIO Loads client

Project description


Simple Python 3.5+ based tool to write load tests.

Uses asyncio and aiohttp.client

molotov provides:

  • a scenario decorator that can be used to turn a function into a load test.

  • a aiohttp.client session to interact with the HTTP application.

  • a command line to run the load test.

  • an optional curses interface

motolov runs each scenario inside a coroutine (==a worker). You can spawn as many routines as you want to increase concurrency. If your scenarios just contains network calls, you can spin up a few hundreds workers to generate some pretty good load.

If you reach a peak and you want more load, motolov can also run several processes, each one running its coroutines separately. For instance if you run 10 processes and 100 coroutines, that will generate a load of 1000 coroutines spread across 10 separate processes.

Of course, unlike coroutines running in the same process, each forked process will have its own memory space. If your scenario share some state, you need to take this into account in your design.


To create a load test, you need to create a Python module with some functions decorated with the scenario decorator.

The function receives a session object inherited from aiohttp.ClientSession.

Here’s a full example

import json
from molotov import scenario

async def scenario_one(session):
    with await session.get('https://myapp/api') as resp:
        res = await resp.json()
        assert res['result'] == 'OK'

async def scenario_two(session):
    somedata = json.dumps({'OK': 1})
    with await'http://myapp/api', data=somedata) as resp:
        assert resp.status_code == 200

When molotov runs, it creates some workers and each worker runs a sequence of functions. To determine which function should be run for each step, the worker randomly picks one given their weights.

In our example, scenario_two is picked 60% of the time.

To run the script you can use the module name or its path.

In the example below, the script is executed in quiet mode with 50 concurrent users for 60 seconds, and stops on the first failure:

$ molotov molotov/tests/ --statsd -w 50 -d 60 -qx


To run a test, use the molotov runner and point it to the scenario module or path:

$ bin/molotov --help
usage: molotov [-h] [--statsd] [--statsd-host STATSD_HOST]
            [--statsd-port STATSD_PORT] [--version] [--debug] [-v]
            [-w WORKERS] [-p PROCESSES] [-d DURATION] [-q] [-x] [-c]

Load test.

positional arguments:
scenario              path or module name that contains scenarii

optional arguments:
-h, --help            show this help message and exit
--statsd              Sends metrics to Statsd.
--statsd-host STATSD_HOST
                        Statsd host.
--statsd-port STATSD_PORT
                        Statsd port.
--version             Displays version and exits.
--debug               Run the event loop in debug mode.
-v, --verbose         Verbose
-w WORKERS, --workers WORKERS
                        Number of workers
                        Number of processes
-d DURATION, --duration DURATION
                        Duration in seconds
-q, --quiet           Quiet
-x, --exception       Stop on first failure.
-c, --console         Use simple console for feedback

Running from a git repo

To run molotov directly from a github repo, add a molotov.json at the top of that repo alongside your molotov tests.

molotov.json is a configuration file that contains a list of tests to run. Each test is defined by a name and the options that will be passed in the command line to molotov.

In the following example, two tests are defined, test and test-heavy:

  "molotov": {
    "tests": {
      "test": {"duration": 30,
               "verbose": true
      "test-heavy": {"duration": 300,
                     "users": 30

Once you have that file on the top of you repository you can directly run it using molotov, with the moloslave command.


$ moloslave test

This will simply run molotov with the options from the json file.

There are also two global options you can use to run the test:

  • requirements: points a Pip requirements file that will be installed prior to the test

  • env: mapping containing environment variables that will be set prior to the test


{"molotov": {
   "requirements": "requirements.txt",
   "env": {"SERVER_URL": ""},
   "tests": {
     "test": {"duration": 30},
     "test-heavy": {"duration": 300, "workers": 10}

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

molotov-0.1.tar.gz (10.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page