@browserstack/mcp-server 1.5.0-beta.1 → 1.5.0-beta.10

package/capability/loadtesting.capability-index.json

@@ -3,7 +3,7 @@
   "version": "1.0",
   "build_id": "43eba70_2026-09-02T14:26:51Z",
   "loadtesting": {
-    "summary": "Load and performance testing: run k6, JMeter, Gatling and Locust load tests at scale. List and inspect projects and load tests; create, update, start, stop and monitor runs; read run reports, AI insights and historical trends; compare runs; and check VU-hour quota and cost estimates. Test definitions, runs and their results live here. Account plan and billing do not — only VU-hour entitlement is exposed, via quota.",
+    "summary": "Load and performance testing: run k6, JMeter, Gatling and Locust load tests at scale. List and inspect projects and load tests; create, update, start, stop and monitor runs; read run reports, AI insights and historical trends; compare runs; and check VU-hour quota and cost estimates. Test definitions, runs and their results live here. Account plan and billing do not — only VU-hour entitlement is exposed, via quota. There is no capability to delete a load test or schedule recurring runs — for those, point the user to the web dashboard. Each capability returns its full result in one call; reuse a result within a task rather than re-fetching the same data.",
     "base_url": "https://load-api.browserstack.com",
     "auth": {
       "type": "http",
@@ -242,7 +242,8 @@
         "intent": "Show how a project's load-test metrics trend across recent runs — use this for 'is performance getting better or worse across this project?'",
         "guidance": [
           "metrics accepts dotted names or @ aliases; @vitals / @all expand to metric sets.",
-          "windowRuns bounds how many recent runs are aggregated."
+          "windowRuns bounds how many recent runs are aggregated.",
+          "Returns the whole windowed series across metrics in one call — request all needed metrics together; do not call once per metric or re-fetch the same window."
         ],
         "returns": [
           "metrics"
@@ -328,13 +329,20 @@
             "name": "hadSlaBreach",
             "type": "boolean",
             "description": "Filter to runs that did / did not breach SLA."
+          },
+          {
+            "name": "tag",
+            "type": "string",
+            "description": "Filter to runs carrying this tag (a run's own tags, or the tags it inherits from its test when it has none of its own)."
           }
         ],
         "intent": "List the execution history across every load test in a project — newest first, paginated. Use for 'what ran last week in this project?' or to find runs across tests to compare.",
         "guidance": [
           "Returns run metadata only, not metrics — use getLoadTestRunReport for a run's KPIs.",
+          "Each run carries a tags array — its own run-level tags if set (via updateLoadTest with runId), otherwise the tags inherited from its test. Filter with the tag query param.",
           "Page with cursor + limit; nextCursor is opaque.",
-          "For a single test's history use /loadTests/{testId}/runs; for currently-live runs use /loadTests/runs/active."
+          "For a single test's history use /loadTests/{testId}/runs; for currently-live runs use /loadTests/runs/active.",
+          "One call returns the page of run history — reuse it for follow-ups and page with cursor only when more rows are needed; do not re-list the same window."
         ],
         "returns": [
           "runs",
@@ -386,12 +394,18 @@
             "name": "userId",
             "type": "integer",
             "description": "Restrict to runs started by a user."
+          },
+          {
+            "name": "tag",
+            "type": "string",
+            "description": "Filter to runs carrying this tag (a run's own tags, or the tags it inherits from its test when it has none of its own)."
           }
         ],
         "intent": "List load-test runs currently executing — use this for 'what's running right now?' or to find a runId to stop or monitor.",
         "guidance": [
           "Returns non-terminal runs across the account.",
           "runId here is the UUID needed by getLoadTestRunStatus and stopLoadTestRun.",
+          "Each run carries a tags array — its own run-level tags if set, otherwise the tags inherited from its test. Filter with the tag query param.",
           "vuHoursBurnedSoFar reflects consumption at the moment of the call."
         ],
         "returns": [
@@ -437,7 +451,8 @@
         "guidance": [
           "jobId is the run UUID from startLoadTestRun or listLoadTestRuns.",
           "Respect pollAfterSeconds between polls instead of tight-looping.",
-          "slaBreachFlags surfaces threshold breaches as they trip."
+          "slaBreachFlags surfaces threshold breaches as they trip.",
+          "For 'is it done?' / 'how much time is left?', this status call is sufficient — do not fetch the run report to answer a status question."
         ],
         "returns": [
           "status",
@@ -578,14 +593,7 @@
           {
             "name": "errorCategory",
             "type": "string",
-            "values": [
-              "5xx",
-              "4xx",
-              "timeout",
-              "connection",
-              "assertion"
-            ],
-            "description": "Comma-separated error categories to include."
+            "description": "Comma-separated error categories — any combination of: 5xx, 4xx, timeout, connection, assertion (e.g. \"5xx,4xx\")."
           },
           {
             "name": "metrics",
@@ -613,7 +621,9 @@
           "Only valid for a terminal run.",
           "Start with detail=aggregate; escalate to per-txn or full only when you need transaction- or network-level detail — full is large.",
           "groupBy and errorCategory narrow the payload; byteCap hard-caps the response (max 256 KB).",
-          "metrics accepts dotted names or @ aliases; see getLoadTestMetricsManifest for what applies to this test type."
+          "metrics accepts dotted names or @ aliases; see getLoadTestMetricsManifest for what applies to this test type.",
+          "Answer a scoped question with the narrowest slice instead of the whole report: one metric → metrics=; error breakdown → errorCategory= (or slaOnly=true); a time window → sinceIso/untilIso; slowest transaction → detail=per-txn with groupBy=transaction and topN.",
+          "One call with the right params returns everything for that question — do not re-fetch the same run with the same params. Fetch the full report (view=full / detail=full) only when the user explicitly asks for the raw or complete report."
         ],
         "returns": [
           "runId",
@@ -748,7 +758,10 @@
         "guidance": [
           "Read-only despite being a POST — nothing is started.",
           "fitsInQuota / remainingAfterEstimate compare the estimate against current quota.",
-          "For the same check at start time, call startLoadTestRun with dryRun:true."
+          "For the same check at start time, call startLoadTestRun with dryRun:true.",
+          "Always use this for a cost or VU-hour estimate of a hypothetical run — it models ramp-up. Do not compute VU-hours by hand from VUs × duration.",
+          "A protocol (plu) run is billed at a full load-generator pod's capacity (e.g. 1000 VUs for k6), not the VUs it actually uses, and carries a minimum billing floor (5 minutes) — so a small or short plu run can estimate far higher than VUs × duration would suggest. That is expected; report the returned estimatedVuHours as-is rather than second-guessing it as an error.",
+          "The estimate is for the test's OWN type: a browser (blu) run costs about 10x a protocol (plu) run at the same VUs and duration (browser VUs carry a 10x weight). So the number depends heavily on whether the test is plu, blu or hybrid — always state which type the estimate is for. When the user asks about a hypothetical run without fixing the type, do not silently inherit the type of whatever test you priced against: say the type explicitly, and if it is genuinely open, give both the plu and blu figures (they differ ~10x) or ask which they mean."
         ],
         "returns": [
           "estimatedVuHours",
@@ -830,7 +843,8 @@
         "intent": "Compare two completed runs and surface the deltas — use this for 'did this run regress vs the baseline?'",
         "guidance": [
           "baselineRunId and candidateRunId are run UUIDs and must differ; both runs must be terminal.",
-          "regressedOnly + pctChangeMin filter to material regressions; dimensions accepts kpi, transaction, sla."
+          "regressedOnly + pctChangeMin filter to material regressions; dimensions accepts kpi, transaction, sla.",
+          "Use this to compare two runs — it returns per-KPI and per-transaction deltas directly. Do not fetch both run reports and diff them yourself."
         ],
         "returns": [
           "kpiDeltas",
@@ -877,11 +891,17 @@
             "name": "framework",
             "type": "string",
             "required": true,
+            "description": "PLU (protocol) frameworks: k6, jmeter, gatling, locust. BLU (browser) frameworks: playwright, selenium, webdriverio, nightwatch, lcncnightwatch. Must match testType — a PLU framework for testType plu, a BLU framework for testType blu (the backend rejects a mismatched pair).",
             "values": [
               "k6",
               "jmeter",
               "gatling",
-              "locust"
+              "locust",
+              "playwright",
+              "selenium",
+              "webdriverio",
+              "nightwatch",
+              "lcncnightwatch"
             ]
           },
           {
@@ -897,7 +917,7 @@
           {
             "name": "config",
             "type": "object",
-            "description": "Test configuration incl. scriptRef {source: s3|s3_upload|existing_zip_id, value|identifier}, vuRamp, durationSec, loadGeneratorLocations, slaThresholds, envVarKeys, tags. To supply a script from a local file or URL, use the pendingScriptUpload flow, then source='s3'."
+            "description": "Test configuration incl. scriptRef {source: s3|s3_upload|existing_zip_id|sample, value|identifier}, loadProfile (constant|ramping|iterations|throughput), vus, vuRamp, durationSec, iterations, targetRps, maxVus, loadGeneratorLocations, slaThresholds, envVarKeys, tags. See the load-profile guidance for which fields each loadProfile needs (iterations + throughput are PLU-only). To supply a script from a local file or URL, use the pendingScriptUpload flow, then source='s3'. To create a test from the platform's built-in sample (no upload), use scriptRef:{source:'sample'} — for Selenium also pass scriptRef.subType (testng|junit|vanillajava|python|pytest|jest|serenity-cucumber)."
           },
           {
             "name": "children",
@@ -934,7 +954,12 @@
         "guidance": [
           "Provide exactly one of projectId or projectName; projectName creates the project if absent.",
           "Script upload is two-phase: send pendingScriptUpload to get a presigned uploadUrl + s3Key, PUT the file, then call create again with the scriptRef source and s3Key returned in the response's nextStep.",
-          "Pass idempotencyKey so a retried create does not duplicate the test."
+          "To spin up a test from a built-in sample with NO file handling (the dashboard's 'use sample script'), pass scriptRef:{source:'sample'} — the platform's bundled sample for the given framework is used. For Selenium, also pass scriptRef.subType (testng|junit|vanillajava|python|pytest|jest|serenity-cucumber) to pick the binding. testType and framework are still needed; the load profile defaults to constant 1 VU / 30s (see below).",
+          "Pass idempotencyKey so a retried create does not duplicate the test.",
+          "Only THREE things must be known before creating, and each is taken from the user's request when they've stated it — ask ONLY for the ones still missing, and ask about nothing else: (1) testType — plu (protocol / API load), blu (real-browser load) or hybrid (both); (2) framework — k6 / jmeter / gatling / locust for plu, playwright / selenium / webdriverio / nightwatch for blu; (3) the script — a built-in sample (scriptRef:{source:'sample'}; for Selenium also pass scriptRef.subType) OR the user's own script via the pendingScriptUpload flow. Do not guess a framework/testType, but do not re-ask for one the user already gave.",
+          "There is no clone capability. To duplicate a test, getLoadTest the source and copy its full config into this create — vuRamp/vus, durationSec, loadGeneratorLocations and slaThresholds included; nothing is inherited from the source, so anything you omit is dropped.",
+          "Everything BEYOND those three DEFAULTS — do not ask about it; apply the default unless the user explicitly specifies otherwise: loadProfile='constant', config.vus=1, config.durationSec=30, region us-east-1 (omit loadGeneratorLocations so the backend defaults it), and NO advanced features (do not enable log capture, response capture, artifacts, thresholds, etc.). Send config.vus=1 + config.durationSec=30 with no vuRamp for the default constant profile.",
+          "Only when the user explicitly asks for a different load shape, set config.loadProfile: 'ramping' (config.vuRamp: array of {vus, durationSec} stages; ramp up/down is inferred from adjacent VU deltas), 'iterations' (PLU only — config.iterations = fixed run count, plus config.vus), or 'throughput' (PLU and only JMeter/Gatling/locust/k6 — config.targetRps + config.maxVus + config.durationSec). A stage's own 'type' is NOT honored — every stage persists as a hold."
         ],
         "returns": [
           "testId",
@@ -1014,7 +1039,8 @@
         "guidance": [
           "testId is the numeric test id, not a run id.",
           "dryRun:true returns the VU-hour estimate and quota fit without starting anything.",
-          "On success returns runId (UUID) + dashboardLink; poll getLoadTestRunStatus with the runId."
+          "On success returns runId (UUID) + dashboardLink; poll getLoadTestRunStatus with the runId.",
+          "A run without dryRun generates real load and consumes VU-hours. Unless the user has already asked to run it now, dryRun:true first, show the estimate/quota fit and the parameters that will be used (VUs, duration, target), and start the real run only after the user confirms — do not treat your own confirmation as the user's."
         ],
         "returns": [
           "runId",
@@ -1098,12 +1124,19 @@
             "name": "hadSlaBreach",
             "type": "boolean",
             "description": "Only runs that breached an SLA."
+          },
+          {
+            "name": "tag",
+            "type": "string",
+            "description": "Filter to runs carrying this tag (a run's own tags, or the tags it inherits from the test when it has none of its own)."
           }
         ],
         "intent": "List the execution history of a test — use this to find past runs of a specific test or to get a runId.",
         "guidance": [
           "testId is numeric; runId values returned are UUIDs.",
-          "Filter with status / verdict / date range; page with cursor + limit."
+          "Each run carries a tags array — its own run-level tags if set (via updateLoadTest with runId), otherwise the tags inherited from the test. Filter with the tag query param.",
+          "Filter with status / verdict / date range; page with cursor + limit.",
+          "One call returns this test's run history — reuse it and page with cursor when needed; do not re-list the same window."
         ],
         "returns": [
           "runs",
@@ -1185,7 +1218,8 @@
         "intent": "Show how one test's metrics trend across its recent runs — use this for 'is this test getting slower over time?'",
         "guidance": [
           "metrics accepts dotted names or @ aliases; @vitals / @all expand to metric sets.",
-          "windowRuns bounds how many recent runs are aggregated."
+          "windowRuns bounds how many recent runs are aggregated.",
+          "Returns the whole windowed series across metrics in one call — request all needed metrics together; do not call once per metric or re-fetch the same window."
         ],
         "returns": [
           "metrics"
@@ -1295,13 +1329,22 @@
                 "type": "string"
               }
             ]
+          },
+          {
+            "name": "runId",
+            "type": "string",
+            "description": "Tag a specific RUN instead of the test definition. When set, config.tags is applied to that run's own tags (the saved test is NOT changed); only config.tags may accompany runId. Omit it to edit the test."
           }
         ],
-        "intent": "Update an existing load test's name or configuration — use this to change tags, SLA thresholds, script or settings.",
+        "intent": "Update an existing load test's name or configuration — use this to change tags, SLA thresholds, script or settings; also tags a specific run when runId is set.",
         "guidance": [
           "Partial update: send only the fields to change.",
           "Pass ifVersion for optimistic concurrency; a stale value returns 409 VERSION_CONFLICT.",
-          "Script replacement uses the same two-phase pendingScriptUpload flow as create."
+          "Script replacement uses the same two-phase pendingScriptUpload flow as create.",
+          "config is a partial update, but each field it carries REPLACES that field wholesale — it does not merge. tags overwrites the entire tag set; it does not append. To add a tag to a test (or the same tag across several tests), getLoadTest each one first and send the union under config.tags.",
+          "To change the load profile, send config.loadProfile plus that profile's fields (see createLoadTest's load-profile guidance for the four shapes). Switching profiles clears the previous profile's fields — e.g. ramping→throughput empties the stages and drops iterations. iterations and throughput are PLU-only.",
+          "To tag a specific RUN rather than the test, pass runId (a run UUID from listLoadTestRuns) together with config.tags — the tags apply to that one run and the saved test is untouched. A run inherits the test's tags until you set its own; setting run tags overrides (they also replace wholesale, so send the union to add). Omit runId to tag the test itself.",
+          "Tags live on the load test, not on its runs — there is no per-run tagging, so do not touch runs when asked to tag a test. To tag every test in a project, list them with listLoadTests and page through with cursor until hasMore is false, then updateLoadTest each one — do not stop after the first page or a subset."
         ],
         "returns": [
           "testId",
@@ -1344,13 +1387,7 @@
           {
             "name": "include",
             "type": "string",
-            "values": [
-              "config",
-              "thresholds",
-              "tags",
-              "children"
-            ],
-            "description": "Comma-separated sub-resources to expand."
+            "description": "Comma-separated sub-resources to expand — any combination of: config, thresholds, tags, children (e.g. \"config,thresholds\"). Ask for everything you need in ONE call (include=config,thresholds,tags) rather than one request per sub-resource."
           },
           {
             "name": "fields",
@@ -1361,7 +1398,8 @@
         "intent": "Get the full configuration of a single load test — use this to inspect a test's settings, script reference, SLA thresholds and children.",
         "guidance": [
           "testId is numeric (from listLoadTests).",
-          "Use include to expand config / thresholds / tags / children."
+          "Use include to expand config / thresholds / tags / children.",
+          "A single call returns the complete configuration — VU/ramp profile, duration, load-generator regions and SLA thresholds (expand them with include=config,thresholds). Do not call again for the same testId within a task; reuse the result."
         ],
         "returns": [
           "testId",