@qa-gentic/agents 1.1.2

package/src/qa_stlc_agents/agent_test_case_manager/tools/ado_workitem.py

@@ -0,0 +1,302 @@
+"""
+ado_workitem.py — Azure DevOps Work Item REST API calls for the Test Case Manager.
+
+All functions use get_auth_headers() from auth.py — no credentials in this file.
+
+Public API:
+  fetch_work_item(org_url, project, work_item_id)        -> dict
+  create_test_case(org_url, project, title, steps, ...)  -> dict
+  link_test_cases_to_work_item(org_url, project, wi_id, tc_ids) -> dict
+  get_linked_test_cases(org_url, project, work_item_id)  -> dict
+"""
+from __future__ import annotations
+
+import json
+import xml.etree.ElementTree as ET
+from typing import Dict, List, Optional
+
+import requests
+
+from qa_stlc_agents.shared.auth import get_auth_headers
+
+_API = "7.1"
+
+
+# ---------------------------------------------------------------------------
+# fetch_work_item
+# ---------------------------------------------------------------------------
+
+def fetch_work_item(org_url: str, project: str, work_item_id: int) -> dict:
+    """Fetch a PBI or Bug with all relevant fields and parent feature."""
+    org_url = org_url.rstrip("/")
+    headers = get_auth_headers()
+
+    resp = requests.get(
+        f"{org_url}/{project}/_apis/wit/workitems/{work_item_id}",
+        headers=headers,
+        params={"$expand": "relations", "api-version": _API},
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    fields = data.get("fields", {})
+
+    wi_type = fields.get("System.WorkItemType", "")
+
+    # ── Epic guard — test cases must NEVER be created for Epics ─────────────
+    if wi_type == "Epic":
+        return {
+            "error": "epic_not_supported",
+            "work_item_type": wi_type,
+            "work_item_id": work_item_id,
+            "message": (
+                f"Work item {work_item_id} is an Epic. "
+                "Manual test cases cannot be created or linked to an Epic. "
+                "Test cases in ADO are always scoped to PBIs, Bugs, or Features — "
+                "never to Epics. To generate tests for this Epic, use "
+                "qa-gherkin-generator:fetch_epic_hierarchy to walk its child Features "
+                "and PBIs/Bugs, then call create_and_link_test_cases on each individual "
+                "Feature or PBI/Bug work item ID, not on the Epic itself."
+            ),
+        }
+
+    wi = {
+        "id": data["id"],
+        "type": fields.get("System.WorkItemType", ""),
+        "title": fields.get("System.Title", ""),
+        "description": _strip_html(fields.get("System.Description", "") or ""),
+        "acceptance_criteria": _strip_html(
+            fields.get("Microsoft.VSTS.Common.AcceptanceCriteria", "") or ""
+        ),
+        "repro_steps": _strip_html(
+            fields.get("Microsoft.VSTS.TCM.ReproSteps", "") or ""
+        ),
+        "state": fields.get("System.State", ""),
+        "priority": fields.get("Microsoft.VSTS.Common.Priority", ""),
+        "story_points": fields.get("Microsoft.VSTS.Scheduling.StoryPoints", ""),
+        "tags": fields.get("System.Tags", ""),
+        "assigned_to": (
+            (fields.get("System.AssignedTo") or {}).get("displayName", "")
+        ),
+        "area_path": fields.get("System.AreaPath", ""),
+        "iteration_path": fields.get("System.IterationPath", ""),
+    }
+
+    # Fetch parent feature if present
+    parent_feature = None
+    for rel in data.get("relations", []):
+        if rel.get("rel") == "System.LinkTypes.Hierarchy-Reverse":
+            try:
+                pr = requests.get(
+                    rel["url"] + f"?api-version={_API}",
+                    headers=get_auth_headers(),
+                    timeout=30,
+                )
+                if pr.ok:
+                    pf = pr.json().get("fields", {})
+                    parent_feature = {
+                        "id": pr.json().get("id"),
+                        "type": pf.get("System.WorkItemType", ""),
+                        "title": pf.get("System.Title", ""),
+                    }
+            except Exception:
+                pass
+            break
+
+    # Existing linked test cases count
+    existing_tc_count = sum(
+        1 for r in data.get("relations", [])
+        if r.get("rel") == "Microsoft.VSTS.Common.TestedBy-Forward"
+    )
+
+    # Coverage hints derived from text
+    coverage_hints = _extract_coverage_hints(wi)
+
+    return {
+        "work_item": wi,
+        "parent_feature": parent_feature,
+        "existing_test_cases_count": existing_tc_count,
+        "coverage_hints": coverage_hints,
+    }
+
+
+# ---------------------------------------------------------------------------
+# create_test_case
+# ---------------------------------------------------------------------------
+
+def create_test_case(
+    org_url: str,
+    project: str,
+    title: str,
+    steps: List[Dict],
+    priority: int = 2,
+    area_path: Optional[str] = None,
+    iteration_path: Optional[str] = None,
+) -> dict:
+    """Create a Test Case work item with XML steps in ADO."""
+    org_url = org_url.rstrip("/")
+    headers = get_auth_headers("application/json-patch+json")
+
+    steps_xml = _build_steps_xml(steps)
+
+    patch = [
+        {"op": "add", "path": "/fields/System.Title", "value": title},
+        {"op": "add", "path": "/fields/System.State", "value": "Design"},
+        {"op": "add", "path": "/fields/Microsoft.VSTS.Common.Priority", "value": priority},
+    ]
+    if steps_xml:
+        patch.append({"op": "add", "path": "/fields/Microsoft.VSTS.TCM.Steps", "value": steps_xml})
+    if area_path:
+        patch.append({"op": "add", "path": "/fields/System.AreaPath", "value": area_path})
+    if iteration_path:
+        patch.append({"op": "add", "path": "/fields/System.IterationPath", "value": iteration_path})
+
+    resp = requests.post(
+        f"{org_url}/{project}/_apis/wit/workitems/$Test%20Case",
+        headers=headers,
+        params={"api-version": _API},
+        json=patch,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    created = resp.json()
+    return {
+        "success": True,
+        "test_case_id": created["id"],
+        "title": title,
+        "url": created.get("_links", {}).get("html", {}).get("href", ""),
+    }
+
+
+# ---------------------------------------------------------------------------
+# link_test_cases_to_work_item
+# ---------------------------------------------------------------------------
+
+def link_test_cases_to_work_item(
+    org_url: str,
+    project: str,
+    work_item_id: int,
+    test_case_ids: List[int],
+) -> dict:
+    """Create TestedBy-Forward links from a work item to test cases."""
+    org_url = org_url.rstrip("/")
+    headers = get_auth_headers("application/json-patch+json")
+
+    relations = [
+        {
+            "op": "add",
+            "path": "/relations/-",
+            "value": {
+                "rel": "Microsoft.VSTS.Common.TestedBy-Forward",
+                "url": f"{org_url}/{project}/_apis/wit/workItems/{tc_id}",
+            },
+        }
+        for tc_id in test_case_ids
+    ]
+
+    resp = requests.patch(
+        f"{org_url}/{project}/_apis/wit/workitems/{work_item_id}",
+        headers=headers,
+        params={"api-version": _API},
+        json=relations,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return {
+        "success": True,
+        "work_item_id": work_item_id,
+        "linked_count": len(test_case_ids),
+        "test_case_ids": test_case_ids,
+    }
+
+
+# ---------------------------------------------------------------------------
+# get_linked_test_cases
+# ---------------------------------------------------------------------------
+
+def get_linked_test_cases(org_url: str, project: str, work_item_id: int) -> dict:
+    """Return all test cases linked via TestedBy to a work item."""
+    org_url = org_url.rstrip("/")
+    headers = get_auth_headers()
+
+    resp = requests.get(
+        f"{org_url}/{project}/_apis/wit/workitems/{work_item_id}",
+        headers=headers,
+        params={"$expand": "relations", "api-version": _API},
+        timeout=30,
+    )
+    resp.raise_for_status()
+
+    linked = []
+    for rel in resp.json().get("relations", []):
+        if rel.get("rel") == "Microsoft.VSTS.Common.TestedBy-Forward":
+            tc_id = int(rel["url"].split("/")[-1])
+            try:
+                tc = requests.get(
+                    rel["url"] + f"?api-version={_API}",
+                    headers=get_auth_headers(),
+                    timeout=30,
+                )
+                if tc.ok:
+                    f = tc.json().get("fields", {})
+                    linked.append({
+                        "id": tc_id,
+                        "title": f.get("System.Title", ""),
+                        "state": f.get("System.State", ""),
+                        "priority": f.get("Microsoft.VSTS.Common.Priority", ""),
+                    })
+            except Exception:
+                linked.append({"id": tc_id})
+
+    return {"work_item_id": work_item_id, "linked_test_cases": linked, "count": len(linked)}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _build_steps_xml(steps: List[Dict]) -> str:
+    if not steps:
+        return ""
+
+    def esc(s: str) -> str:
+        return (s or "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")
+
+    inner = "".join(
+        f'<step id="{i+1}" type="ValidateStep">'
+        f'<parameterizedString isformatted="false">{esc(s.get("action",""))}</parameterizedString>'
+        f'<parameterizedString isformatted="false">{esc(s.get("expected_result",""))}</parameterizedString>'
+        f"<description/></step>"
+        for i, s in enumerate(steps)
+    )
+    return f'<steps id="0" last="{len(steps)}">{inner}</steps>'
+
+
+def _strip_html(html: str) -> str:
+    if not html:
+        return ""
+    import re
+    text = re.sub(r"<br\s*/?>", "\n", html, flags=re.IGNORECASE)
+    text = re.sub(r"</p>|</li>|</tr>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"<li[^>]*>", "• ", text, flags=re.IGNORECASE)
+    text = re.sub(r"<[^>]+>", "", text)
+    for old, new in [("&nbsp;", " "), ("&amp;", "&"), ("&lt;", "<"), ("&gt;", ">"), ("&quot;", '"')]:
+        text = text.replace(old, new)
+    return re.sub(r"\n{3,}", "\n\n", text).strip()
+
+
+def _extract_coverage_hints(wi: dict) -> list:
+    text = " ".join([wi.get("description", ""), wi.get("acceptance_criteria", "")]).lower()
+    checks = [
+        (["toast", "notification", "success message", "confirmation"], "toast_notifications"),
+        (["mb", "kb", "size limit", "file size", "maximum size"], "file_size_boundary"),
+        (["display", "shows", "reflects", "after upload", "after save", "updated"], "post_action_state"),
+        (["mobile", "webview", "ios", "android"], "platform_specific"),
+        (["initials", "first name", "last name", "derived", "generated"], "computed_values"),
+        (["refresh", "reload", "re-login", "persist", "retained"], "data_persistence"),
+        (["tab", "keyboard", "accessible", "aria", "wcag", "a11y"], "accessibility"),
+        (["crop", "resize", "zoom", "drag", "rotate"], "image_manipulation"),
+        (["format", "png", "jpg", "jpeg", "webp", "svg"], "file_formats"),
+        (["cancel", "close", "discard", "dismiss"], "cancel_flows"),
+    ]
+    return [hint for keywords, hint in checks if any(kw in text for kw in keywords)]

package/src/qa_stlc_agents/shared/auth.py

@@ -0,0 +1,119 @@
+"""
+auth.py — Authentication for the QA Test Case Manager MCP Agent.
+
+Uses MSAL with a persistent file-based token cache — identical approach to
+the official microsoft/azure-devops-mcp server and the ado-qa-mcp-agent.
+
+Flow:
+  1. Check ~/.msal-cache/msal-cache.json for a cached token.
+     If the browser is already signed into a Microsoft account (via VS Code,
+     az login, or a previous run), the token is loaded silently — no browser
+     prompt appears.
+  2. Only if no valid cached token exists: open browser once for interactive
+     login. Token is written to cache. Browser never opens again until the
+     refresh token expires (~90 days).
+
+The cache path is shared with microsoft/azure-devops-mcp and ado-qa-mcp-agent,
+so signing in via any of those tools means this agent is already authenticated.
+
+Optional env vars:
+  AZURE_TENANT_ID     Pin to a specific Entra tenant (default: "organizations")
+  AZURE_CLIENT_ID     Custom app registration (default: Azure CLI client ID)
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict
+
+# ADO OAuth scope — same as microsoft/azure-devops-mcp
+_ADO_SCOPE = "499b84ac-1321-427f-aa17-267ca6975798/.default"
+
+# Azure CLI public client ID — works without a custom app registration
+_DEFAULT_CLIENT_ID = "04b07795-8ddb-461a-bbee-02f9e1bf7b46"
+
+# Shared cache location with microsoft/azure-devops-mcp
+_CACHE_FILE = Path.home() / ".msal-cache" / "msal-cache.json"
+
+_msal_app = None
+
+
+def get_auth_headers(content_type: str = "application/json") -> Dict[str, str]:
+    """Return HTTP headers with a valid ADO Bearer token."""
+    token = _acquire_token()
+    return {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": content_type,
+        "Accept": "application/json",
+    }
+
+
+def get_signed_in_user() -> str:
+    """Return the display name / UPN of the cached account, or empty string."""
+    try:
+        app, _ = _get_msal_app()
+        accounts = app.get_accounts()
+        if accounts:
+            return accounts[0].get("name") or accounts[0].get("username") or ""
+    except Exception:
+        pass
+    return ""
+
+
+def _get_msal_app():
+    global _msal_app
+    if _msal_app is None:
+        _msal_app = _create_msal_app()
+    return _msal_app
+
+
+def _create_msal_app():
+    import msal  # type: ignore
+
+    client_id = os.getenv("AZURE_CLIENT_ID", _DEFAULT_CLIENT_ID)
+    tenant_id = os.getenv("AZURE_TENANT_ID", "organizations")
+    authority = f"https://login.microsoftonline.com/{tenant_id}"
+
+    cache = msal.SerializableTokenCache()
+    _CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    if _CACHE_FILE.exists():
+        cache.deserialize(_CACHE_FILE.read_text(encoding="utf-8"))
+
+    app = msal.PublicClientApplication(
+        client_id=client_id,
+        authority=authority,
+        token_cache=cache,
+    )
+    return app, cache
+
+
+def _acquire_token() -> str:
+    """
+    1. Try silent acquisition from the shared cache.
+    2. Fall back to acquire_token_interactive (opens browser once).
+    """
+    app, cache = _get_msal_app()
+    scopes = [_ADO_SCOPE]
+
+    accounts = app.get_accounts()
+    if accounts:
+        result = app.acquire_token_silent(scopes, account=accounts[0])
+        if result and "access_token" in result:
+            _persist_cache(cache)
+            return result["access_token"]
+
+    # No cached token — open browser
+    result = app.acquire_token_interactive(scopes=scopes)
+
+    if "access_token" not in result:
+        err = result.get("error_description") or result.get("error") or str(result)
+        raise RuntimeError(f"MSAL authentication failed: {err}")
+
+    _persist_cache(cache)
+    return result["access_token"]
+
+
+def _persist_cache(cache) -> None:
+    if cache.has_state_changed:
+        _CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _CACHE_FILE.write_text(cache.serialize(), encoding="utf-8")