@suiflex/suitest-mcp 0.1.0

package/python/suitest_lifecycle/blackbox/models.py

@@ -0,0 +1,299 @@
+"""Serializable data model for the blackbox engine.
+
+Everything round-trips through plain JSON (``to_json``/``from_json``) so the
+same discovery artifact feeds Zero's deterministic generator, the MCP tools,
+and (optionally) an LLM as reasoning context. Stdlib-only.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+# --------------------------------------------------------------------------- #
+# DOM elements
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class ElementInfo:
+    """One interactive element as captured from the live DOM.
+
+    Carries every attribute the selector strategy can rank — the element is
+    addressable even when the app has no ``data-testid`` convention at all.
+    """
+
+    tag: str = ""
+    kind: str = ""  # input | button | link | select | textarea | checkbox | radio
+    testid: str = ""  # data-testid | data-cy | data-test (first found)
+    testid_attr: str = ""  # which attribute carried it
+    role: str = ""  # explicit role attr or implicit (button/link/...)
+    aria_label: str = ""
+    label: str = ""  # associated <label> text
+    placeholder: str = ""
+    name: str = ""
+    input_type: str = ""
+    autocomplete: str = ""
+    text: str = ""  # visible text (buttons/links)
+    dom_id: str = ""
+    href: str = ""
+    css: str = ""  # stable-ish css path fallback
+    required: bool = False
+
+    def to_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @staticmethod
+    def from_json(raw: dict[str, Any]) -> ElementInfo:
+        known = {f for f in ElementInfo.__dataclass_fields__}
+        return ElementInfo(**{k: v for k, v in raw.items() if k in known})
+
+
+# --------------------------------------------------------------------------- #
+# Login
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class LoginForm:
+    """Detected login form — locator EXPRESSIONS (Playwright, python) per part."""
+
+    route: str = ""
+    username: str = ""  # locator expression, e.g. page.get_by_label("Email")
+    password: str = ""
+    submit: str = ""
+    remember: str = ""
+    error: str = ""  # error region locator (may be empty until observed)
+
+    def found(self) -> bool:
+        return bool(self.username and self.password and self.submit)
+
+    def to_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @staticmethod
+    def from_json(raw: dict[str, Any]) -> LoginForm:
+        known = {f for f in LoginForm.__dataclass_fields__}
+        return LoginForm(**{k: v for k, v in raw.items() if k in known})
+
+
+# --------------------------------------------------------------------------- #
+# Pages
+# --------------------------------------------------------------------------- #
+
+PAGE_PATTERNS = (
+    "login",
+    "dashboard",
+    "list",
+    "detail",
+    "form",
+    "modal",
+    "empty",
+    "error",
+    "forbidden",
+    "not_found",
+    "blank",
+    "unknown",
+)
+
+
+@dataclass
+class PageInfo:
+    """One crawled route with its digest + evidence pointers."""
+
+    route: str
+    url: str = ""
+    title: str = ""
+    pattern: str = "unknown"  # one of PAGE_PATTERNS
+    protected: bool = False
+    depth: int = 0
+    inputs: list[ElementInfo] = field(default_factory=list)
+    buttons: list[ElementInfo] = field(default_factory=list)
+    links: list[ElementInfo] = field(default_factory=list)
+    nav_routes: list[str] = field(default_factory=list)  # internal hrefs found here
+    testids: list[str] = field(default_factory=list)
+    has_table: bool = False
+    row_locator: str = ""  # repeated-row locator when a list/table was detected
+    has_form: bool = False
+    has_modal: bool = False
+    search_locator: str = ""
+    pagination_locator: str = ""
+    console_errors: list[str] = field(default_factory=list)
+    network_errors: list[str] = field(default_factory=list)
+    screenshot: str = ""  # evidence path
+    blank: bool = False
+    visible_text_sample: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["inputs"] = [e.to_json() for e in self.inputs]
+        d["buttons"] = [e.to_json() for e in self.buttons]
+        d["links"] = [e.to_json() for e in self.links]
+        return d
+
+    @staticmethod
+    def from_json(raw: dict[str, Any]) -> PageInfo:
+        known = {f for f in PageInfo.__dataclass_fields__}
+        data = {k: v for k, v in raw.items() if k in known}
+        for key in ("inputs", "buttons", "links"):
+            data[key] = [ElementInfo.from_json(e) for e in raw.get(key, [])]
+        return PageInfo(**data)
+
+
+# --------------------------------------------------------------------------- #
+# Discovery result (the engine's central artifact)
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class LoginProbe:
+    """Outcome of actually performing the login during discovery."""
+
+    attempted: bool = False
+    success: bool = False
+    landed_route: str = ""
+    error_locator: str = ""  # observed error region on a failed probe
+    detail: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @staticmethod
+    def from_json(raw: dict[str, Any]) -> LoginProbe:
+        known = {f for f in LoginProbe.__dataclass_fields__}
+        return LoginProbe(**{k: v for k, v in raw.items() if k in known})
+
+
+@dataclass
+class DiscoveryResult:
+    base_url: str = ""
+    login: LoginForm | None = None
+    login_probe: LoginProbe = field(default_factory=LoginProbe)
+    pages: list[PageInfo] = field(default_factory=list)
+    skipped_routes: list[str] = field(default_factory=list)  # safeMode / excluded
+    errors: list[str] = field(default_factory=list)
+
+    def page(self, route: str) -> PageInfo | None:
+        for p in self.pages:
+            if p.route == route:
+                return p
+        return None
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "baseUrl": self.base_url,
+            "login": self.login.to_json() if self.login else None,
+            "loginProbe": self.login_probe.to_json(),
+            "pages": [p.to_json() for p in self.pages],
+            "skippedRoutes": self.skipped_routes,
+            "errors": self.errors,
+        }
+
+    @staticmethod
+    def from_json(raw: dict[str, Any]) -> DiscoveryResult:
+        return DiscoveryResult(
+            base_url=str(raw.get("baseUrl", "")),
+            login=LoginForm.from_json(raw["login"]) if raw.get("login") else None,
+            login_probe=LoginProbe.from_json(raw.get("loginProbe", {})),
+            pages=[PageInfo.from_json(p) for p in raw.get("pages", [])],
+            skipped_routes=list(raw.get("skippedRoutes", [])),
+            errors=list(raw.get("errors", [])),
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Config (suitest.config.json "ui" section)
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class BlackboxAuth:
+    strategy: str = "form"
+    login_url: str = "/login"
+    username: str = ""
+    password: str = ""
+
+
+@dataclass
+class BlackboxCrawl:
+    max_depth: int = 3
+    max_routes: int = 30
+    max_actions_per_page: int = 20
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    safe_mode: bool = True
+    # Validation aid: pretend the app has no data-testid convention so the
+    # heuristic tiers (role/label/placeholder/name/text) get exercised.
+    ignore_testids: bool = False
+
+
+@dataclass
+class BlackboxSelectors:
+    """Optional manual overrides — locator expressions or raw CSS."""
+
+    login_username: str = ""
+    login_password: str = ""
+    login_submit: str = ""
+
+
+@dataclass
+class BlackboxTestGeneration:
+    include_smoke: bool = True
+    include_auth: bool = True
+    include_navigation: bool = True
+    include_forms: bool = True
+    include_tables: bool = True
+    allow_mutation: bool = False
+
+
+@dataclass
+class BlackboxUiConfig:
+    mode: str = "blackbox"
+    target_url: str = ""
+    auth: BlackboxAuth = field(default_factory=BlackboxAuth)
+    crawl: BlackboxCrawl = field(default_factory=BlackboxCrawl)
+    selectors: BlackboxSelectors = field(default_factory=BlackboxSelectors)
+    test_generation: BlackboxTestGeneration = field(default_factory=BlackboxTestGeneration)
+    headed: bool = False
+    record_video: bool = True
+
+    @staticmethod
+    def from_raw(raw: dict[str, Any]) -> BlackboxUiConfig:
+        auth = raw.get("auth") or {}
+        crawl = raw.get("crawl") or {}
+        selectors = raw.get("selectors") or {}
+        gen = raw.get("testGeneration") or {}
+        return BlackboxUiConfig(
+            mode=str(raw.get("mode", "blackbox")),
+            target_url=str(raw.get("targetUrl", "")).rstrip("/"),
+            auth=BlackboxAuth(
+                strategy=str(auth.get("strategy", "form")),
+                login_url=str(auth.get("loginUrl", "/login")),
+                username=str(auth.get("username", "")),
+                password=str(auth.get("password", "")),
+            ),
+            crawl=BlackboxCrawl(
+                max_depth=int(crawl.get("maxDepth", 3)),
+                max_routes=int(crawl.get("maxRoutes", 30)),
+                max_actions_per_page=int(crawl.get("maxActionsPerPage", 20)),
+                include=[str(x) for x in crawl.get("include", [])],
+                exclude=[str(x) for x in crawl.get("exclude", [])],
+                safe_mode=bool(crawl.get("safeMode", True)),
+                ignore_testids=bool(crawl.get("ignoreTestIds", False)),
+            ),
+            selectors=BlackboxSelectors(
+                login_username=str(selectors.get("loginUsername", "")),
+                login_password=str(selectors.get("loginPassword", "")),
+                login_submit=str(selectors.get("loginSubmit", "")),
+            ),
+            test_generation=BlackboxTestGeneration(
+                include_smoke=bool(gen.get("includeSmoke", True)),
+                include_auth=bool(gen.get("includeAuth", True)),
+                include_navigation=bool(gen.get("includeNavigation", True)),
+                include_forms=bool(gen.get("includeForms", True)),
+                include_tables=bool(gen.get("includeTables", True)),
+                allow_mutation=bool(gen.get("allowMutation", False)),
+            ),
+            headed=bool(raw.get("headed", False)),
+            record_video=bool(raw.get("recordVideo", True)),
+        )

package/python/suitest_lifecycle/blackbox/prd_ingest.py

@@ -0,0 +1,108 @@
+"""Uploaded-PRD ingestion — markdown in, structured requirements out.
+
+TestSprite-parity flow: the user brings a **markdown** product spec (that is
+the required format); Suitest turns it into a test plan. Parsing here is
+deterministic (stdlib only) — headings become features, bullet lines become
+requirements — so the artifact is stable context for the LLM planner and
+readable on its own in ``prd_ingest.json``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+_HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
+_BULLET = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+(.+?)\s*$")
+
+
+@dataclass
+class PrdSection:
+    heading: str
+    level: int
+    requirements: list[str] = field(default_factory=list)
+    text: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class PrdDocument:
+    title: str = ""
+    source_file: str = ""
+    sections: list[PrdSection] = field(default_factory=list)
+
+    @property
+    def requirements(self) -> list[str]:
+        return [r for s in self.sections for r in s.requirements]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "sourceFile": self.source_file,
+            "sections": [s.to_json() for s in self.sections],
+            "requirementCount": len(self.requirements),
+        }
+
+    def as_prompt_context(self, *, max_chars: int = 12_000) -> str:
+        """Compact PRD rendering for the LLM planner prompt."""
+        lines: list[str] = [f"PRD: {self.title}" if self.title else "PRD"]
+        for s in self.sections:
+            lines.append(f"\n{'#' * max(s.level, 1)} {s.heading}")
+            if s.text:
+                lines.append(s.text)
+            for r in s.requirements:
+                lines.append(f"- {r}")
+        return "\n".join(lines)[:max_chars]
+
+
+def parse_prd_markdown(text: str, *, source_file: str = "") -> PrdDocument:
+    doc = PrdDocument(source_file=source_file)
+    current: PrdSection | None = None
+    prose: list[str] = []
+
+    def flush_prose() -> None:
+        nonlocal prose
+        if current is not None and prose:
+            current.text = " ".join(prose)[:600]
+        prose = []
+
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        m = _HEADING.match(line)
+        if m:
+            flush_prose()
+            level = len(m.group(1))
+            heading = m.group(2).strip()
+            if not doc.title and level == 1:
+                doc.title = heading
+                current = None
+                continue
+            current = PrdSection(heading=heading, level=level)
+            doc.sections.append(current)
+            continue
+        b = _BULLET.match(line)
+        if b and current is not None:
+            current.requirements.append(b.group(1)[:300])
+            continue
+        if line.strip() and current is not None:
+            prose.append(line.strip())
+    flush_prose()
+
+    # PRD with no headings at all → one implicit section from the whole body.
+    if not doc.sections and text.strip():
+        doc.sections.append(PrdSection(heading="Requirements", level=2, text=text.strip()[:600]))
+    return doc
+
+
+def load_prd(path: str | Path) -> PrdDocument:
+    p = Path(path)
+    if p.suffix.lower() not in (".md", ".markdown"):
+        raise ValueError(f"PRD must be a markdown file (.md), got: {p.name}")
+    return parse_prd_markdown(p.read_text(encoding="utf-8"), source_file=str(p))
+
+
+__all__ = ["PrdDocument", "PrdSection", "load_prd", "parse_prd_markdown"]

package/python/suitest_lifecycle/blackbox/reporter.py

@@ -0,0 +1,76 @@
+"""Blackbox reporter — route map, evidence index, bug candidates, summary JSON."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from suitest_lifecycle.blackbox.models import DiscoveryResult
+
+
+def bug_candidates(discovery: DiscoveryResult) -> list[dict[str, Any]]:
+    """Deterministic findings worth a human look — NOT failed tests, DOM smells."""
+    out: list[dict[str, Any]] = []
+    for p in discovery.pages:
+        if p.blank:
+            out.append(
+                {"route": p.route, "kind": "blank_page", "detail": "page rendered no content"}
+            )
+        if p.pattern == "error":
+            out.append(
+                {"route": p.route, "kind": "error_page", "detail": p.visible_text_sample[:160]}
+            )
+        for err in p.console_errors[:5]:
+            out.append({"route": p.route, "kind": "console_error", "detail": err})
+        for err in p.network_errors[:5]:
+            out.append({"route": p.route, "kind": "network_error", "detail": err})
+    if (
+        discovery.login is not None
+        and discovery.login_probe.attempted
+        and not discovery.login_probe.success
+    ):
+        out.append(
+            {
+                "route": discovery.login.route,
+                "kind": "login_failed",
+                "detail": discovery.login_probe.detail,
+            }
+        )
+    return out
+
+
+def summarize(
+    discovery: DiscoveryResult,
+    *,
+    graph: dict[str, Any] | None = None,
+    test_results: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    routes = {p.route: p.pattern for p in discovery.pages}
+    return {
+        "baseUrl": discovery.base_url,
+        "loginDetected": discovery.login is not None,
+        "loginSucceeded": discovery.login_probe.success,
+        "routesDiscovered": len(discovery.pages),
+        "routeMap": routes,
+        "skippedRoutes": discovery.skipped_routes,
+        "screenshots": [p.screenshot for p in discovery.pages if p.screenshot],
+        "consoleErrorPages": [p.route for p in discovery.pages if p.console_errors],
+        "networkErrorPages": [p.route for p in discovery.pages if p.network_errors],
+        "bugCandidates": bug_candidates(discovery),
+        "graphNodes": len(graph["nodes"]) if graph else None,
+        "graphEdges": len(graph["edges"]) if graph else None,
+        "testResults": test_results or [],
+        "engineErrors": discovery.errors,
+    }
+
+
+def write_report(report: dict[str, Any], out_dir: str | Path) -> str:
+    path = Path(out_dir) / "blackbox_report.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+    return str(path)
+
+
+__all__ = ["bug_candidates", "summarize", "write_report"]

package/python/suitest_lifecycle/blackbox/selector.py

@@ -0,0 +1,111 @@
+"""General selector strategy — rank an element's addressing options.
+
+Priority (docs/BLACKBOX_UI_TESTING.md):
+1. data-testid / data-cy / data-test
+2. ARIA role + accessible name
+3. associated label text
+4. placeholder
+5. input type / name / autocomplete
+6. button text / link text
+7. stable CSS path fallback
+8. XPath only when literally nothing else exists (we synthesize one from the
+   CSS path, so in practice tier 7 always wins first)
+
+The output is a **Playwright (python, async) locator expression string** that
+generated tests embed verbatim, e.g. ``page.get_by_label("Email")``. The old
+suitest-example testid convention is therefore just tier 1 — never a
+requirement.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from suitest_lifecycle.blackbox.models import ElementInfo
+
+_IMPLICIT_ROLE = {
+    "button": "button",
+    "a": "link",
+    "select": "combobox",
+    "textarea": "textbox",
+}
+
+
+def _q(value: str) -> str:
+    """Escape a python double-quoted string literal."""
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _role_of(el: ElementInfo) -> str:
+    if el.role:
+        return el.role
+    if el.tag == "input":
+        t = el.input_type.lower()
+        if t in ("submit", "button"):
+            return "button"
+        if t == "checkbox":
+            return "checkbox"
+        if t == "radio":
+            return "radio"
+        return "textbox"
+    return _IMPLICIT_ROLE.get(el.tag, "")
+
+
+def _accessible_name(el: ElementInfo) -> str:
+    return el.aria_label or el.label or el.text.strip()
+
+
+def build_locator(el: ElementInfo, *, ignore_testids: bool = False) -> str:
+    """Best locator expression for ``el`` per the strategy above."""
+    # 1 — test attributes
+    if el.testid and not ignore_testids:
+        if el.testid_attr in ("", "data-testid"):
+            return f'page.get_by_test_id("{_q(el.testid)}")'
+        return f"page.locator('[{el.testid_attr}=\"{_q(el.testid)}\"]')"
+    # 2 — role + accessible name
+    role = _role_of(el)
+    name = _accessible_name(el)
+    if role in ("button", "link", "checkbox", "radio", "combobox") and name:
+        return f'page.get_by_role("{role}", name="{_q(name)}").first'
+    # 3 — label
+    if el.label:
+        return f'page.get_by_label("{_q(el.label)}").first'
+    # 4 — placeholder
+    if el.placeholder:
+        return f'page.get_by_placeholder("{_q(el.placeholder)}").first'
+    # 5 — input name / type / autocomplete
+    if el.tag in ("input", "textarea", "select"):
+        if el.name:
+            return f"page.locator('{el.tag}[name=\"{_q(el.name)}\"]').first"
+        if el.autocomplete:
+            return f"page.locator('{el.tag}[autocomplete=\"{_q(el.autocomplete)}\"]').first"
+        if el.input_type:
+            return f"page.locator('input[type=\"{_q(el.input_type)}\"]').first"
+    # 6 — visible text (buttons / links)
+    if el.text.strip():
+        if role:
+            return f'page.get_by_role("{role}", name="{_q(el.text.strip())}").first'
+        return f'page.get_by_text("{_q(el.text.strip())}", exact=False).first'
+    # 5b — dom id (stable-ish, before raw css)
+    if el.dom_id:
+        return f'page.locator("#{_q(el.dom_id)}")'
+    # 7 — stable CSS path
+    if el.css:
+        return f'page.locator("{_q(el.css)}").first'
+    # 8 — XPath as the absolute last resort
+    return f'page.locator("xpath=//{el.tag or "*"}").first'
+
+
+def describe(el: ElementInfo) -> str:
+    """Short human label for reports/step descriptions."""
+    return (
+        el.label
+        or el.aria_label
+        or el.placeholder
+        or el.text.strip()
+        or el.name
+        or el.testid
+        or el.dom_id
+        or f"<{el.tag}>"
+    )[:60]