managing-suite-assignments

Managing Suite Assignments

Prerequisites

Load checking-devops-prerequisites first — Prerequisites 1–4 AND Prerequisite 5 (stage). You need doce-org-alias, pipelineId, and stageId before proceeding in any mode.

Variable	Description
doce-org-alias	Established in Prerequisite 1
pipelineId	Identified in Prerequisite 4 (pipeline selection)
stageId	Identified in Prerequisite 5 (stage selection)
event	Pre-Promote, Post-Promote, or Review

---

Mode A — Assign a single suite to a stage

Use this mode when a relevant test suite already exists but is not yet linked to a pipeline stage and the user wants to add it as a single one-off assignment.

Additional inputs required:

Variable	Description
testSuiteId	ID of the suite to assign
testSuiteName	Name of the suite (for display in confirmation)

Confirmation gate

Confirmation required before any API call is made.

Present the following prompt to the user and wait for an affirmative response:

"The suite <testSuiteName> is not currently assigned to the <stageName> stage (<event>). Would you like me to assign it now?"

Do not proceed until the user confirms.

On success

Report to the user:

"Suite <testSuiteName> has been assigned to the <stageName> stage (<event>)."

---

Mode B — Map multiple suites to a stage

Use this mode when configuring suite-to-stage mappings across a pipeline or assigning multiple suites to stages as part of a testing strategy.

Additional inputs required:

Input	Description
testSuiteOperations	List of {testSuiteId, action: "add"|"remove"}

MANDATORY IMPACT PREVIEW — Required Before Any Changes

Do not call the API until the user has confirmed the preview below.

Present the full mapping summary and wait for explicit confirmation:

"Here's the suite mapping I'll apply:

Suite	Stage	Event	Action
<suiteName>	<stageName>	<event>	Add
<suiteName2>	<stageName>	<event>	Remove

Confirm to apply all changes?"

Only proceed after the user explicitly confirms.

On success

"Suite mapping applied. <N> suite(s) updated for the <stageName> stage."

---

Mode C — Add/remove test classes in a suite

Use this mode when the user wants to add or remove individual test classes within an existing suite assignment, sync reviewed tests into a suite, or promote tests to a suite.

Additional inputs required:

Input	Source
testSuiteOperations	List of {testSuiteId, action: "add"|"remove"}

Governance rules

• Never call this without explicit approval. AI-reviewed or modified tests must be re-presented to the user before this call is made.
• Rejected tests must be EXCLUDED from the payload — do not include them even if they were previously in the suite.
• If tests were modified during review, re-present the final list of tests before requesting confirmation.

Confirmation gate

REQUIRED — do not skip. Show the user the full list of changes before calling:

"I'm about to sync the following changes to the test suite:

• Add: <testSuiteName1>, <testSuiteName2>
• Remove: <testSuiteName3>
• Stage: <stageName> | Event: <event>

Confirm?"

Only proceed after receiving explicit confirmation.

On success

Confirm to the user:

"Test suite updated successfully for the <stageName> stage."

---

The system call

All three modes use the same endpoint. Substitute all <placeholder> values before executing.

sf api request rest "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testSuiteStages" --method POST --body '{"pipelineStageId":"<stageId>","event":"<event>","assignments":[{"testSuiteId":"<id>","action":"add|remove"}]}' --target-org <doce-org-alias>

Full payload schema:

{
  "pipelineStageId": "<stageId>",
  "event": "<event>",
  "assignments": [
    {"testSuiteId": "<suiteId1>", "action": "add"},
    {"testSuiteId": "<suiteId2>", "action": "remove"}
  ]
}

Error handling

Never expose raw API error messages to the user. Map response status codes to the following user-facing messages:

Status	User-facing message
400	"The request was invalid. Check that all suite and stage IDs are correct and the event type is valid."
403	"You don't have permission to modify suite assignments on this pipeline."
404	"The pipeline or stage was not found."
500	"A server error occurred. Try again in a few minutes."

---

Related skills

• syncing-test-providers — use when the suite you want to assign doesn't appear yet; re-syncing the provider pulls in newly added suites.
• recommending-devops-tests — use when a suite has not yet been identified and you need a recommendation for which suite to assign.
• configuring-quality-gate — use to configure a quality gate on the stage after mapping suites.
• analyzing-test-failures — use for failure analysis and suggested improvements to the tests within a suite.