Performance Module

Locust Load Tests

Locust load-test scenarios for the TMDB movies endpoints.

Two user models, selectable by class name on the CLI (running without a class name spawns both 50/50.

  • MoviesUser — endpoint traffic mix: weighted, independent read-only requests mirroring api/movies_api.py. The original baselining model.

  • JourneyUser — realistic user journeys: four SequentialTaskSet flows (browse & drill down, search-driven, filtered discovery, cast exploration) where later steps chain ids taken from earlier responses.

Both use Locust’s own self.client (not the API classes) so every request is instrumented for the stats report; auth and URLs are still single-sourced from config.config.Config / .env.

Target is the live TMDB API — keep the load gentle (see performance/README.md).

Run from the repo root:

poetry run locust -f performance/locustfile.py JourneyUser # web UI at :8089 poetry run locust -f performance/locustfile.py MoviesUser –headless -u 3 -r 1 -t 30s

class performance.locustfile.BrowseAndDrillDown(*args, **kwargs)[source]

Bases: SequentialTaskSet

Casual visitor: popular list → details of a listed movie → its alt titles.

alternative_titles()[source]

Fetch the picked movie’s alternative titles, then end the journey.

Raises:

locust.exception.InterruptTaskSet – Always, via self.interrupt(), returning control to the user class so its next journey can be scheduled.

movie_details()[source]

Open the details of the movie picked from the popular list.

popular_page()[source]

Fetch page 1 of popular movies and remember a random listed id.

tasks: list[TaskSet | Callable] = [<function BrowseAndDrillDown.popular_page>, <function BrowseAndDrillDown.movie_details>, <function BrowseAndDrillDown.alternative_titles>]

Collection of python callables and/or TaskSet classes that the User(s) will run.

If tasks is a list, the task to be performed will be picked randomly.

If tasks is a (callable,int) list of two-tuples, or a {callable:int} dict, the task to be performed will be picked randomly, but each task will be weighted according to its corresponding int value. So in the following case, ThreadPage will be fifteen times more likely to be picked than write_post:

class ForumPage(TaskSet):
    tasks = {ThreadPage:15, write_post:1}
class performance.locustfile.CastExploration(*args, **kwargs)[source]

Bases: SequentialTaskSet

Rabbit-hole user: movie details → its credits → a cast member’s details.

movie_credits()[source]

Fetch the movie’s credits and remember a random cast member’s id.

movie_details()[source]

Open a random movie’s details (id drawn from movie_ids.txt).

person_details()[source]

Open the picked cast member’s person details, then end the journey.

Raises:

locust.exception.InterruptTaskSet – Always, via self.interrupt().

tasks: list[TaskSet | Callable] = [<function CastExploration.movie_details>, <function CastExploration.movie_credits>, <function CastExploration.person_details>]

Collection of python callables and/or TaskSet classes that the User(s) will run.

If tasks is a list, the task to be performed will be picked randomly.

If tasks is a (callable,int) list of two-tuples, or a {callable:int} dict, the task to be performed will be picked randomly, but each task will be weighted according to its corresponding int value. So in the following case, ThreadPage will be fifteen times more likely to be picked than write_post:

class ForumPage(TaskSet):
    tasks = {ThreadPage:15, write_post:1}
class performance.locustfile.FilteredDiscovery(*args, **kwargs)[source]

Bases: SequentialTaskSet

Undecided browser: filtered discover → two more pages → details of a hit.

discover_first_page()[source]

Run a random filter combination and remember a random hit’s id.

discover_more_pages()[source]

Page through results 2–3 with the same filters, back-to-back.

movie_details()[source]

Open the details of the picked discover hit, then end the journey.

Raises:

locust.exception.InterruptTaskSet – Always, via self.interrupt().

tasks: list[TaskSet | Callable] = [<function FilteredDiscovery.discover_first_page>, <function FilteredDiscovery.discover_more_pages>, <function FilteredDiscovery.movie_details>]

Collection of python callables and/or TaskSet classes that the User(s) will run.

If tasks is a list, the task to be performed will be picked randomly.

If tasks is a (callable,int) list of two-tuples, or a {callable:int} dict, the task to be performed will be picked randomly, but each task will be weighted according to its corresponding int value. So in the following case, ThreadPage will be fifteen times more likely to be picked than write_post:

class ForumPage(TaskSet):
    tasks = {ThreadPage:15, write_post:1}
class performance.locustfile.JourneyUser(*args, **kwargs)[source]

Bases: HttpUser

A simulated visitor running complete browse sessions.

Each iteration picks one journey by weight (~50/25/15/10 user mix) and runs its steps in order with think-time between them; ids for later steps come from earlier responses, so the traffic is correlated like a real client’s. Write endpoints stay excluded — no mutation load on the live API.

abstract: bool = False

If abstract is True, the class is meant to be subclassed, and users will not choose this locust during a test

host: str | None = 'https://api.themoviedb.org'

Base hostname to swarm. i.e: http://127.0.0.1:1234

on_start()[source]

Attach auth headers to this user’s session once, at spawn time.

tasks: list[TaskSet | Callable] = [<class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.BrowseAndDrillDown'>, <class 'performance.locustfile.SearchDriven'>, <class 'performance.locustfile.SearchDriven'>, <class 'performance.locustfile.SearchDriven'>, <class 'performance.locustfile.SearchDriven'>, <class 'performance.locustfile.SearchDriven'>, <class 'performance.locustfile.FilteredDiscovery'>, <class 'performance.locustfile.FilteredDiscovery'>, <class 'performance.locustfile.FilteredDiscovery'>, <class 'performance.locustfile.CastExploration'>, <class 'performance.locustfile.CastExploration'>]

Collection of python callables and/or TaskSet classes that the Locust user(s) will run.

If tasks is a list, the task to be performed will be picked randomly.

If tasks is a (callable,int) list of two-tuples, or a {callable:int} dict, the task to be performed will be picked randomly, but each task will be weighted according to its corresponding int value. So in the following case, ThreadPage will be fifteen times more likely to be picked than write_post:

class ForumPage(TaskSet):
    tasks = {ThreadPage:15, write_post:1}
wait_time()
class performance.locustfile.MoviesUser(*args, **kwargs)[source]

Bases: HttpUser

A simulated TMDB API consumer issuing independent movie requests.

Task weights approximate real read traffic: movie details requested most, list endpoints less often. Write endpoints (rating add/delete) are deliberately excluded — no mutation load on the live API.

abstract: bool = False

If abstract is True, the class is meant to be subclassed, and users will not choose this locust during a test

alternative_titles()[source]

Fetch alternative titles for the fixed Config.MOVIE_ID movie.

host: str | None = 'https://api.themoviedb.org'

Base hostname to swarm. i.e: http://127.0.0.1:1234

movie_details()[source]

Fetch details of a random movie (weight 3: the dominant request).

on_start()[source]

Attach auth headers to this user’s session once, at spawn time.

popular_movies()[source]

Fetch page 1 of popular movies, with custom pass/fail judgment.

Demonstrates catch_response: a 200 whose body has no results is marked a failure even though the status code alone would pass.

tasks: list[TaskSet | Callable] = [<function MoviesUser.movie_details>, <function MoviesUser.movie_details>, <function MoviesUser.movie_details>, <function MoviesUser.popular_movies>, <function MoviesUser.popular_movies>, <function MoviesUser.top_rated_movies>, <function MoviesUser.alternative_titles>]

Collection of python callables and/or TaskSet classes that the Locust user(s) will run.

If tasks is a list, the task to be performed will be picked randomly.

If tasks is a (callable,int) list of two-tuples, or a {callable:int} dict, the task to be performed will be picked randomly, but each task will be weighted according to its corresponding int value. So in the following case, ThreadPage will be fifteen times more likely to be picked than write_post:

class ForumPage(TaskSet):
    tasks = {ThreadPage:15, write_post:1}
top_rated_movies()[source]

Fetch page 1 of top-rated movies.

wait_time()
class performance.locustfile.SearchDriven(*args, **kwargs)[source]

Bases: SequentialTaskSet

Searcher: query page 1 → page 2 of the same query → details of a result.

movie_details()[source]

Open the details of the picked search result, then end the journey.

Raises:

locust.exception.InterruptTaskSet – Always, via self.interrupt().

search_first_page()[source]

Search a rotating query and remember a random matched movie id.

search_second_page()[source]

Paginate to page 2 of the same query, like a user scanning on.

tasks: list[TaskSet | Callable] = [<function SearchDriven.search_first_page>, <function SearchDriven.search_second_page>, <function SearchDriven.movie_details>]

Collection of python callables and/or TaskSet classes that the User(s) will run.

If tasks is a list, the task to be performed will be picked randomly.

If tasks is a (callable,int) list of two-tuples, or a {callable:int} dict, the task to be performed will be picked randomly, but each task will be weighted according to its corresponding int value. So in the following case, ThreadPage will be fifteen times more likely to be picked than write_post:

class ForumPage(TaskSet):
    tasks = {ThreadPage:15, write_post:1}