nat-engine 1__py3-none-any.whl

mannf/product/ingestors/cypress_ingestor.py

@@ -0,0 +1,487 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Cypress test-file ingestor plugin.
+
+Parses Cypress ``.cy.js`` / ``.cy.ts`` test files using regex-based
+extraction (no AST or Node.js runtime required) and converts the discovered
+test actions into :class:`~mannf.product.ingestors.models.IngestedTestCase`
+objects that match the :class:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator`
+task shape.
+
+Supported Cypress patterns
+--------------------------
+* ``describe('suite name', () => { ... })`` / ``context(...)`` — suite blocks
+* ``it('test name', () => { ... })`` / ``specify(...)`` — individual test blocks
+* ``cy.visit('url')`` / ``cy.visit("url")``
+* ``cy.get('selector').type('value')``
+* ``cy.get('selector').clear().type('value')``
+* ``cy.get('selector').click()``
+* ``cy.get('selector').check()`` / ``.uncheck()``
+* ``cy.get('selector').select('value')``
+* ``cy.get('selector').first().click()`` / ``.eq(n).click()``
+* ``cy.contains('text').click()`` / ``cy.contains('selector', 'text').click()``
+* ``cy.url().should('include', '/path')`` / ``('eq', 'url')``
+* ``cy.get('selector').should('be.visible')`` / ``'exist'`` / ``'have.text', '...'``
+* ``cy.intercept('method', 'url').as('alias')`` — captured as metadata
+* ``cy.wait('@alias')`` — captured as wait step
+* ``cy.scrollTo('position')`` / ``cy.get('selector').scrollIntoView()``
+
+The extracted tests are tagged with ``["cypress"]`` and their source
+file reference is set to ``file.cy.ts::<test_name>``.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from mannf.product.ingestors.base import IngestorPlugin
+from mannf.product.ingestors.models import (
+    IngestedTestCase,
+    IngestorSource,
+    IngestResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Regex patterns
+# ---------------------------------------------------------------------------
+
+# it('name', ...) or it("name", ...) or it(`name`, ...)
+# Also matches specify('name', ...)
+# Use \b to avoid matching 'it' inside words like 'visit'
+_RE_IT_BLOCK = re.compile(
+    r"""\b(?:it|specify)\s*\(\s*(['"`])(.*?)\1""",
+    re.DOTALL,
+)
+
+# describe('suite name', ...) or describe("suite name", ...)
+# Also matches context('suite name', ...)
+_RE_DESCRIBE_BLOCK = re.compile(
+    r"""\b(?:describe|context)\s*\(\s*(['"`])(.*?)\1""",
+    re.DOTALL,
+)
+
+# cy.visit('url') / cy.visit("url") / cy.visit(`url`)
+_RE_VISIT = re.compile(
+    r"""cy\.visit\s*\(\s*(['"`])(.*?)\1""",
+)
+
+# cy.get('selector').type('value') — handles optional .clear() before .type()
+_RE_GET_TYPE = re.compile(
+    r"""cy\.get\s*\(\s*(['"`])(.*?)\1\s*\)(?:\.clear\s*\(\s*\))?\.type\s*\(\s*(['"`])(.*?)\3\s*\)""",
+)
+
+# cy.get('selector').click() — supports chained .first() / .eq(n) before .click()
+_RE_GET_CLICK = re.compile(
+    r"""cy\.get\s*\(\s*(['"`])(.*?)\1\s*\)(?:\.(?:first|last)\s*\(\s*\)|\.eq\s*\(\s*\d+\s*\))*\.click\s*\(\s*\)""",
+)
+
+# cy.get('selector').check() or .uncheck()
+_RE_GET_CHECK = re.compile(
+    r"""cy\.get\s*\(\s*(['"`])(.*?)\1\s*\)\.(?:check|uncheck)\s*\(\s*\)""",
+)
+
+# cy.get('selector').select('value')
+_RE_GET_SELECT = re.compile(
+    r"""cy\.get\s*\(\s*(['"`])(.*?)\1\s*\)\.select\s*\(\s*(['"`])(.*?)\3\s*\)""",
+)
+
+# cy.contains('text').click()  — one-argument form
+_RE_CONTAINS_CLICK_1 = re.compile(
+    r"""cy\.contains\s*\(\s*(['"`])(.*?)\1\s*\)\.click\s*\(\s*\)""",
+)
+
+# cy.contains('selector', 'text').click()  — two-argument form
+_RE_CONTAINS_CLICK_2 = re.compile(
+    r"""cy\.contains\s*\(\s*(['"`])(.*?)\1\s*,\s*(['"`])(.*?)\3\s*\)\.click\s*\(\s*\)""",
+)
+
+# cy.url().should('include'|'eq', 'value')
+_RE_URL_SHOULD = re.compile(
+    r"""cy\.url\s*\(\s*\)\.should\s*\(\s*(['"`])(include|eq|contain)\1\s*,\s*(['"`])(.*?)\3\s*\)""",
+)
+
+# cy.get('selector').should('assertion') — single-arg form (e.g., 'be.visible', 'exist', 'not.exist')
+_RE_GET_SHOULD_1 = re.compile(
+    r"""cy\.get\s*\(\s*(['"`])(.*?)\1\s*\)\.should\s*\(\s*(['"`])(.*?)\3\s*\)""",
+)
+
+# cy.get('selector').should('assertion', 'value') — two-arg form (e.g., 'have.text', 'have.value')
+_RE_GET_SHOULD_2 = re.compile(
+    r"""cy\.get\s*\(\s*(['"`])(.*?)\1\s*\)\.should\s*\(\s*(['"`])(.*?)\3\s*,\s*(['"`])(.*?)\5\s*\)""",
+)
+
+# cy.intercept('METHOD', 'url').as('alias')
+_RE_INTERCEPT = re.compile(
+    r"""cy\.intercept\s*\(\s*(['"`])(.*?)\1\s*,\s*(['"`])(.*?)\3\s*\)\.as\s*\(\s*(['"`])(.*?)\5\s*\)""",
+)
+
+# cy.wait('@alias')
+_RE_WAIT = re.compile(
+    r"""cy\.wait\s*\(\s*(['"`])(@\w+)\1\s*\)""",
+)
+
+# cy.scrollTo('position')
+_RE_SCROLL_TO = re.compile(
+    r"""cy\.scrollTo\s*\(\s*(['"`])(.*?)\1\s*\)""",
+)
+
+# cy.get('selector').scrollIntoView()
+_RE_SCROLL_INTO_VIEW = re.compile(
+    r"""cy\.get\s*\(\s*(['"`])(.*?)\1\s*\)\.scrollIntoView\s*\(\s*\)""",
+)
+
+# Priority heuristics
+_HIGH_PRIORITY_KEYWORDS: tuple[str, ...] = (
+    "login", "auth", "register", "checkout", "payment", "critical",
+)
+_NEGATIVE_KEYWORDS: tuple[str, ...] = (
+    "invalid", "error", "fail", "negative", "reject", "wrong",
+)
+
+# Cypress file extensions
+_CYPRESS_EXTENSIONS: frozenset[str] = frozenset(
+    [".cy.js", ".cy.ts", ".cy.jsx", ".cy.tsx"]
+)
+
+# ---------------------------------------------------------------------------
+# Helper — extract test blocks from source
+# ---------------------------------------------------------------------------
+
+
+def _extract_test_blocks(content: str) -> list[tuple[str, str]]:
+    """Return a list of (test_name, test_body) pairs from *content*.
+
+    Uses a brace-counting approach to isolate each ``it('name', ...)`` /
+    ``specify('name', ...)`` block.  The test name is optionally prefixed with
+    the enclosing ``describe`` / ``context`` suite name so that tests from
+    different suites are unambiguous.
+    """
+    results: list[tuple[str, str]] = []
+
+    # Build a list of (start, end, suite_name) for every describe/context block
+    # so we can look up which suite contains each it() call.
+    suite_ranges: list[tuple[int, int, str]] = []
+    for dm in _RE_DESCRIBE_BLOCK.finditer(content):
+        suite_name = dm.group(2)
+        pos = dm.end()
+        brace_pos = content.find("{", pos)
+        if brace_pos == -1:
+            continue
+        depth = 0
+        end_pos = brace_pos
+        for i, ch in enumerate(content[brace_pos:], start=brace_pos):
+            if ch == "{":
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0:
+                    end_pos = i
+                    break
+        suite_ranges.append((dm.start(), end_pos, suite_name))
+
+    for m in _RE_IT_BLOCK.finditer(content):
+        raw_name = m.group(2)
+
+        # Determine the innermost enclosing suite (if any)
+        suite_name: str | None = None
+        for s_start, s_end, s_name in suite_ranges:
+            if s_start <= m.start() <= s_end:
+                suite_name = s_name
+        full_name = f"{suite_name} > {raw_name}" if suite_name else raw_name
+
+        # Find opening '{' of the arrow function body
+        pos = m.end()
+        arrow_match = content.find("=> {", pos)
+        if arrow_match != -1:
+            brace_pos = content.find("{", arrow_match)
+        else:
+            brace_pos = content.find("{", pos)
+        if brace_pos == -1:
+            continue
+        # Brace-count to find the matching '}'
+        depth = 0
+        end_pos = brace_pos
+        for i, ch in enumerate(content[brace_pos:], start=brace_pos):
+            if ch == "{":
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0:
+                    end_pos = i
+                    break
+        body = content[brace_pos : end_pos + 1]
+        results.append((full_name, body))
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Step extractors
+# ---------------------------------------------------------------------------
+
+
+def _extract_steps(body: str) -> list[dict[str, Any]]:
+    """Extract all recognisable Cypress actions from *body* as step dicts."""
+    steps: list[dict[str, Any]] = []
+
+    # cy.visit
+    for m in _RE_VISIT.finditer(body):
+        url = m.group(2)
+        steps.append(
+            {"action": "navigate", "selector": url, "url": url, "_pos": m.start()}
+        )
+
+    # cy.get().type()  (with optional .clear() prefix)
+    for m in _RE_GET_TYPE.finditer(body):
+        steps.append(
+            {"action": "fill", "selector": m.group(2), "value": m.group(4), "_pos": m.start()}
+        )
+
+    # cy.get().click()  (with optional .first()/.eq(n) prefix)
+    for m in _RE_GET_CLICK.finditer(body):
+        steps.append(
+            {"action": "click", "selector": m.group(2), "_pos": m.start()}
+        )
+
+    # cy.get().check() / .uncheck()  → treated as click
+    for m in _RE_GET_CHECK.finditer(body):
+        steps.append(
+            {"action": "click", "selector": m.group(2), "_pos": m.start()}
+        )
+
+    # cy.get().select()  → mapped to fill
+    for m in _RE_GET_SELECT.finditer(body):
+        steps.append(
+            {"action": "fill", "selector": m.group(2), "value": m.group(4), "_pos": m.start()}
+        )
+
+    # cy.contains('selector', 'text').click()  — two-arg form (more specific, match first)
+    for m in _RE_CONTAINS_CLICK_2.finditer(body):
+        steps.append(
+            {"action": "click", "selector": f"text={m.group(4)}", "_pos": m.start()}
+        )
+
+    # cy.contains('text').click()  — one-arg form
+    # Exclude positions already matched by the two-arg form.
+    contains_two_arg_positions = {
+        m.start() for m in _RE_CONTAINS_CLICK_2.finditer(body)
+    }
+    for m in _RE_CONTAINS_CLICK_1.finditer(body):
+        if m.start() not in contains_two_arg_positions:
+            steps.append(
+                {"action": "click", "selector": f"text={m.group(2)}", "_pos": m.start()}
+            )
+
+    # cy.url().should(...)
+    for m in _RE_URL_SHOULD.finditer(body):
+        steps.append(
+            {
+                "action": "assert",
+                "assertion": "url",
+                "value": m.group(4),
+                "_pos": m.start(),
+            }
+        )
+
+    # cy.get().should('assertion', 'value')  — two-arg form (more specific, match first)
+    for m in _RE_GET_SHOULD_2.finditer(body):
+        steps.append(
+            {
+                "action": "assert",
+                "assertion": m.group(4),
+                "selector": m.group(2),
+                "value": m.group(6),
+                "_pos": m.start(),
+            }
+        )
+
+    # cy.get().should('assertion')  — single-arg form
+    # Only emit if this position wasn't already captured by the two-arg form.
+    two_arg_positions = {
+        m.start() for m in _RE_GET_SHOULD_2.finditer(body)
+    }
+    for m in _RE_GET_SHOULD_1.finditer(body):
+        if m.start() not in two_arg_positions:
+            steps.append(
+                {
+                    "action": "assert",
+                    "assertion": m.group(4),
+                    "selector": m.group(2),
+                    "_pos": m.start(),
+                }
+            )
+
+    # cy.intercept().as()  — capture as metadata step
+    for m in _RE_INTERCEPT.finditer(body):
+        steps.append(
+            {
+                "action": "intercept",
+                "method": m.group(2),
+                "url": m.group(4),
+                "alias": m.group(6),
+                "_pos": m.start(),
+            }
+        )
+
+    # cy.wait('@alias')
+    for m in _RE_WAIT.finditer(body):
+        steps.append(
+            {"action": "wait", "alias": m.group(2), "_pos": m.start()}
+        )
+
+    # cy.scrollTo()
+    for m in _RE_SCROLL_TO.finditer(body):
+        steps.append(
+            {"action": "scroll", "position": m.group(2), "_pos": m.start()}
+        )
+
+    # cy.get().scrollIntoView()
+    for m in _RE_SCROLL_INTO_VIEW.finditer(body):
+        steps.append(
+            {"action": "scroll", "selector": m.group(2), "_pos": m.start()}
+        )
+
+    # Sort by position so steps are in source order
+    steps.sort(key=lambda s: s.pop("_pos", 0))
+    return steps
+
+
+# ---------------------------------------------------------------------------
+# Priority / tag inference
+# ---------------------------------------------------------------------------
+
+
+def _infer_priority(name: str) -> str:
+    name_lower = name.lower()
+    if any(kw in name_lower for kw in _HIGH_PRIORITY_KEYWORDS):
+        return "high"
+    if any(kw in name_lower for kw in _NEGATIVE_KEYWORDS):
+        return "medium"
+    return "medium"
+
+
+def _infer_tags(name: str) -> list[str]:
+    tags = ["cypress"]
+    name_lower = name.lower()
+    if any(kw in name_lower for kw in _NEGATIVE_KEYWORDS):
+        tags.append("negative")
+    if any(kw in name_lower for kw in _HIGH_PRIORITY_KEYWORDS):
+        tags.append("smoke")
+    return tags
+
+
+# ---------------------------------------------------------------------------
+# CypressIngestor
+# ---------------------------------------------------------------------------
+
+
+class CypressIngestor(IngestorPlugin):
+    """Ingestor for Cypress ``.cy.js`` / ``.cy.ts`` test files.
+
+    Parses Cypress test files using regex-based extraction and converts
+    ``cy.visit()``, ``cy.get().type()``, ``cy.get().click()``,
+    ``cy.contains()``, ``cy.url().should()``, and similar calls into
+    :class:`~mannf.product.ingestors.models.IngestedTestCase` objects.
+    """
+
+    name = "cypress"
+    display_name = "Cypress Test"
+    description = "Parse Cypress .cy.js/.cy.ts test files into test cases."
+    supported_extensions = [".cy.js", ".cy.ts", ".cy.jsx", ".cy.tsx"]
+    supported_formats = ["cypress"]
+
+    # ------------------------------------------------------------------
+    # IngestorPlugin interface
+    # ------------------------------------------------------------------
+
+    async def ingest(
+        self, source: IngestorSource, config: dict
+    ) -> IngestResult:
+        """Parse the Cypress source and return an :class:`IngestResult`."""
+        try:
+            content = self._read_source(source)
+        except (FileNotFoundError, ValueError) as exc:
+            return self._make_error_result(source, str(exc))
+
+        if not content.strip():
+            return IngestResult(
+                success=True,
+                source=source,
+                warnings=["Cypress source is empty"],
+                stats={"test_case_count": 0},
+            )
+
+        source_name = Path(source.path).name if source.path else "cypress.cy.ts"
+        test_cases = self._parse(content, source_name)
+
+        return IngestResult(
+            success=True,
+            source=source,
+            test_cases=test_cases,
+            stats={"test_case_count": len(test_cases)},
+        )
+
+    def validate_config(self, config: dict) -> list[str]:
+        """No required configuration keys."""
+        return []
+
+    def can_handle(self, source: IngestorSource) -> bool:
+        """Return True for cypress format or matching file extension/content."""
+        if source.format == "cypress":
+            return True
+        if source.path is not None:
+            name = Path(source.path).name.lower()
+            if any(name.endswith(ext) for ext in _CYPRESS_EXTENSIONS):
+                return True
+        if source.raw_content is not None:
+            return (
+                "cy.visit(" in source.raw_content
+                or "cy.get(" in source.raw_content
+                or "cy.contains(" in source.raw_content
+            )
+        return False
+
+    # ------------------------------------------------------------------
+    # Internal parsing
+    # ------------------------------------------------------------------
+
+    def _parse(self, content: str, source_name: str) -> list[IngestedTestCase]:
+        """Extract all test cases from *content*."""
+        test_cases: list[IngestedTestCase] = []
+        seen_names: set[str] = set()
+
+        for name, body in _extract_test_blocks(content):
+            # Deduplicate test names (different describe blocks may use the
+            # same bare it() name; disambiguate with a counter)
+            unique_name = name
+            if unique_name in seen_names:
+                counter = 2
+                while f"{name} ({counter})" in seen_names:
+                    counter += 1
+                unique_name = f"{name} ({counter})"
+            seen_names.add(unique_name)
+
+            steps = _extract_steps(body)
+            priority = _infer_priority(unique_name)
+            tags = _infer_tags(unique_name)
+
+            tc = IngestedTestCase(
+                name=unique_name,
+                description=f"Cypress test: {unique_name}",
+                steps=steps,
+                priority=priority,
+                tags=tags,
+                source_ref=f"{source_name}::{unique_name}",
+                metadata={"source_format": "cypress"},
+            )
+            test_cases.append(tc)
+
+        return test_cases