"""
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
"""
import random
from locust import HttpUser, SequentialTaskSet, between, task
from config.config import Config
from tests.data.data_loader import load_test_data
from tests.helpers.test_data_generators import pick_random_movie_id
API = f"/{Config.API_VERSION}"
# Rotating search queries, single-sourced from the integration suite's data so
# perf and functional tests exercise the same known-good query set.
SEARCH_QUERIES = sorted({
case["query_param"]["query"]
for case in load_test_data("test_data.yaml", "search_movies")["search_movies"]["valid"]
})
# Filter combinations for the discovery journey (genre ids: action, comedy,
# sci-fi). Values are strings — requests would serialize Python bools/ints
# in forms TMDB only tolerates undocumented.
DISCOVER_FILTERS = (
{"with_genres": "28", "sort_by": "popularity.desc"},
{"with_genres": "35", "primary_release_year": "2020"},
{"with_genres": "878", "sort_by": "vote_average.desc", "vote_count.gte": "1000"},
)
def _auth_headers():
"""
Build the default headers for every simulated user's session.
Also fail-fast validates the credential, so a missing ``TMDB_AUTH_TOKEN``
aborts at user spawn instead of surfacing as per-request 401 failures.
(Validation is deliberately not at module import time: Sphinx imports this
module to render docs and must not require a configured ``.env``.)
:returns: Headers with Bearer authorization and JSON content type.
:rtype: dict
:raises RuntimeError: If ``TMDB_AUTH_TOKEN`` is not configured.
"""
Config.validate(["AUTH_TOKEN"])
return {
"Authorization": f"Bearer {Config.AUTH_TOKEN}",
"Content-Type": "application/json",
}
def _pick_result_id(response, key="results"):
"""
Pull a random item id out of a paginated response.
Used to chain journey steps: the id picked from one step's response
becomes the path parameter of the next step's request.
:param response: Response from an instrumented ``self.client`` call.
:type response: requests.Response
:param key: Body key holding the list of items to pick from.
:type key: str
:returns: A random item's ``id``, or ``None`` when the request failed or
the list is missing/empty (callers skip their step on ``None``).
:rtype: int or None
"""
items = response.json().get(key) if response.ok else None
return random.choice(items)["id"] if items else None
[docs]
class BrowseAndDrillDown(SequentialTaskSet):
"""Casual visitor: popular list → details of a listed movie → its alt titles."""
[docs]
@task
def popular_page(self):
"""Fetch page 1 of popular movies and remember a random listed id."""
response = self.client.get(f"{API}/movie/popular", params={"page": 1})
self.movie_id = _pick_result_id(response)
[docs]
@task
def movie_details(self):
"""Open the details of the movie picked from the popular list."""
if self.movie_id:
self.client.get(f"{API}/movie/{self.movie_id}", name=f"{API}/movie/[id]")
[docs]
@task
def alternative_titles(self):
"""
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.
"""
if self.movie_id:
self.client.get(
f"{API}/movie/{self.movie_id}/alternative_titles",
name=f"{API}/movie/[id]/alternative_titles",
)
self.interrupt() # Ends the journey and helps to put the execution back to the user class to pick the next one.
[docs]
class SearchDriven(SequentialTaskSet):
"""Searcher: query page 1 → page 2 of the same query → details of a result."""
[docs]
@task
def search_first_page(self):
"""Search a rotating query and remember a random matched movie id."""
self.query = random.choice(SEARCH_QUERIES)
response = self.client.get(
f"{API}/search/movie",
params={"query": self.query, "page": 1},
name=f"{API}/search/movie",
)
self.movie_id = _pick_result_id(response)
[docs]
@task
def search_second_page(self):
"""Paginate to page 2 of the same query, like a user scanning on."""
self.client.get(
f"{API}/search/movie",
params={"query": self.query, "page": 2},
name=f"{API}/search/movie",
)
[docs]
@task
def movie_details(self):
"""
Open the details of the picked search result, then end the journey.
:raises locust.exception.InterruptTaskSet: Always, via
``self.interrupt()``.
"""
if self.movie_id:
self.client.get(f"{API}/movie/{self.movie_id}", name=f"{API}/movie/[id]")
self.interrupt()
[docs]
class FilteredDiscovery(SequentialTaskSet):
"""Undecided browser: filtered discover → two more pages → details of a hit."""
[docs]
@task
def discover_first_page(self):
"""Run a random filter combination and remember a random hit's id."""
self.filters = random.choice(DISCOVER_FILTERS)
response = self.client.get(
f"{API}/discover/movie",
params={**self.filters, "page": 1},
name=f"{API}/discover/movie",
)
self.movie_id = _pick_result_id(response)
[docs]
@task
def discover_more_pages(self):
"""Page through results 2–3 with the same filters, back-to-back."""
for page in (2, 3):
self.client.get(
f"{API}/discover/movie",
params={**self.filters, "page": page},
name=f"{API}/discover/movie",
)
[docs]
@task
def movie_details(self):
"""
Open the details of the picked discover hit, then end the journey.
:raises locust.exception.InterruptTaskSet: Always, via
``self.interrupt()``.
"""
if self.movie_id:
self.client.get(f"{API}/movie/{self.movie_id}", name=f"{API}/movie/[id]")
self.interrupt()
[docs]
class CastExploration(SequentialTaskSet):
"""Rabbit-hole user: movie details → its credits → a cast member's details."""
[docs]
@task
def movie_details(self):
"""Open a random movie's details (id drawn from movie_ids.txt)."""
self.movie_id = pick_random_movie_id()
self.client.get(f"{API}/movie/{self.movie_id}", name=f"{API}/movie/[id]")
[docs]
@task
def movie_credits(self):
"""Fetch the movie's credits and remember a random cast member's id."""
response = self.client.get(
f"{API}/movie/{self.movie_id}/credits",
name=f"{API}/movie/[id]/credits",
)
self.person_id = _pick_result_id(response, key="cast")
[docs]
@task
def person_details(self):
"""
Open the picked cast member's person details, then end the journey.
:raises locust.exception.InterruptTaskSet: Always, via
``self.interrupt()``.
"""
if self.person_id:
self.client.get(f"{API}/person/{self.person_id}", name=f"{API}/person/[id]")
self.interrupt()
[docs]
class JourneyUser(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.
"""
host = Config.BASE_URL
wait_time = between(1, 3) # seconds of think-time between journey steps
tasks = {
BrowseAndDrillDown: 10,
SearchDriven: 5,
FilteredDiscovery: 3,
CastExploration: 2,
}
[docs]
def on_start(self):
"""Attach auth headers to this user's session once, at spawn time."""
self.client.headers.update(_auth_headers())
[docs]
class MoviesUser(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.
"""
host = Config.BASE_URL
wait_time = between(1, 3) # seconds of think-time between each user's tasks
[docs]
def on_start(self):
"""Attach auth headers to this user's session once, at spawn time."""
self.client.headers.update(_auth_headers())
[docs]
@task(3)
def movie_details(self):
"""Fetch details of a random movie (weight 3: the dominant request)."""
# Random ids from tests/data/movie_ids.txt bust server-side caches;
# `name=` groups all of them under one row in the stats table.
self.client.get(
f"{API}/movie/{pick_random_movie_id()}",
name=f"{API}/movie/[id]",
)
[docs]
@task(2)
def popular_movies(self):
"""
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.
"""
with self.client.get(
f"{API}/movie/popular",
params={"page": 1},
catch_response=True,
) as response:
if response.ok and not response.json().get("results"):
response.failure("200 OK but 'results' is missing or empty")
[docs]
@task(1)
def top_rated_movies(self):
"""Fetch page 1 of top-rated movies."""
self.client.get(f"{API}/movie/top_rated", params={"page": 1})
[docs]
@task(1)
def alternative_titles(self):
"""Fetch alternative titles for the fixed ``Config.MOVIE_ID`` movie."""
self.client.get(
f"{API}/movie/{Config.MOVIE_ID}/alternative_titles",
name=f"{API}/movie/[id]/alternative_titles",
)