robotframework-locust 1.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. LocustLibrary/__init__.py +143 -0
  2. LocustLibrary/builder.py +169 -0
  3. LocustLibrary/calllog.py +115 -0
  4. LocustLibrary/checks.py +122 -0
  5. LocustLibrary/distributed.py +52 -0
  6. LocustLibrary/feed.py +61 -0
  7. LocustLibrary/k6/__init__.py +1 -0
  8. LocustLibrary/k6/cli.py +66 -0
  9. LocustLibrary/k6/emit.py +69 -0
  10. LocustLibrary/k6/options.py +128 -0
  11. LocustLibrary/k6/profile.py +130 -0
  12. LocustLibrary/k6/robot_files.py +127 -0
  13. LocustLibrary/k6/scan.py +195 -0
  14. LocustLibrary/parsing.py +80 -0
  15. LocustLibrary/reporting.py +108 -0
  16. LocustLibrary/runner.py +135 -0
  17. LocustLibrary/scenario.py +102 -0
  18. LocustLibrary/shape.py +33 -0
  19. LocustLibrary/shared.py +28 -0
  20. LocustLibrary/stats.py +81 -0
  21. LocustLibrary/stoprules.py +93 -0
  22. LocustLibrary/studio/__init__.py +3 -0
  23. LocustLibrary/studio/app.py +170 -0
  24. LocustLibrary/studio/build_tab.py +73 -0
  25. LocustLibrary/studio/fonts/Inter-Medium.ttf +0 -0
  26. LocustLibrary/studio/fonts/Inter-OFL.txt +92 -0
  27. LocustLibrary/studio/fonts/Inter-Regular.ttf +0 -0
  28. LocustLibrary/studio/fonts/Inter-SemiBold.ttf +0 -0
  29. LocustLibrary/studio/fonts/JetBrainsMono-Medium.ttf +0 -0
  30. LocustLibrary/studio/fonts/JetBrainsMono-OFL.txt +93 -0
  31. LocustLibrary/studio/fonts/JetBrainsMono-Regular.ttf +0 -0
  32. LocustLibrary/studio/fonts.py +17 -0
  33. LocustLibrary/studio/live.py +131 -0
  34. LocustLibrary/studio/panels.py +139 -0
  35. LocustLibrary/studio/report_tab.py +50 -0
  36. LocustLibrary/studio/run_tab.py +187 -0
  37. LocustLibrary/studio/sidebar.py +82 -0
  38. LocustLibrary/studio/themes.py +83 -0
  39. LocustLibrary/studio/worker.py +39 -0
  40. LocustLibrary/suiteplan.py +76 -0
  41. LocustLibrary/users.py +153 -0
  42. LocustLibrary/validation.py +55 -0
  43. LocustLibrary/webui.py +32 -0
  44. robotframework_locust-1.0.1.dist-info/METADATA +178 -0
  45. robotframework_locust-1.0.1.dist-info/RECORD +49 -0
  46. robotframework_locust-1.0.1.dist-info/WHEEL +5 -0
  47. robotframework_locust-1.0.1.dist-info/entry_points.txt +3 -0
  48. robotframework_locust-1.0.1.dist-info/licenses/LICENSE +21 -0
  49. robotframework_locust-1.0.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,143 @@
1
+ """Robot Framework library for authoring and running Locust load tests in RF syntax."""
2
+
3
+ import subprocess
4
+ import sys
5
+
6
+ from robot.api import logger
7
+ from robot.api.deco import keyword
8
+
9
+ from .builder import BuildKeywords
10
+ from .calllog import MAX_FAILED, PER_NAME
11
+ from .checks import CheckKeywords
12
+ from .parsing import _parse_seconds, _ratio
13
+ from .runner import run_load_test
14
+ from .scenario import RunConfig, Scenario, Stats
15
+ from .shared import SharedKeywords
16
+
17
+ __version__ = "1.0.1"
18
+
19
+
20
+ class LocustLibrary(BuildKeywords, CheckKeywords, SharedKeywords):
21
+ """LocustLibrary drives load tests through Locust with RF-native syntax."""
22
+
23
+ ROBOT_LIBRARY_SCOPE = "SUITE"
24
+
25
+ def __init__(self, python_path: str = "") -> None:
26
+ """`python_path` is a folder searched for the modules Add Python Task names."""
27
+ if python_path and python_path not in sys.path:
28
+ sys.path.insert(0, python_path)
29
+ self._scenario: Scenario | None = None
30
+ self._scenarios: list[Scenario] = []
31
+ self._default: Scenario | None = None
32
+ self._config: RunConfig | None = None
33
+ self._stats: Stats | None = None
34
+ self._web_proc: subprocess.Popen[bytes] | None = None
35
+ self._dist_master: subprocess.Popen[bytes] | None = None
36
+ self._dist_workers: list[subprocess.Popen[bytes]] | None = None
37
+ self._shared = {}
38
+
39
+ @keyword
40
+ def run_load_test(self, users: int = 10, spawn_rate: float = 1.0,
41
+ run_time: str = "30s", iterations: int = 0,
42
+ max_users: int = 100, stop_on_fail_ratio: str = "0",
43
+ fail_ratio_warmup: str = "10s") -> None:
44
+ """Run the configured load test headless.
45
+
46
+ `iterations` stops every user after that many task runs in total, within `run_time`.
47
+ Stages from Set Load Stages replace `users`, `spawn_rate` and `run_time`.
48
+ A run that would start more than `max_users` users is refused before it starts.
49
+ The log gets a stats table and the first calls of every request name plus the failed ones.
50
+ `stop_on_fail_ratio` (`20%` or `0.2`; 0 is off) stops the run early once the share of
51
+ failed requests passes it after `fail_ratio_warmup`; the reason is logged as a warning.
52
+ """
53
+ if self._scenario is None or self._config is None:
54
+ raise RuntimeError("Call Create Load Test first.")
55
+ self._config.users = users
56
+ self._config.spawn_rate = spawn_rate
57
+ self._config.run_time = run_time
58
+ self._config.iterations = iterations
59
+ self._config.stop_on_fail_ratio = _ratio(stop_on_fail_ratio)
60
+ self._config.fail_ratio_warmup = _parse_seconds(fail_ratio_warmup)
61
+ self._check_ceiling(self._config, max_users)
62
+ self._shared.clear()
63
+ for host in dict.fromkeys(s.host for s in self._scenarios if not s.verify_tls):
64
+ logger.warn(f"TLS verification is off for {host}")
65
+ self._stats = run_load_test(self._scenarios, self._config)
66
+ if self._stats.stopped:
67
+ logger.warn(f"Load test {self._stats.stopped}")
68
+ if self._stats.cpu_busy:
69
+ logger.warn("Load generator CPU went over 90%; response times may be too high")
70
+ self._log_run(self._stats)
71
+ if self._stats.stop_failed:
72
+ raise AssertionError(f"Load test {self._stats.stopped}")
73
+
74
+ @keyword
75
+ def get_user_index(self) -> int:
76
+ """Return the number of the virtual user running this task, unique within the run.
77
+
78
+ Use it for a unique value or a data row per user, such as `${PREFIX}_${index}`.
79
+ """
80
+ from .users import current_user
81
+
82
+ return int(current_user().index)
83
+
84
+ @keyword
85
+ def get_user_iteration(self) -> int:
86
+ """Return how many task runs this virtual user has started, counting this one."""
87
+ from .users import current_user
88
+
89
+ return int(current_user().iteration)
90
+
91
+ def _log_run(self, stats: Stats) -> None:
92
+ from .reporting import stats_table_html
93
+
94
+ logger.info(stats_table_html(stats), html=True)
95
+ for block in stats.calls:
96
+ logger.info(block, html=True)
97
+ if stats.left_out:
98
+ logger.info(f"{stats.left_out} more calls not logged: the log keeps the first "
99
+ f"{PER_NAME} of each request name and up to {MAX_FAILED} failures.")
100
+
101
+ def _check_ceiling(self, config: RunConfig, max_users: int) -> None:
102
+ peak = max((s.users for s in config.stages), default=config.users)
103
+ peak = max(peak, sum(s.fixed_count for s in self._scenarios))
104
+ if peak > max_users:
105
+ raise ValueError(f"{peak} users is over max_users={max_users}; raise it on purpose")
106
+
107
+ @keyword
108
+ def start_locust_web(self, locustfile: str, port: int = 8089) -> None:
109
+ """Start Locust web UI as subprocess."""
110
+ from .webui import start_web_ui, stop_web_ui
111
+
112
+ if self._web_proc is not None:
113
+ stop_web_ui(self._web_proc)
114
+ self._web_proc = start_web_ui(locustfile, port=port)
115
+
116
+ @keyword
117
+ def stop_locust_web(self) -> None:
118
+ """Stop Locust web UI."""
119
+ from .webui import stop_web_ui
120
+
121
+ proc = self._web_proc
122
+ if proc is not None:
123
+ stop_web_ui(proc)
124
+ self._web_proc = None
125
+
126
+ @keyword
127
+ def run_distributed(self, locustfile: str, processes: int = 2) -> None:
128
+ """Run Locust in distributed mode."""
129
+ from .distributed import run_distributed as _run
130
+
131
+ self.stop_distributed()
132
+ self._dist_master, self._dist_workers = _run(
133
+ locustfile, processes=processes
134
+ )
135
+
136
+ @keyword
137
+ def stop_distributed(self) -> None:
138
+ """Stop the master and workers from Run Distributed."""
139
+ from .distributed import stop_distributed as _stop
140
+
141
+ _stop(self._dist_master, self._dist_workers)
142
+ self._dist_master = None
143
+ self._dist_workers = None
@@ -0,0 +1,169 @@
1
+ """Keywords that build the load test: classes, stages, waits and tasks."""
2
+
3
+ from robot.api import logger
4
+ from robot.api.deco import keyword
5
+
6
+ from .parsing import _keyword_name, _parse_seconds, _python_function, _stage, _statuses
7
+ from .scenario import RunConfig, Scenario, Stats, Task
8
+
9
+
10
+ class BuildKeywords:
11
+ """Keywords that fill the scenarios a run starts from."""
12
+
13
+ _scenario: Scenario | None
14
+ _scenarios: list[Scenario]
15
+ _default: Scenario | None
16
+ _config: RunConfig | None
17
+ _stats: Stats | None
18
+
19
+ @keyword
20
+ def create_load_test(self, host: str, verify_tls: bool = True, proxy: str = "",
21
+ allowed_hosts: str = "") -> None:
22
+ """Create a new load test scenario.
23
+
24
+ `verify_tls=False` matches k6 insecureSkipTLSVerify. `proxy` is an http:// proxy URL;
25
+ Locust ignores HTTPS_PROXY, so pass it here.
26
+ `allowed_hosts` is a comma list of host names the test may hit; when it is empty the
27
+ LOCUSTLIBRARY_ALLOWED_HOSTS environment variable is used. A host outside the list is
28
+ refused. With no list at all the host is accepted and one warning is logged.
29
+ """
30
+ from .validation import allowed_hosts as read_allowed
31
+ from .validation import validate_host
32
+
33
+ allowed = read_allowed(allowed_hosts)
34
+ host = validate_host(host, allowed)
35
+ if not allowed:
36
+ logger.warn(f"No allowed hosts set; {host} is not checked against a list")
37
+ self._scenario = Scenario(host=host, verify_tls=verify_tls, proxy=proxy)
38
+ self._scenarios = [self._scenario]
39
+ self._default = self._scenario
40
+ self._config = RunConfig()
41
+ self._stats = None
42
+
43
+ @keyword
44
+ def add_user_class(self, name: str, weight: int = 1, fixed_count: int = 0) -> None:
45
+ """Start a new user class; later tasks and waits belong to it.
46
+
47
+ One class per k6 scenario. `weight` splits the users by ratio,
48
+ `fixed_count` pins an exact number of users.
49
+ """
50
+ if self._scenario is None:
51
+ raise RuntimeError("Call Create Load Test first.")
52
+ current = self._scenario
53
+ self._scenario = Scenario(host=current.host, name=name, weight=weight,
54
+ fixed_count=fixed_count, verify_tls=current.verify_tls,
55
+ proxy=current.proxy)
56
+ # The class Create Load Test made has no tasks yet; Locust refuses a class without tasks.
57
+ if current is self._default and len(self._scenarios) == 1 and not current.tasks:
58
+ self._scenarios = []
59
+ self._scenarios.append(self._scenario)
60
+
61
+ @keyword
62
+ def set_load_stages(self, *stages: str) -> None:
63
+ """Ramp like k6 ramping-vus: each `duration:users` stage, as `2m:20`."""
64
+ if self._config is None:
65
+ raise RuntimeError("Call Create Load Test first.")
66
+ self._config.stages = [_stage(s) for s in stages]
67
+
68
+ @keyword
69
+ def set_wait_time(self, minimum: str, maximum: str) -> None:
70
+ """Set think time between tasks."""
71
+ if self._scenario is None:
72
+ raise RuntimeError("Call Create Load Test first.")
73
+ self._scenario.wait_min = _parse_seconds(minimum)
74
+ self._scenario.wait_max = _parse_seconds(maximum)
75
+
76
+ @keyword
77
+ def set_pacing(self, interval: str) -> None:
78
+ """Start a task run every `interval` per user, whatever the response time.
79
+
80
+ A run that takes longer starts the next one at once. Replaces Set Wait Time for the
81
+ current user class.
82
+ """
83
+ if self._scenario is None:
84
+ raise RuntimeError("Call Create Load Test first.")
85
+ self._scenario.pacing = _parse_seconds(interval)
86
+
87
+ @keyword
88
+ def add_stop_rule(self, rule: str) -> None:
89
+ """Stop the run once `rule` holds for its whole window, like `p95 > 1s for 10s`.
90
+
91
+ Metrics: `pN` (Locust's last 10 s window), `fail` and `rcNNN` (`?` and `*` match a
92
+ digit; share since the last check), `cpu` and `mem` (load machine). End with
93
+ `, stop as passed` to stop without failing; the default fails Run Load Test.
94
+ """
95
+ from .stoprules import parse_rule
96
+
97
+ if self._config is None:
98
+ raise RuntimeError("Call Create Load Test first.")
99
+ self._config.stop_rules.append(parse_rule(rule))
100
+
101
+ @keyword
102
+ def add_get_request(self, name: str, path: str, weight: int = 1,
103
+ expected_status: object = 200,
104
+ headers: dict[str, str] | None = None,
105
+ expected_text: str = "") -> None:
106
+ """Add a GET request task.
107
+
108
+ `expected_status` takes one code, a comma list (`200, 204`) or a list.
109
+ `expected_text` must appear in the response body, or the request counts as failed.
110
+ """
111
+ self._add_http_task(Task(name=name, method="GET", path=path, weight=weight,
112
+ expected=_statuses(expected_status),
113
+ headers=headers or {}, expected_text=expected_text))
114
+
115
+ @keyword
116
+ def add_post_request(self, name: str, path: str, weight: int = 1,
117
+ expected_status: object = 200,
118
+ headers: dict[str, str] | None = None,
119
+ json: object = None, data: object = None,
120
+ expected_text: str = "") -> None:
121
+ """Add a POST request task with a `json` or form `data` body.
122
+
123
+ `expected_text` must appear in the response body, or the request counts as failed.
124
+ """
125
+ self._add_http_task(Task(name=name, method="POST", path=path, weight=weight,
126
+ expected=_statuses(expected_status),
127
+ headers=headers or {}, json=json, body=data,
128
+ expected_text=expected_text))
129
+
130
+ @keyword
131
+ def add_task(self, name: str, keyword: str = "", weight: int = 1) -> None:
132
+ """Add an RF-keyword task."""
133
+ if self._scenario is None:
134
+ raise RuntimeError("Call Create Load Test first.")
135
+ self._scenario.tasks.append(
136
+ Task(name=name, kind="rf", weight=weight, keyword_name=_keyword_name(keyword))
137
+ )
138
+
139
+ @keyword
140
+ def add_python_task(self, name: str, function: str, weight: int = 1) -> None:
141
+ """Add a Python task: `module.function` called with the Locust user.
142
+
143
+ Requests made through `user.client` show as their own stats rows, so a
144
+ multi-step flow (register, read OTP, verify) is measured per request.
145
+ """
146
+ if self._scenario is None:
147
+ raise RuntimeError("Call Create Load Test first.")
148
+ self._scenario.tasks.append(
149
+ Task(name=name, kind="py", weight=weight, function=_python_function(function))
150
+ )
151
+
152
+ @keyword
153
+ def set_on_start(self, keyword_name: str) -> None:
154
+ """Set the on_start keyword name."""
155
+ if self._scenario is None:
156
+ raise RuntimeError("Call Create Load Test first.")
157
+ self._scenario.on_start = _keyword_name(keyword_name)
158
+
159
+ @keyword
160
+ def set_on_stop(self, keyword_name: str) -> None:
161
+ """Set the on_stop keyword name."""
162
+ if self._scenario is None:
163
+ raise RuntimeError("Call Create Load Test first.")
164
+ self._scenario.on_stop = _keyword_name(keyword_name)
165
+
166
+ def _add_http_task(self, task: Task) -> None:
167
+ if self._scenario is None:
168
+ raise RuntimeError("Call Create Load Test first.")
169
+ self._scenario.tasks.append(task)
@@ -0,0 +1,115 @@
1
+ """Request log for a load run, written the way RequestsLibrary logs its calls.
2
+
3
+ A run makes thousands of calls, so the log keeps the first few of each request name and the
4
+ failed ones. Secrets in headers and bodies are masked before anything is kept.
5
+ """
6
+
7
+ import html
8
+ import json
9
+ import time
10
+ from dataclasses import dataclass, field
11
+ from typing import Any
12
+ from urllib.parse import parse_qsl, urlencode
13
+
14
+ PER_NAME = 3
15
+ MAX_FAILED = 50
16
+ _LIMIT = 10000
17
+ _MASK = "***"
18
+ _SECRET_HEADERS = {"authorization", "proxy-authorization", "cookie", "set-cookie"}
19
+ _SECRET_FIELDS = {"password", "client_secret", "access_token", "refresh_token", "id_token", "otp"}
20
+ _PRE = "white-space:pre-wrap;word-break:break-all"
21
+
22
+
23
+ @dataclass
24
+ class CallLog:
25
+ """Collects one HTML block per kept call; listens on Locust's request event."""
26
+
27
+ entries: list[str] = field(default_factory=list)
28
+ left_out: int = 0
29
+ _seen: dict[str, int] = field(default_factory=dict)
30
+ _failed: int = 0
31
+
32
+ def record(self, request_type: str, name: str, response_time: float,
33
+ response: Any = None, exception: Any = None, start_time: float | None = None,
34
+ **_event: Any) -> None:
35
+ if not self._wanted(name, exception is not None):
36
+ self.left_out += 1
37
+ return
38
+ sent = time.localtime(start_time) if start_time is not None else time.localtime()
39
+ call = f"{time.strftime('%H:%M:%S', sent)} {request_type} {name}"
40
+ self.entries.append(_block(call, response_time, response, exception))
41
+
42
+ def _wanted(self, name: str, failed: bool) -> bool:
43
+ seen = self._seen.get(name, 0)
44
+ self._seen[name] = seen + 1
45
+ if seen < PER_NAME:
46
+ return True
47
+ if failed and self._failed < MAX_FAILED:
48
+ self._failed += 1
49
+ return True
50
+ return False
51
+
52
+
53
+ def _block(call: str, response_time: float, response: Any, exception: Any) -> str:
54
+ status = getattr(response, "status_code", "no response")
55
+ summary = f"{call} {status} {response_time:.0f} ms"
56
+ if exception is not None:
57
+ summary += f" FAILED: {exception}"
58
+ text = _exchange(response) if response is not None else "no HTTP response recorded"
59
+ return (f"<details><summary>{html.escape(summary)}</summary>"
60
+ f'<pre style="{_PRE}">{html.escape(text)}</pre></details>')
61
+
62
+
63
+ def _exchange(response: Any) -> str:
64
+ request = response.request
65
+ method = str(request.method).upper()
66
+ return "\n".join([
67
+ f"{method} Request : url={request.url}",
68
+ f"path_url={request.path_url}",
69
+ f"headers={mask_headers(request.headers)}",
70
+ f"body={mask_body(request.body)}",
71
+ "",
72
+ f"{method} Response : url={request.url}",
73
+ f"status={response.status_code}, reason={response.reason}",
74
+ f"headers={mask_headers(response.headers)}",
75
+ f"body={mask_body(response.text)}",
76
+ ])
77
+
78
+
79
+ def mask_headers(headers: Any) -> dict[str, str]:
80
+ return {k: _MASK if k.lower() in _SECRET_HEADERS else v for k, v in dict(headers).items()}
81
+
82
+
83
+ def mask_body(body: Any) -> str:
84
+ if not body:
85
+ return ""
86
+ text = body.decode("utf-8", "replace") if isinstance(body, bytes) else str(body)
87
+ text = _masked_json(text) or _masked_form(text) or text
88
+ if len(text) > _LIMIT:
89
+ text = text[:_LIMIT] + f"... (cut at {_LIMIT} characters)"
90
+ return text
91
+
92
+
93
+ def _masked_json(text: str) -> str:
94
+ try:
95
+ data = json.loads(text)
96
+ except ValueError:
97
+ return ""
98
+ return json.dumps(_mask_value(data), ensure_ascii=False)
99
+
100
+
101
+ def _mask_value(value: Any) -> Any:
102
+ if isinstance(value, dict):
103
+ return {k: _MASK if str(k).lower() in _SECRET_FIELDS else _mask_value(v)
104
+ for k, v in value.items()}
105
+ if isinstance(value, list):
106
+ return [_mask_value(item) for item in value]
107
+ return value
108
+
109
+
110
+ def _masked_form(text: str) -> str:
111
+ try:
112
+ pairs = parse_qsl(text, keep_blank_values=True, strict_parsing=True)
113
+ except ValueError:
114
+ return ""
115
+ return urlencode([(k, _MASK if k.lower() in _SECRET_FIELDS else v) for k, v in pairs], safe="*")
@@ -0,0 +1,122 @@
1
+ """Keywords that read and assert on the stats of the last run."""
2
+
3
+ import html
4
+ from pathlib import Path
5
+
6
+ from robot.api import logger
7
+ from robot.api.deco import keyword
8
+
9
+ from .parsing import _measured_percentile, _parse_seconds
10
+ from .scenario import Stats, StatsRow
11
+
12
+
13
+ def _output_dir() -> str | None:
14
+ """Robot's output folder, so reports land beside log.html; None outside a Robot run."""
15
+ from robot.libraries.BuiltIn import BuiltIn, RobotNotRunningError
16
+
17
+ try:
18
+ return str(BuiltIn().get_variable_value("${OUTPUT DIR}"))
19
+ except RobotNotRunningError:
20
+ return None
21
+
22
+
23
+ class CheckKeywords:
24
+ """Keywords that read the last run's stats and fail on a missed target."""
25
+
26
+ _stats: Stats | None
27
+
28
+ @keyword
29
+ def get_locust_stats(self) -> dict[str, object]:
30
+ """Return parsed stats as a dict."""
31
+ if self._stats is None:
32
+ return {}
33
+ return {"rows": [r.__dict__ for r in self._stats.rows],
34
+ "aggregated": self._stats.aggregated.__dict__ if self._stats.aggregated else None,
35
+ "fail_ratio": self._stats.fail_ratio}
36
+
37
+ @keyword
38
+ def get_aggregated_stats(self) -> dict[str, object]:
39
+ """Return aggregated stats."""
40
+ if self._stats is None or self._stats.aggregated is None:
41
+ return {}
42
+ return self._stats.aggregated.__dict__
43
+
44
+ def _aggregated(self) -> StatsRow:
45
+ stats = self._stats
46
+ if stats is None or stats.aggregated is None:
47
+ raise RuntimeError("No stats available. Run Load Test first.")
48
+ if stats.aggregated.request_count == 0:
49
+ raise RuntimeError("No requests recorded.")
50
+ return stats.aggregated
51
+
52
+ @keyword
53
+ def should_have_no_failures(self) -> None:
54
+ """Fail if any request failed."""
55
+ row = self._aggregated()
56
+ if row.failure_count > 0:
57
+ raise AssertionError(f"Failures: {row.failure_count}")
58
+
59
+ @keyword
60
+ def should_meet_response_time(self, endpoint: str, percentile: str,
61
+ maximum: str) -> None:
62
+ """Assert response time percentile <= maximum."""
63
+ if self._stats is None:
64
+ raise RuntimeError("No stats available. Run Load Test first.")
65
+ if maximum.lower().endswith("ms"):
66
+ max_ms = float(maximum.lower().rstrip("ms"))
67
+ else:
68
+ max_ms = _parse_seconds(maximum) * 1000
69
+ # One name can hold several methods; the slowest one decides.
70
+ targets = [r for r in self._stats.rows if r.name == endpoint]
71
+ if not targets and self._stats.aggregated and endpoint.lower() in ("aggregated", "total", ""):
72
+ targets = [self._stats.aggregated]
73
+ if not targets:
74
+ raise RuntimeError(f"Endpoint not found: {endpoint}")
75
+ actual = max(_measured_percentile(r, percentile) for r in targets)
76
+ if actual > max_ms:
77
+ raise AssertionError(
78
+ f"{endpoint} {percentile}={actual}ms > {max_ms}ms"
79
+ )
80
+
81
+ @keyword
82
+ def should_meet_throughput(self, minimum: str) -> None:
83
+ """Assert RPS >= minimum."""
84
+ row = self._aggregated()
85
+ min_rps = float(minimum)
86
+ if row.rps < min_rps:
87
+ raise AssertionError(f"RPS {row.rps} < {min_rps}")
88
+
89
+ @keyword
90
+ def should_meet_error_rate(self, maximum: str, endpoint: str = "") -> None:
91
+ """Assert error rate <= maximum percent, overall or for one endpoint."""
92
+ rows = self._endpoint_rows(endpoint) if endpoint else [self._aggregated()]
93
+ max_rate = float(maximum.rstrip("%")) / 100.0
94
+ rate = sum(r.failure_count for r in rows) / sum(r.request_count for r in rows)
95
+ if rate > max_rate:
96
+ raise AssertionError(f"{rows[0].name} error rate {rate:.2%} > {max_rate:.2%}")
97
+
98
+ def _endpoint_rows(self, endpoint: str) -> list[StatsRow]:
99
+ # One name can hold several methods; k6 thresholds count them together.
100
+ rows = [r for r in (self._stats.rows if self._stats else []) if r.name == endpoint]
101
+ if not rows:
102
+ raise RuntimeError(f"Endpoint not found: {endpoint}")
103
+ if sum(r.request_count for r in rows) == 0:
104
+ raise RuntimeError("No requests recorded.")
105
+ return rows
106
+
107
+ @keyword
108
+ def export_report(self, base_path: str = "locust") -> str:
109
+ """Write <base>_stats.csv and the Locust HTML report <base>.html beside log.html.
110
+
111
+ The HTML report is linked in the log. Returns the base path.
112
+ """
113
+ if self._stats is None:
114
+ raise RuntimeError("No stats available. Run Load Test first.")
115
+ from .reporting import write_stats_csv
116
+
117
+ base = write_stats_csv(self._stats, base_path, _output_dir())
118
+ if self._stats.report_html:
119
+ Path(base + ".html").write_text(self._stats.report_html, encoding="utf-8")
120
+ name = html.escape(Path(base).name + ".html")
121
+ logger.info(f'Locust report: <a href="{name}">{name}</a>', html=True)
122
+ return base
@@ -0,0 +1,52 @@
1
+ """Distributed worker support."""
2
+
3
+ import subprocess
4
+ import sys
5
+
6
+ from .validation import validate_locustfile
7
+
8
+ # Locust binds every interface when these flags are left off.
9
+ _LOOPBACK = "127.0.0.1"
10
+
11
+
12
+ def run_distributed(
13
+ locustfile: str, processes: int = 2, master_port: int = 5557
14
+ ) -> tuple[subprocess.Popen[bytes], list[subprocess.Popen[bytes]]]:
15
+ """Run Locust in distributed mode (master + workers)."""
16
+ locustfile = validate_locustfile(locustfile)
17
+ master = subprocess.Popen([
18
+ sys.executable, "-m", "locust", "-f", locustfile, "--master",
19
+ "--master-bind-host", _LOOPBACK,
20
+ "--master-bind-port", str(master_port),
21
+ "--web-host", _LOOPBACK,
22
+ ])
23
+ workers: list[subprocess.Popen[bytes]] = []
24
+ for _ in range(processes):
25
+ workers.append(subprocess.Popen([
26
+ sys.executable, "-m", "locust", "-f", locustfile, "--worker",
27
+ "--master-host", _LOOPBACK, "--master-port", str(master_port),
28
+ ]))
29
+ return master, workers
30
+
31
+
32
+ def stop_distributed(
33
+ master: subprocess.Popen[bytes] | None,
34
+ workers: list[subprocess.Popen[bytes]] | None,
35
+ ) -> None:
36
+ """Stop a master and its workers started by run_distributed."""
37
+ procs: list[subprocess.Popen[bytes]] = []
38
+ if master is not None:
39
+ procs.append(master)
40
+ procs.extend(workers or [])
41
+ for proc in procs:
42
+ _stop_one(proc)
43
+
44
+
45
+ def _stop_one(proc: subprocess.Popen[bytes]) -> None:
46
+ if proc.poll() is not None:
47
+ return
48
+ proc.terminate()
49
+ try:
50
+ proc.wait(timeout=10)
51
+ except subprocess.TimeoutExpired:
52
+ proc.kill()
LocustLibrary/feed.py ADDED
@@ -0,0 +1,61 @@
1
+ """Run feed for Studio: Locust's per-second history and the final stats, as JSON lines.
2
+
3
+ Run Load Test writes it when LOCUSTLIBRARY_FEED names a file; Studio reads it during the run.
4
+ """
5
+
6
+ import json
7
+ from dataclasses import asdict
8
+ from datetime import UTC, datetime
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ import gevent
13
+
14
+ from .scenario import Stats
15
+ from .stats import _stats_from_env
16
+
17
+ ENV = "LOCUSTLIBRARY_FEED"
18
+
19
+
20
+ def snapshot(local: Any) -> dict[str, Any]:
21
+ """The values of Locust's report charts right now."""
22
+ total = local.stats.total
23
+ return {"time": datetime.now(UTC).isoformat(), "rps": total.current_rps or 0,
24
+ "fails": total.current_fail_per_sec or 0,
25
+ "p50": total.get_current_response_time_percentile(0.5) or 0,
26
+ "p95": total.get_current_response_time_percentile(0.95) or 0,
27
+ "users": local.user_count or 0, "table": _table(_stats_from_env(local))}
28
+
29
+
30
+ def follow(local: Any, path: str) -> None:
31
+ # Locust's own history samples every few seconds; live charts need one point a second.
32
+ while True:
33
+ if local.state not in ("ready", "stopped"):
34
+ with open(path, "a", encoding="utf-8") as handle:
35
+ handle.write(json.dumps(snapshot(local)) + "\n")
36
+ gevent.sleep(1)
37
+
38
+
39
+ def _table(stats: Stats) -> dict[str, Any]:
40
+ return {"rows": [asdict(row) for row in stats.rows],
41
+ "aggregated": asdict(stats.aggregated) if stats.aggregated else None,
42
+ "fail_ratio": stats.fail_ratio}
43
+
44
+
45
+ def write_final(path: str, stats: Stats) -> None:
46
+ final = _table(stats)
47
+ with open(path, "a", encoding="utf-8") as handle:
48
+ handle.write(json.dumps({"final": final}) + "\n")
49
+
50
+
51
+ def read_new(path: str, offset: int) -> tuple[list[dict[str, Any]], int]:
52
+ """Whole lines written since offset, and the offset after them."""
53
+ file = Path(path)
54
+ if not file.is_file():
55
+ return [], offset
56
+ with file.open("rb") as handle:
57
+ handle.seek(offset)
58
+ chunk = handle.read()
59
+ done = chunk.rfind(b"\n") + 1
60
+ lines = chunk[:done].decode("utf-8").splitlines()
61
+ return [json.loads(line) for line in lines if line.strip()], offset + done
@@ -0,0 +1 @@
1
+ """Convert k6 scripts into Robot Framework suites for LocustLibrary."""