@suiflex/suitest-mcp 0.1.0

package/python/suitest_lifecycle/plan_frontend.py

@@ -0,0 +1,252 @@
+"""Deterministic frontend test-plan generator (ZERO tier).
+
+Builds UI test cases from discovered pages: login happy/invalid, protected-route
+redirect, dashboard/list render, create-via-form, search empty state, logout.
+Each case's ``source_ref`` is ``fe:<archetype> <route>`` so the playwright
+exporter can render the right script, and is traceable to a real page route.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from suitest_lifecycle.models import CodeSummary, PlanCase, PlanStep, Priority
+
+if TYPE_CHECKING:
+    from suitest_lifecycle.config import Config
+
+
+def _routes(summary: CodeSummary) -> dict[str, bool]:
+    return {p.route: p.protected for p in summary.pages}
+
+
+def _case(
+    cid: str,
+    title: str,
+    desc: str,
+    category: str,
+    prio: Priority,
+    ref: str,
+    steps: list[tuple[str, str]],
+) -> PlanCase:
+    return PlanCase(
+        id=cid,
+        title=title,
+        description=desc,
+        category=category,
+        priority=prio,
+        source_ref=ref,
+        steps=[PlanStep(type=t, description=d) for t, d in steps],
+    )
+
+
+def generate_frontend_plan(summary: CodeSummary, config: Config) -> list[PlanCase]:
+    routes = _routes(summary)
+    has_login = "/login" in routes
+    protected = [r for r, prot in routes.items() if prot]
+    cases: list[PlanCase] = []
+    n = 0
+
+    def nid() -> str:
+        nonlocal n
+        n += 1
+        return f"TC{n:03d}"
+
+    if has_login:
+        cases.append(
+            _case(
+                nid(),
+                "successful_login_opens_the_dashboard",
+                "Valid credentials log in and land on the dashboard.",
+                "Auth",
+                Priority.HIGH,
+                "fe:login_success /login",
+                [
+                    ("action", "Navigate to /login"),
+                    ("action", "Fill email and password and submit"),
+                    ("assertion", "Dashboard page is visible"),
+                ],
+            )
+        )
+        cases.append(
+            _case(
+                nid(),
+                "invalid_login_shows_an_error",
+                "Wrong credentials keep the user on login with an error.",
+                "Auth",
+                Priority.MEDIUM,
+                "fe:invalid_login /login",
+                [
+                    ("action", "Navigate to /login"),
+                    ("action", "Submit an invalid password"),
+                    ("assertion", "An error message is shown and URL stays /login"),
+                ],
+            )
+        )
+        cases.append(
+            _case(
+                nid(),
+                "login_with_empty_fields_shows_validation_error",
+                "Submitting the login form with empty fields shows a validation error.",
+                "Auth",
+                Priority.MEDIUM,
+                "fe:empty_login /login",
+                [
+                    ("action", "Navigate to /login"),
+                    ("action", "Submit the form with both fields empty"),
+                    ("assertion", "A validation error is shown and URL stays /login"),
+                ],
+            )
+        )
+
+    if protected:
+        target = "/products" if "/products" in routes else protected[0]
+        cases.append(
+            _case(
+                nid(),
+                "protected_route_redirects_anonymous_to_login",
+                f"Visiting {target} unauthenticated redirects to /login.",
+                "Auth",
+                Priority.HIGH,
+                f"fe:protected_redirect {target}",
+                [
+                    ("action", f"Navigate directly to {target} with no session"),
+                    ("assertion", "Login page is shown"),
+                ],
+            )
+        )
+
+    if "/dashboard" in routes:
+        cases.append(
+            _case(
+                nid(),
+                "dashboard_shows_summary_after_login",
+                "After login the dashboard renders its summary cards.",
+                "Dashboard",
+                Priority.MEDIUM,
+                "fe:dashboard_loads /dashboard",
+                [
+                    ("action", "Log in"),
+                    ("assertion", "Dashboard summary is visible"),
+                ],
+            )
+        )
+        if has_login:
+            cases.append(
+                _case(
+                    nid(),
+                    "logout_returns_to_login_and_clears_session",
+                    "Logging out returns to /login and protected routes redirect again.",
+                    "Auth",
+                    Priority.MEDIUM,
+                    "fe:logout /dashboard",
+                    [
+                        ("action", "Log in"),
+                        ("action", "Click the logout button"),
+                        ("assertion", "Login page is shown"),
+                        ("action", "Navigate to /dashboard again"),
+                        ("assertion", "Still on the login page (session cleared)"),
+                    ],
+                )
+            )
+
+    if "/products" in routes:
+        cases.append(
+            _case(
+                nid(),
+                "products_list_loads_after_login",
+                "Authenticated user can open the products list.",
+                "Products",
+                Priority.MEDIUM,
+                "fe:products_list /products",
+                [
+                    ("action", "Log in and go to /products"),
+                    ("assertion", "Products page is visible"),
+                ],
+            )
+        )
+        cases.append(
+            _case(
+                nid(),
+                "search_with_no_match_shows_empty_state",
+                "Searching for a non-existent product shows an empty state.",
+                "Products",
+                Priority.LOW,
+                "fe:search_empty /products",
+                [
+                    ("action", "Log in, open /products, type an unlikely query"),
+                    ("assertion", "Empty state is visible"),
+                ],
+            )
+        )
+        if "/products/new" in routes:
+            cases.append(
+                _case(
+                    nid(),
+                    "search_with_match_filters_the_product_list",
+                    "Searching for an existing product narrows the list to that product.",
+                    "Products",
+                    Priority.MEDIUM,
+                    "fe:search_match /products",
+                    [
+                        ("action", "Log in and create a uniquely-named product"),
+                        ("action", "Open /products and search for that exact name"),
+                        ("assertion", "Exactly the matching product row is shown"),
+                    ],
+                )
+            )
+            cases.append(
+                _case(
+                    nid(),
+                    "delete_product_removes_it_from_the_list",
+                    "Deleting a product removes its row from the list.",
+                    "Products",
+                    Priority.MEDIUM,
+                    "fe:delete_product /products",
+                    [
+                        ("action", "Log in and create a uniquely-named product"),
+                        (
+                            "action",
+                            "Search for it and click its delete button, accepting the confirm",
+                        ),
+                        ("assertion", "The product row disappears from the list"),
+                    ],
+                )
+            )
+
+    if "/products/new" in routes:
+        cases.append(
+            _case(
+                nid(),
+                "create_product_via_form_returns_to_list",
+                "Filling the product form creates a product and returns to the list.",
+                "Products",
+                Priority.HIGH,
+                "fe:create_product /products/new",
+                [
+                    ("action", "Log in and open /products/new"),
+                    ("action", "Fill required fields and submit"),
+                    ("assertion", "Returns to the products list"),
+                ],
+            )
+        )
+        cases.append(
+            _case(
+                nid(),
+                "create_product_with_invalid_data_shows_validation_error",
+                "Submitting the product form with invalid data keeps the user on the form.",
+                "Products",
+                Priority.MEDIUM,
+                "fe:create_invalid /products/new",
+                [
+                    ("action", "Log in and open /products/new"),
+                    ("action", "Fill a too-short name and no SKU, then submit"),
+                    ("assertion", "Form stays visible with validation errors; no navigation"),
+                ],
+            )
+        )
+
+    return cases
+
+
+__all__ = ["generate_frontend_plan"]

package/python/suitest_lifecycle/prd.py

@@ -0,0 +1,92 @@
+"""Build a normalised ``standard_prd`` from static analysis (ZERO tier).
+
+Deterministic: groups endpoints/pages into features and renders human-readable
+user-flows. An LLM enrichment pass (CLOUD/LOCAL tier) can later rewrite the prose
+via ``packages/agent``; this baseline never requires a model.
+"""
+
+from __future__ import annotations
+
+from suitest_lifecycle.models import CodeSummary, Endpoint, Mode, Prd, PrdFeature
+
+
+def _title(slug: str) -> str:
+    return slug.replace("-", " ").replace("_", " ").strip().title() or "Root"
+
+
+def _backend_features(summary: CodeSummary) -> list[PrdFeature]:
+    by_group: dict[str, list[Endpoint]] = {}
+    for ep in summary.endpoints:
+        parts = [
+            p for p in ep.path.strip("/").split("/") if p and not p.startswith(":") and p != "api"
+        ]
+        key = parts[0] if parts else "root"
+        by_group.setdefault(key, []).append(ep)
+
+    features: list[PrdFeature] = []
+    for group, eps in sorted(by_group.items()):
+        flows: list[str] = []
+        for ep in eps:
+            auth = " (auth required)" if ep.auth_required else " (public)"
+            flows.append(f"{ep.method} {ep.path}{auth} -> expected 2xx for valid input")
+        features.append(
+            PrdFeature(
+                name=_title(group),
+                description=f"{group} API surface ({len(eps)} endpoint(s)).",
+                user_flows=flows,
+            )
+        )
+    return features
+
+
+def _frontend_features(summary: CodeSummary) -> list[PrdFeature]:
+    features: list[PrdFeature] = []
+    for page in summary.pages:
+        guard = " (protected)" if page.protected else " (public)"
+        features.append(
+            PrdFeature(
+                name=page.name,
+                description=f"Page at route {page.route}{guard}.",
+                user_flows=[f"Navigate to {page.route} -> page renders without error"],
+            )
+        )
+    return features
+
+
+def build_prd(summary: CodeSummary, date: str, project: str) -> Prd:
+    if summary.mode is Mode.BACKEND:
+        overview = (
+            f"{project} is a {', '.join(summary.tech_stack)} backend exposing "
+            f"{len(summary.endpoints)} HTTP endpoint(s)."
+        )
+        features = _backend_features(summary)
+        goals = [
+            "Every endpoint returns the documented status for valid and invalid input.",
+            "Protected endpoints reject unauthenticated requests with 401.",
+            "Authenticated CRUD flows create, read, update and delete correctly.",
+        ]
+    else:
+        overview = (
+            f"{project} is a {', '.join(summary.tech_stack)} web app with "
+            f"{len(summary.pages)} page route(s)."
+        )
+        features = _frontend_features(summary)
+        goals = [
+            "Users can log in and reach protected pages.",
+            "Protected routes redirect unauthenticated visitors to login.",
+            "Core CRUD UI flows (create/edit/delete) work end to end.",
+        ]
+    if summary.auth_flow:
+        goals.insert(0, summary.auth_flow)
+
+    return Prd(
+        project=project,
+        date=date,
+        prepared_by="Generated by Suitest",
+        product_overview=overview,
+        core_goals=goals,
+        features=features,
+    )
+
+
+__all__ = ["build_prd"]

package/python/suitest_lifecycle/process.py

@@ -0,0 +1,111 @@
+"""Target server process manager.
+
+Spawns the app-under-test (``server.startCommand``) in its own process group so
+the *whole* tree (npm → tsx → node) can be torn down, streams its output to an
+in-memory ring buffer for ready-log detection + failure diagnostics, and stops
+it gracefully (SIGTERM → SIGKILL). POSIX-focused (the dev target is darwin/linux).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shlex
+import signal
+import subprocess
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass
+class ManagedProcess:
+    popen: subprocess.Popen[bytes]
+    _buffer: deque[str]
+    _lock: threading.Lock
+
+    def log_text(self) -> str:
+        with self._lock:
+            return "".join(self._buffer)
+
+    def tail(self, lines: int = 40) -> str:
+        text = self.log_text()
+        return "\n".join(text.splitlines()[-lines:])
+
+    @property
+    def alive(self) -> bool:
+        return self.popen.poll() is None
+
+    @property
+    def returncode(self) -> int | None:
+        return self.popen.poll()
+
+
+class ProcessManager:
+    """Start/stop a single target server."""
+
+    def __init__(self, *, buffer_chars: int = 200_000) -> None:
+        self._proc: ManagedProcess | None = None
+        self._buffer_chars = buffer_chars
+        self._reader: threading.Thread | None = None
+
+    def start(self, command: str, cwd: Path, env: dict[str, str]) -> ManagedProcess:
+        full_env = {**os.environ, **env}
+        buffer: deque[str] = deque()
+        lock = threading.Lock()
+        char_count = {"n": 0}
+
+        popen = subprocess.Popen(
+            shlex.split(command),
+            cwd=str(cwd),
+            env=full_env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,  # own process group for clean teardown
+        )
+        managed = ManagedProcess(popen=popen, _buffer=buffer, _lock=lock)
+
+        def _drain() -> None:
+            stream = popen.stdout
+            if stream is None:
+                return
+            for raw in iter(stream.readline, b""):
+                chunk = raw.decode("utf-8", errors="replace")
+                with lock:
+                    buffer.append(chunk)
+                    char_count["n"] += len(chunk)
+                    while char_count["n"] > self._buffer_chars and buffer:
+                        char_count["n"] -= len(buffer.popleft())
+
+        reader = threading.Thread(target=_drain, daemon=True)
+        reader.start()
+        self._proc = managed
+        self._reader = reader
+        return managed
+
+    def stop(self, grace_sec: int = 5) -> None:
+        if self._proc is None:
+            return
+        popen = self._proc.popen
+        if popen.poll() is None:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.killpg(os.getpgid(popen.pid), signal.SIGTERM)
+            deadline = time.monotonic() + grace_sec
+            while time.monotonic() < deadline and popen.poll() is None:
+                time.sleep(0.1)
+            if popen.poll() is None:
+                with contextlib.suppress(ProcessLookupError, PermissionError):
+                    os.killpg(os.getpgid(popen.pid), signal.SIGKILL)
+        self._proc = None
+
+    @property
+    def current(self) -> ManagedProcess | None:
+        return self._proc
+
+
+__all__ = ["ManagedProcess", "ProcessManager"]

package/python/suitest_lifecycle/publish.py

@@ -0,0 +1,218 @@
+"""Publish lifecycle results into a running Suitest (Approach A — REST ingest).
+
+Builds the bulk-import (cases + steps + source code) and run-ingest (completed
+run + per-step outcomes + video/screenshot artifacts) payloads, then sends them
+via the Suitest SDK. The SDK is imported lazily so the lifecycle core stays
+stdlib-only; if it (or the server) is unavailable, publishing degrades to a
+clean ``{"published": False, "reason": ...}`` instead of failing the run.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from suitest_lifecycle.config import Config
+    from suitest_lifecycle.models import PlanCase, RunSummary
+    from suitest_lifecycle.paths import Paths
+
+
+class Uploader(Protocol):
+    """Minimal upload surface the publisher needs (satisfied by SuitestClient).
+
+    Artifacts go THROUGH the API — the server holds the S3 credentials, so the
+    lifecycle/MCP client needs no ``SUITEST_S3_*`` env of its own.
+    """
+
+    def upload_file(self, path: str, *, content_type: str | None = None) -> str: ...
+
+
+_PRIORITY = {"High": "P1", "Medium": "P2", "Low": "P3"}
+_MIME = {".webm": "video/webm", ".png": "image/png", ".jpg": "image/jpeg"}
+
+# PlanCase.title is the generated test function slug (codegen emits
+# ``test_<title>``), so the publish layer is where the human display title is
+# minted: ``slug`` carries the technical key, ``title`` the readable sentence.
+# Mirrors suitest_shared.text.humanize_slug (lifecycle stays stdlib-only).
+_ACRONYMS = frozenset({"api", "url", "id", "ui", "ux", "http", "sql", "ok", "sso", "mcp"})
+
+
+def _humanize(slug: str) -> str:
+    words = [w for w in slug.replace("_", " ").replace("-", " ").split() if w]
+    if not words:
+        return slug.strip()
+    out: list[str] = []
+    for i, word in enumerate(words):
+        lower = word.lower()
+        if lower in _ACRONYMS:
+            out.append(lower.upper())
+        elif i == 0:
+            out.append(word[:1].upper() + word[1:].lower())
+        else:
+            out.append(lower)
+    return " ".join(out)
+
+
+def _suite_name(config: Config) -> str:
+    return config.publish.suite_name or f"{config.project_name} {config.mode.value}"
+
+
+def _case_payloads(cases: list[PlanCase], paths: Paths) -> list[dict[str, object]]:
+    out: list[dict[str, object]] = []
+    for c in cases:
+        code = ""
+        if c.automation_file:
+            fp = paths.test_file(c.automation_file)
+            if fp.is_file():
+                code = fp.read_text(encoding="utf-8")
+        out.append(
+            {
+                "sourceRef": c.source_ref,
+                # ``name`` stays the slug — it is the server's idempotency match
+                # key for rows published before the title/slug split.
+                "name": c.title,
+                "slug": c.title,
+                "title": _humanize(c.title),
+                "description": c.description,
+                # Lifecycle cases are produced by the MCP-native plan/run loop, so
+                # they surface under the MCP filter (not the generic IMPORT bucket).
+                "source": "MCP",
+                "priority": _PRIORITY.get(c.priority.value, "P2"),
+                "category": c.category,
+                "tags": list(c.tags),
+                "automationFilePath": c.automation_file,
+                "automationCode": code,
+                "generatedBy": "suitest-lifecycle",
+                "steps": [
+                    {
+                        "order": i + 1,
+                        "action": s.description,
+                        # For assertions the description *is* the expectation; for
+                        # actions there's no distinct expected, so leave it blank
+                        # and let the reader derive one.
+                        "expected": s.description if s.type == "assertion" else "",
+                        "code": None,
+                    }
+                    for i, s in enumerate(c.steps)
+                ],
+            }
+        )
+    return out
+
+
+def _resolve_url(client: Uploader, path: str, mime: str) -> str:
+    """Upload the artifact THROUGH the API (server owns the S3 creds) and return
+    the durable ``s3://`` URL. On any upload hiccup fall back to a local
+    ``file://`` URL so publishing never fails on an artifact."""
+    try:
+        return client.upload_file(path, content_type=mime)
+    except Exception:  # never fail publish on an upload hiccup
+        return "file://" + os.path.abspath(path)
+
+
+def _artifact(client: Uploader, path: str, kind: str) -> dict[str, object] | None:
+    if not path or not os.path.isfile(path):
+        return None
+    ext = os.path.splitext(path)[1].lower()
+    mime = _MIME.get(ext, "application/octet-stream")
+    return {
+        "kind": kind,
+        "url": _resolve_url(client, path, mime),
+        "mimeType": mime,
+        "sizeBytes": os.path.getsize(path),
+    }
+
+
+def _result_payloads(
+    client: Uploader, summary: RunSummary, cases: list[PlanCase]
+) -> list[dict[str, object]]:
+    ref_by_id = {c.id: c.source_ref for c in cases}
+    name_by_id = {c.id: c.title for c in cases}
+    out: list[dict[str, object]] = []
+    for r in summary.results:
+        # Case level carries only the VIDEO now; screenshots are per-step (each
+        # run_step gets its own SCREENSHOT), so the "final" one would be redundant.
+        artifacts = [a for a in (_artifact(client, r.video_path, "VIDEO"),) if a is not None]
+        slug = name_by_id.get(r.test_id, r.title)
+        out.append(
+            {
+                "name": slug,
+                "slug": slug,
+                "sourceRef": ref_by_id.get(r.test_id, r.test_id),
+                "outcome": r.status.value,
+                "durationMs": r.duration_ms,
+                "error": r.error,
+                "steps": [
+                    {
+                        "order": s.index,
+                        "type": s.type,
+                        "description": s.description,
+                        "outcome": s.status.value,
+                        # Per-step screenshot, uploaded so the web can sign + show it.
+                        "screenshot": (
+                            _resolve_url(client, s.screenshot_path, "image/png")
+                            if s.screenshot_path and os.path.isfile(s.screenshot_path)
+                            else ""
+                        ),
+                    }
+                    for s in r.steps
+                ],
+                "artifacts": artifacts,
+            }
+        )
+    return out
+
+
+def publish_results(
+    config: Config, summary: RunSummary, cases: list[PlanCase], paths: Paths
+) -> dict[str, object]:
+    if not config.publish.enabled:
+        return {"published": False, "reason": "publish disabled"}
+    if not config.publish.project_id:
+        return {"published": False, "reason": "publish.projectId not set"}
+    try:
+        from suitest_sdk import SuitestAPIError, SuitestClient
+    except ImportError:
+        return {"published": False, "reason": "suiflex-suitest-sdk not installed"}
+
+    suite = _suite_name(config)
+    # Secrets (the API key) and the endpoint can come from the environment so
+    # they stay out of a committed suitest.config.json — the MCP client injects
+    # SUITEST_API_KEY / SUITEST_API_URL. Config values win when both are set.
+    api_url = config.publish.api_url or os.environ.get("SUITEST_API_URL", "")
+    token = config.publish.token or os.environ.get("SUITEST_API_KEY") or None
+    client = SuitestClient(
+        api_url,
+        token=token,
+        workspace_id=config.publish.workspace_id or None,
+        # Video artifacts upload THROUGH the API to remote object storage — the
+        # default 30s regularly times out on multi-MB webm files.
+        timeout=180.0,
+    )
+    try:
+        with client:
+            imported = client.bulk_import_cases(
+                project_id=config.publish.project_id,
+                suite_name=suite,
+                mode=config.mode.value,
+                cases=_case_payloads(cases, paths),
+            )
+            run = client.ingest_run(
+                project_id=config.publish.project_id,
+                suite_name=suite,
+                name=f"{config.project_name} lifecycle",
+                results=_result_payloads(client, summary, cases),
+            )
+    except SuitestAPIError as exc:
+        return {"published": False, "reason": f"api error: {exc}"}
+    except Exception as exc:  # publish must never fail the run (network/SDK errors)
+        return {"published": False, "reason": f"connection error: {type(exc).__name__}: {exc}"}
+    return {
+        "published": True,
+        "runId": run.get("runId") if isinstance(run, dict) else None,
+        "imported": len(imported.get("imported", [])) if isinstance(imported, dict) else 0,
+    }
+
+
+__all__ = ["publish_results"]