@browserstack/mcp-server 1.5.0-beta.2 → 1.5.0-beta.20

package/capability/loadtesting.capability-index.json

@@ -11,6 +11,7 @@
     },
     "capabilities": [
       {
+        "name": "getLoadTestPlatformStatus",
         "method": "GET",
         "path": "/api/v1/agent/platform/status",
         "mode": "read",
@@ -41,6 +42,7 @@
         }
       },
       {
+        "name": "listLoadTestProjects",
         "method": "GET",
         "path": "/api/v1/agent/projects",
         "mode": "read",
@@ -70,7 +72,11 @@
         "intent": "List the caller's load-testing projects, most recently active first — use this to find a projectId or answer 'what projects do I have?'",
         "guidance": [
           "projectId from here is required by listLoadTests and createLoadTest.",
-          "Page with cursor + limit; nextCursor is opaque."
+          "To find a project by name, pass search=<name> so the server matches it in one call — do NOT page the whole project list to find one. Paging every project is the single largest source of redundant calls on this surface.",
+          "NEVER call this repeatedly with limit=1: it returns the same first project every time and makes no progress. To find one project use search=<name>; to browse, make ONE call with a larger limit and page with cursor only if the user wants more.",
+          "search is group-scoped and may match projects in more than one project space; when it returns several, disambiguate by the projectId on each row — do not assume the first.",
+          "You already have this turn's results — reuse them; do not re-issue an identical call you already made.",
+          "Only enumerate with cursor + limit when the user actually wants the full list; nextCursor is opaque."
         ],
         "returns": [
           "projects",
@@ -95,6 +101,7 @@
         "max_page_size": 100
       },
       {
+        "name": "listLoadTests",
         "method": "GET",
         "path": "/api/v1/agent/projects/{projectId}/loadTests",
         "mode": "read",
@@ -158,6 +165,8 @@
         "intent": "List the load tests in a project — use this to find a testId or browse tests, optionally filtered by type, framework, tag or recent activity.",
         "guidance": [
           "Resolve projectId via listLoadTestProjects first.",
+          "To find a test by name, pass search=<name> so the server matches it in one call — do not page the whole project and match names yourself. In a large project this is the difference between one call and many.",
+          "If several tests match the name, disambiguate by lastRun / updatedSince — do not guess. A descriptive or auto-generated name (e.g. Automation_lts_*) is a real test, not noise; never silently drop it in favour of one that merely sounds more relevant.",
           "The numeric testId returned here is what getLoadTest and startLoadTestRun need — not a runId.",
           "lastRun summarises the most recent execution when present."
         ],
@@ -187,6 +196,50 @@
         "max_page_size": 100
       },
       {
+        "name": "searchLoadTests",
+        "method": "GET",
+        "path": "/api/v1/agent/loadTests/search",
+        "mode": "read",
+        "entity": "loadTest",
+        "query": [
+          {
+            "name": "name",
+            "type": "string",
+            "description": "Test name to search for (substring match, case-insensitive); required."
+          },
+          {
+            "name": "limit",
+            "type": "integer",
+            "description": "Max items to return (1-100, default 50)."
+          }
+        ],
+        "intent": "Find a load test by name across ALL of the caller's projects — use this to resolve a named test to a testId without knowing which project it is in.",
+        "guidance": [
+          "Group-scoped: unlike listLoadTests it needs no projectId. Prefer it to resolve a named test in one call instead of paging every project.",
+          "Each row carries testId, projectId, name, testType and framework — disambiguate same-named tests in different projects by projectId.",
+          "Returns one row per test (its latest version); the numeric testId is what getLoadTest and startLoadTestRun need."
+        ],
+        "returns": [
+          "tests",
+          "hasMore"
+        ],
+        "responses": {
+          "200": {
+            "$response": "Success"
+          },
+          "400": {
+            "$response": "BadRequest"
+          },
+          "401": {
+            "$response": "Unauthorized"
+          },
+          "500": {
+            "$response": "InternalServerError"
+          }
+        }
+      },
+      {
+        "name": "getLoadTestProjectTrends",
         "method": "GET",
         "path": "/api/v1/agent/projects/{projectId}/trends",
         "mode": "read",
@@ -267,6 +320,7 @@
         }
       },
       {
+        "name": "listProjectLoadTestRuns",
         "method": "GET",
         "path": "/api/v1/agent/projects/{projectId}/runs",
         "mode": "read",
@@ -329,11 +383,17 @@
             "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.",
           "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."
@@ -364,6 +424,7 @@
         "max_page_size": 100
       },
       {
+        "name": "listActiveLoadTestRuns",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/runs/active",
         "mode": "read",
@@ -388,12 +449,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": [
@@ -415,6 +482,7 @@
         }
       },
       {
+        "name": "getLoadTestRunStatus",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/runs/{jobId}/status",
         "mode": "read",
@@ -468,6 +536,7 @@
         }
       },
       {
+        "name": "getLoadTestInsightSummary",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/runs/{jobId}/insights",
         "mode": "read",
@@ -516,15 +585,16 @@
           "404": {
             "$response": "NotFound"
           },
-          "503": {
-            "$response": "ServiceUnavailable"
-          },
           "500": {
             "$response": "InternalServerError"
+          },
+          "503": {
+            "$response": "ServiceUnavailable"
           }
         }
       },
       {
+        "name": "getLoadTestRunReport",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/runs/{jobId}/report",
         "mode": "read",
@@ -581,14 +651,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",
@@ -651,6 +714,7 @@
         }
       },
       {
+        "name": "stopLoadTestRun",
         "method": "POST",
         "path": "/api/v1/agent/loadTests/runs/{jobId}/stop",
         "mode": "write",
@@ -692,6 +756,7 @@
         }
       },
       {
+        "name": "getLoadTestQuota",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/quota",
         "mode": "read",
@@ -722,6 +787,7 @@
         }
       },
       {
+        "name": "estimateLoadTestRunCost",
         "method": "POST",
         "path": "/api/v1/agent/loadTests/estimate",
         "mode": "read",
@@ -754,7 +820,9 @@
           "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.",
-          "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."
+          "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",
@@ -780,6 +848,7 @@
         }
       },
       {
+        "name": "compareLoadTestRuns",
         "method": "POST",
         "path": "/api/v1/agent/loadTests/compare",
         "mode": "read",
@@ -859,6 +928,7 @@
         }
       },
       {
+        "name": "createLoadTest",
         "method": "POST",
         "path": "/api/v1/agent/loadTests",
         "mode": "write",
@@ -874,6 +944,7 @@
             "name": "testType",
             "type": "string",
             "required": true,
+            "description": "plu = protocol/API load; blu = real-browser load; hybrid = BOTH in one test (one PLU leg + one BLU leg, supplied via children). These tokens are INTERNAL wire values — send them here but never show them to the user; the user-facing labels are 'API / Protocol' (plu), 'Browser' (blu) and 'Hybrid' (hybrid). All three are valid, user-selectable options — hybrid is not a rare/advanced variant, offer it alongside the other two.",
             "values": [
               "plu",
               "blu",
@@ -884,11 +955,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"
             ]
           },
           {
@@ -904,12 +981,12 @@
           {
             "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",
             "type": "array",
-            "description": "Child scenarios for hybrid tests."
+            "description": "Child scenarios for a hybrid test. A hybrid is exactly one PLU (protocol) leg + one BLU (browser) leg — each leg carries its own framework + scriptRef (a sample or an uploaded script). Send the BLU leg as the top-level testType='blu'/framework/config and put the PLU leg in children[] (one entry, testType='plu' with its framework + config.scriptRef). The backend requires exactly one PLU and one BLU leg and rejects any other composition."
           },
           {
             "name": "idempotencyKey",
@@ -939,9 +1016,17 @@
         ],
         "intent": "Create a new load test in a project — use this to define a test before running it. JSON body only (no multipart).",
         "guidance": [
+          "PRECONDITION — do NOT call this endpoint until THREE things are known: (1) testType (plu/blu/hybrid), (2) framework, (3) the script (a built-in sample or the user's own upload). These are MANDATORY and NOT defaultable — never infer or default them. If the user's request does not state one of the three, ASK the user for the missing ones and WAIT for their answer before creating. 'create a test' with no type/framework/script named means all three are missing → ask all three; do not silently pick k6/plu/sample. Only vus, duration, region and load profile are defaultable (see the DEFAULTS line) — the three above are not.",
+          "'plu' / 'blu' / 'hybrid' are INTERNAL wire values — send them in the request, but NEVER show them to the user. Do not print them in questions, option labels, confirmations, summaries, or prose (no 'Browser (BLU)', no '(plu+blu)'). User-facing labels are: plu → 'API / Protocol', blu → 'Browser', hybrid → 'Hybrid (both API and Browser)'. Frameworks (k6, jmeter, selenium, playwright, …) are real product names and ARE shown to the user.",
+          "When you ASK the user to pick testType or framework, present the FULL, exact option set — never drop, merge, or cross-contaminate options. testType: offer all THREE, using the user-facing labels above — 'API / Protocol', 'Browser', and 'Hybrid'; do not omit Hybrid. framework (ask AFTER testType is chosen, and show only that type's frameworks, each as its OWN separate option): for an API/Protocol test offer exactly k6, jmeter, gatling AND locust (all four — do not drop locust); for a Browser test offer exactly playwright, selenium, webdriverio AND nightwatch (all four — never list the API/Protocol frameworks under a Browser test, and never merge selenium and playwright into one option). For a Hybrid test, collect an API/Protocol leg (its framework + script) AND a Browser leg (its framework + script) and assemble them per the children field — Hybrid needs both legs, so it takes more than the three questions a single-type test does.",
           "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.",
+          "DEFAULTS apply ONLY after the three mandatory fields (testType, framework, script) are known — they never substitute for a missing one of those. Everything BEYOND those three — 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",
@@ -966,6 +1051,7 @@
         }
       },
       {
+        "name": "startLoadTestRun",
         "method": "POST",
         "path": "/api/v1/agent/loadTests/{testId}/runs",
         "mode": "write",
@@ -1021,7 +1107,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",
@@ -1049,6 +1136,7 @@
         }
       },
       {
+        "name": "listLoadTestRuns",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/{testId}/runs",
         "mode": "read",
@@ -1105,12 +1193,20 @@
             "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.",
+          "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.",
+          "To find a run by date, pass sinceIso/untilIso to narrow server-side — do not list the full history and scan it yourself. To compare two dated runs, make one narrowed call per date rather than one broad listing.",
+          "If a date resolves to more than one run, ask the user which; do not assume the first or the latest.",
           "One call returns this test's run history — reuse it and page with cursor when needed; do not re-list the same window."
         ],
         "returns": [
@@ -1139,6 +1235,7 @@
         "max_page_size": 100
       },
       {
+        "name": "getLoadTestHistoricalTrends",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/{testId}/trends",
         "mode": "read",
@@ -1218,6 +1315,7 @@
         }
       },
       {
+        "name": "getLoadTestMetricsManifest",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/{testId}/metricsManifest",
         "mode": "read",
@@ -1258,6 +1356,7 @@
         }
       },
       {
+        "name": "updateLoadTest",
         "method": "PUT",
         "path": "/api/v1/agent/loadTests/{testId}",
         "mode": "write",
@@ -1304,13 +1403,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",
@@ -1338,6 +1446,7 @@
         }
       },
       {
+        "name": "getLoadTest",
         "method": "GET",
         "path": "/api/v1/agent/loadTests/{testId}",
         "mode": "read",
@@ -1353,13 +1462,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",
@@ -1534,6 +1637,7 @@
         ],
         "capabilities": [
           "listLoadTests",
+          "searchLoadTests",
           "getLoadTest",
           "createLoadTest",
           "updateLoadTest"
@@ -1573,7 +1677,8 @@
           "stopLoadTestRun",
           "getLoadTestRunStatus",
           "listLoadTestRuns",
-          "listActiveLoadTestRuns"
+          "listActiveLoadTestRuns",
+          "listProjectLoadTestRuns"
         ]
       },
       "project": {
@@ -1682,7 +1787,8 @@
           }
         ],
         "capabilities": [
-          "getLoadTestHistoricalTrends"
+          "getLoadTestHistoricalTrends",
+          "getLoadTestProjectTrends"
         ]
       },
       "quota": {