steppy-dev 0.3.0__py3-none-any.whl

steppy/tours/replay.py

@@ -0,0 +1,234 @@
+"""``ReplayPlan`` → what ``test_scenario.py.j2`` renders as ``test_<slug>__tour``.
+
+The replay is the scenario followed the way a *user* follows its tour, inside
+the scenario's own test file (every selection, parallel, lastfailed and JUnit
+path is keyed on that file):
+
+1. **Setup** — the steps before the tour's start point, in test mode
+   (``only-in: guide`` steps dropped), e.g. login and the entry navigation.
+2. **Start** — the tour, through the overlay's element API.
+3. **Range** — each tour step: assert the popover shows that step anchored on
+   its target → perform the scenario's *own* action for it (the same codegen
+   branch the scenario test uses, captures removed) → make sure the tour moved
+   on. Range steps that are not tour steps run exactly as in the scenario.
+4. **Complete** — ``tour-complete`` fired and no ``tour-error`` did.
+
+Every action body comes from the ``step_body`` template macro, so a replay can
+never drift from the test it mirrors. This module only decides *which* steps,
+in *which* order, with *which* tour checks around them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+from ..models import SteppyConfig, Scenario, Step
+from .model import ReplayEntry, ReplayPlan, ReplayTourStep
+
+#: Actions that act on whatever has focus: clicking the popover's Next button
+#: before them would steal it, so the Next click is deferred past them.
+FOCUS_DEPENDENT_ACTIONS = frozenset({"keyboard", "custom", "call"})
+
+ItemKind = Literal["setup", "plain", "omitted", "start", "tour", "deferred-ensure", "complete"]
+
+
+class ReplayPlanError(ValueError):
+    """The compiler handed over a plan that does not line up with the scenario (a bug)."""
+
+
+@dataclass(frozen=True)
+class ReplayCheck:
+    step_id: str
+    selector: Optional[str]
+    advance: str
+    ensure: Literal["inline", "deferred"] = "inline"
+
+
+@dataclass
+class ReplayItem:
+    kind: ItemKind
+    comment: str = ""
+    step: Optional[Step] = None
+    #: tour items: one (step copy, check) per sub-step (fill-form has several)
+    parts: list[tuple[Step, ReplayCheck]] = field(default_factory=list)
+    step_id: Optional[str] = None  # deferred-ensure
+
+
+@dataclass
+class ReplayRender:
+    function_name: str
+    role: str
+    roles: list[str]
+    auth: bool
+    spec: dict
+    params: list[tuple[str, str]]
+    items: list[ReplayItem]
+
+
+def _copy(step: Step, **update) -> Step:
+    """No captures in a replay; ``only-in`` is resolved statically, layouts/when stay runtime guards."""
+    return step.model_copy(update={"screenshot": None, "only_in": None, **update})
+
+
+def _check(plan: ReplayPlan, scenario: Scenario) -> None:
+    if len(plan.entries) != len(scenario.steps):
+        raise ReplayPlanError(f"{scenario.slug}: {len(plan.entries)} replay entries for {len(scenario.steps)} steps")
+    seen_range = False
+    expected_index = 0
+    for idx, (step, entry) in enumerate(zip(scenario.steps, plan.entries)):
+        if entry.step_number != (step.step_number or idx + 1):
+            raise ReplayPlanError(f"{scenario.slug}: entry {idx} is for step {entry.step_number}")
+        in_setup = idx < plan.start_index
+        if in_setup and seen_range:
+            raise ReplayPlanError(f"{scenario.slug}: setup step {entry.step_number} after the tour started")
+        seen_range = seen_range or not in_setup
+        if entry.disposition == "tour":
+            if in_setup or step.role not in (plan.role, None) or step.only_in == "test":
+                raise ReplayPlanError(f"{scenario.slug}: step {entry.step_number} cannot be a tour step")
+            fields = list(step.fields or {})
+            for ts in entry.tour_steps:
+                if ts.index != expected_index:
+                    raise ReplayPlanError(f"{scenario.slug}: tour step {ts.step_id} is out of order")
+                expected_index += 1
+                if ts.field is not None and ts.field not in fields:
+                    raise ReplayPlanError(f"{scenario.slug}: {ts.field!r} is not a field of step {entry.step_number}")
+    if expected_index != plan.tour_step_count:
+        raise ReplayPlanError(f"{scenario.slug}: {expected_index} tour steps, plan says {plan.tour_step_count}")
+
+
+def _parts(step: Step, entry: ReplayEntry) -> list[tuple[Step, ReplayCheck]]:
+    def check(ts: ReplayTourStep) -> ReplayCheck:
+        return ReplayCheck(ts.step_id, ts.source_selector, ts.advance)
+
+    if step.action == "fill-form" and any(ts.field for ts in entry.tour_steps):
+        parts = []
+        last = len(entry.tour_steps) - 1
+        for n, ts in enumerate(entry.tour_steps):
+            only = {ts.field: step.fields[ts.field]}
+            parts.append(
+                (
+                    _copy(
+                        step,
+                        fields=only,
+                        wait_after=step.wait_after if n == last else None,
+                        expect=step.expect if n == last else None,
+                    ),
+                    check(ts),
+                )
+            )
+        return parts
+    (ts,) = entry.tour_steps
+    return [(_copy(step), check(ts))]
+
+
+def build_replay(scenario: Scenario, plan: ReplayPlan, config: SteppyConfig) -> ReplayRender:
+    _check(plan, scenario)
+    steps = scenario.steps
+    items: list[ReplayItem] = []
+    started = False
+    pending: Optional[tuple[str, Step]] = None  # deferred Next click: (step id, step for its guard)
+
+    def flush_pending():
+        nonlocal pending
+        if pending is not None:
+            step_id, guard_step = pending
+            items.append(ReplayItem("deferred-ensure", step=guard_step, step_id=step_id))
+            pending = None
+
+    for idx, (step, entry) in enumerate(zip(steps, plan.entries)):
+        title = step.step_title or ""
+        if idx < plan.start_index:
+            if entry.disposition == "drop":
+                items.append(ReplayItem("omitted", comment=f"Step {entry.step_number}: {title} — guide-only, skipped"))
+            else:
+                items.append(
+                    ReplayItem("setup", comment=f"Step {entry.step_number}: {title} — setup", step=_copy(step))
+                )
+            continue
+        if not started:
+            route = plan.entry_route or "the current page"
+            items.append(ReplayItem("start", comment=f"Tour '{plan.tour_id}' starts here (entry {route})"))
+            started = True
+        if entry.disposition == "drop":
+            items.append(
+                ReplayItem("omitted", comment=f"Step {entry.step_number}: {title} — test-only, not in the tour")
+            )
+            continue
+        if entry.disposition != "tour":
+            items.append(ReplayItem("plain", comment=f"Step {entry.step_number}: {title}", step=_copy(step)))
+            continue
+        flush_pending()
+        parts = _parts(step, entry)
+        last_step, last_check = parts[-1]
+        if last_check.advance in ("input", "manual") and _focus_dependent_follows(steps, plan.entries, idx):
+            parts[-1] = (
+                last_step,
+                ReplayCheck(last_check.step_id, last_check.selector, last_check.advance, "deferred"),
+            )
+            pending = (last_check.step_id, _copy(step))
+        ids = ", ".join(f"'{c.step_id}'" for _s, c in parts)
+        items.append(
+            ReplayItem(
+                "tour",
+                comment=f"Step {entry.step_number}: {title} — tour step {ids} ({parts[0][1].advance})",
+                step=_copy(step),
+                parts=parts,
+            )
+        )
+    if not started:
+        items.append(ReplayItem("start", comment=f"Tour '{plan.tour_id}' starts here"))
+    flush_pending()
+    items.append(ReplayItem("complete", comment=f"Tour '{plan.tour_id}' must complete"))
+
+    from ..generator import SteppyGenerator
+
+    timeout = SteppyGenerator._resolve_timeout(None, scenario, config)
+    tour_steps = [ts for e in plan.entries for ts in e.tour_steps]
+    spec = {
+        "id": plan.tour_id,
+        "role": plan.role,
+        "default_locale": plan.default_locale,
+        "attribute": plan.test_id_attribute,
+        "timeout_ms": int(timeout),
+        "entry": (
+            {"route": plan.entry_route, "params": [list(p) for p in plan.entry_params]} if plan.entry_route else None
+        ),
+        "layouts": dict(plan.layouts),
+        "steps": [
+            {
+                "id": ts.step_id,
+                "target": ts.target,
+                "wait_for": ts.wait_for,
+                "advance": ts.advance,
+                "layouts": list(ts.layouts) if ts.layouts else None,
+                "scenario_step": e.step_number,
+                "action": steps[i].action,
+                "title": steps[i].step_title or "",
+                "field": ts.field,
+                "selector": ts.source_selector,
+            }
+            for i, e in enumerate(plan.entries)
+            for ts in e.tour_steps
+        ],
+    }
+    assert len(spec["steps"]) == len(tour_steps)
+    slug_ = scenario.slug.replace("-", "_")
+    return ReplayRender(
+        function_name=f"test_{slug_}__tour",
+        role=plan.role,
+        roles=sorted(scenario.get_roles()),
+        auth=scenario.auth,
+        spec=spec,
+        params=list(plan.entry_params),
+        items=items,
+    )
+
+
+def _focus_dependent_follows(steps: list[Step], entries: tuple[ReplayEntry, ...], idx: int) -> bool:
+    for step, entry in zip(steps[idx + 1 :], entries[idx + 1 :]):
+        if entry.disposition == "tour":
+            return False
+        if entry.disposition == "run" and step.action in FOCUS_DEPENDENT_ACTIONS:
+            return True
+    return False

steppy/tours/routes.py

@@ -0,0 +1,175 @@
+"""Entry routes: from a scenario's navigate target to a tour's route pattern.
+
+A tour may declare where it starts (``tour.entry: /invoices/:invoiceId``) or
+inherit it from the scenario's navigation. Either way the stored route is
+**base-relative** — the path *inside* the app, with the app URL's own path
+prefix removed — because the overlay matches it against the document's base
+URL (``<base href>``) and the app's router navigates to it.
+
+Navigate targets are resolved the way the generated tests resolve ``goto()``:
+relative to ``apps.<role>.url``. A ``{{var}}`` segment becomes a ``:var``
+parameter; literal segments are percent-encoded the way ``location.pathname``
+spells them.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+from urllib.parse import quote, unquote, urlsplit
+
+from ..tour_spec import is_dot_segment, is_route
+from .settings import origin_of
+
+#: Segments that look like fixture ids: the tour cannot know them in production.
+ID_LIKE_RE = re.compile(r"\d+|[0-9a-fA-F]{8}-[0-9a-fA-F-]{27}|(?=.*\d)[0-9a-fA-F]{8,}")
+_VAR_SEG = re.compile(r"\{\{\s*([A-Za-z_][A-Za-z0-9_]{0,63})\s*\}\}")
+_PARAM_SEG = re.compile(r":([A-Za-z_][A-Za-z0-9_]{0,63})")
+_SAFE = "._~!$&()*+,;=@-%"
+
+
+@dataclass(frozen=True)
+class AppBase:
+    origin: Optional[str]
+    path: str  # always ends with "/"
+    unresolved: bool = False
+
+
+def app_base(app_url: Optional[str]) -> AppBase:
+    """Origin and path prefix of an app URL; ``unresolved`` when it has no usable host."""
+    if not app_url or "${" in app_url:
+        return AppBase(None, "/", unresolved=True)
+    origin = origin_of(app_url)
+    if origin is None:
+        return AppBase(None, "/", unresolved=True)
+    path = urlsplit(app_url).path or "/"
+    return AppBase(origin, path if path.endswith("/") else path + "/")
+
+
+@dataclass
+class RouteResult:
+    """A route pattern, or the reason there is none, plus non-fatal notes."""
+
+    segments: Optional[list[str]] = None  # pattern segments (":param" or encoded literal)
+    raw_segments: list[str] = field(default_factory=list)  # the target's own segments (for binding)
+    error: Optional[str] = None
+    query_dropped: bool = False
+    id_like: list[str] = field(default_factory=list)
+
+    @property
+    def route(self) -> Optional[str]:
+        if self.segments is None:
+            return None
+        return "/" + "/".join(self.segments)
+
+
+def _target_path(raw: str, base: AppBase) -> tuple[Optional[str], Optional[str], bool]:
+    """``(base-relative path, error, query_dropped)`` for a navigate target."""
+    text = raw.strip()
+    if "#" in text:
+        return None, "hash routes are not supported by in-app tours (v1)", False
+    if re.match(r"^[A-Za-z][A-Za-z0-9+.-]*:", text) or text.startswith("//"):
+        if base.origin is None:
+            return None, "an absolute URL cannot be checked against an unresolved app URL — set tour.entry", False
+        if origin_of(text) != base.origin:
+            return None, f"{text!r} is not on the app's origin ({base.origin}) — a tour cannot navigate there", False
+        parts = urlsplit(text)
+        path, query = parts.path or "/", parts.query
+    else:
+        path, _, query = text.partition("?")
+    if not path.startswith("/"):
+        path = base.path + path
+    if base.path != "/":
+        prefix = base.path.rstrip("/")
+        if path == prefix:
+            path = "/"
+        elif path.startswith(base.path):
+            path = "/" + path[len(base.path) :]
+        else:
+            return None, f"{text!r} is outside the app's base path {base.path}", bool(query)
+    if len(path) > 1 and path.endswith("/"):
+        path = path.rstrip("/") or "/"
+    return path, None, bool(query)
+
+
+def _segments(path: str) -> list[str]:
+    return [] if path == "/" else path.split("/")[1:]
+
+
+def _literal(seg: str) -> Optional[str]:
+    if not seg or is_dot_segment(seg):
+        return None
+    return quote(seg, safe=_SAFE)
+
+
+def route_from_target(raw: str, base: AppBase) -> RouteResult:
+    """Inferred entry: the navigate target as a pattern (``{{var}}`` → ``:var``)."""
+    path, error, query = _target_path(raw, base)
+    if error:
+        return RouteResult(error=error, query_dropped=query)
+    result = RouteResult(query_dropped=query, segments=[])
+    for seg in _segments(path):
+        result.raw_segments.append(seg)
+        var = _VAR_SEG.fullmatch(seg)
+        if var:
+            result.segments.append(":" + var.group(1))
+            continue
+        if "{{" in seg:
+            return RouteResult(error=f"segment {seg!r} is only partly a {{{{var}}}}; make it a whole segment")
+        lit = _literal(seg)
+        if lit is None:
+            return RouteResult(error=f"segment {seg!r} is not a valid path segment")
+        if ID_LIKE_RE.fullmatch(unquote(seg)):
+            result.id_like.append(seg)
+        result.segments.append(lit)
+    if not is_route(result.route):
+        return RouteResult(error=f"{result.route!r} is not a route the in-app player accepts")
+    return result
+
+
+def parse_entry_pattern(text: str) -> RouteResult:
+    """Explicit ``tour.entry``: already base-relative; ``:name`` and ``{{name}}`` are params."""
+    path = text.strip()
+    if len(path) > 1:
+        path = path.rstrip("/") or "/"
+    result = RouteResult(segments=[])
+    for seg in _segments(path):
+        param = _PARAM_SEG.fullmatch(seg) or _VAR_SEG.fullmatch(seg)
+        if param:
+            result.segments.append(":" + param.group(1))
+            continue
+        lit = _literal(seg)
+        if lit is None or "{{" in seg:
+            return RouteResult(error=f"tour.entry segment {seg!r} is not a valid path segment")
+        result.segments.append(lit)
+    if not is_route(result.route):
+        return RouteResult(error=f"tour.entry {text!r} is not a route the in-app player accepts")
+    return result
+
+
+def target_segments(raw: str, base: AppBase) -> Optional[list[str]]:
+    """The raw base-relative segments of a navigate target, or None when unusable."""
+    path, error, _ = _target_path(raw, base)
+    return None if error else _segments(path)
+
+
+def matches(pattern: list[str], target: list[str]) -> bool:
+    """Segment-wise match: ``:p`` takes any segment; a literal must equal a literal."""
+    if len(pattern) != len(target):
+        return False
+    for pat, seg in zip(pattern, target):
+        if pat.startswith(":"):
+            continue
+        if _VAR_SEG.fullmatch(seg) or pat != _literal(seg):
+            return False
+    return True
+
+
+def bind(pattern: list[str], target: list[str]) -> tuple[tuple[str, str], ...]:
+    """``(param, template)`` pairs: the target's text for each ``:param`` (``{{var}}`` kept)."""
+    out = []
+    for pat, seg in zip(pattern, target):
+        if pat.startswith(":"):
+            out.append((pat[1:], seg if _VAR_SEG.fullmatch(seg) else unquote(seg)))
+    return tuple(out)

steppy/tours/settings.py

@@ -0,0 +1,164 @@
+"""A resolved, immutable view of ``config.yaml``'s ``tours:`` block."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlsplit
+
+from ..captures import DEFAULT_TOURS_DIR, resolve_output_dir
+from ..locales import base_language
+from ..models import DEFAULT_LOCALE, DEFAULT_LOCALES, SteppyConfig
+from ..tour_spec import CHROME_STRING_LOCALES
+from .diagnostics import Diagnostic
+
+
+def origin_of(url: str) -> Optional[str]:
+    """``scheme://host[:port]`` with default ports dropped, or None if not http(s)."""
+    parts = urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        return None
+    default = {"http": 80, "https": 443}[parts.scheme]
+    port = parts.port
+    return f"{parts.scheme}://{parts.hostname.lower()}" + (f":{port}" if port and port != default else "")
+
+
+@dataclass(frozen=True)
+class ToursSettings:
+    enabled: bool
+    default_opt_in: bool
+    build_id_raw: str
+    locales: tuple[str, ...]
+    default_locale: str
+    test_id_attribute: str
+    guide_base_url: Optional[str]
+    guide_origin: Optional[str]
+    layouts: tuple[tuple[str, str], ...]
+    replay: bool
+    project_root: Path
+    tours_root: Path
+    app_assets_dirs: tuple[Path, ...]
+    publishes_guide: bool
+    app_urls: dict = field(default_factory=dict)  # role -> configured app URL
+    screenshot_widths: dict = field(default_factory=dict)  # layout -> viewport width
+
+    @property
+    def layout_map(self) -> dict[str, str]:
+        return dict(self.layouts)
+
+    @classmethod
+    def from_config(cls, config: SteppyConfig, project_root: Path) -> "ToursSettings":
+        tours = config.tours
+        if tours is None:
+            raise ValueError("config.yaml has no tours: block")
+        root = Path(project_root).resolve()
+        locales = tuple(tours.locales or config.locales or DEFAULT_LOCALES)
+        default_locale = tours.default_locale or config.default_locale or DEFAULT_LOCALE
+        base = tours.guide_base_url
+        if base is not None and "${" in base:
+            base = None  # unresolved: no guide links (reported by settings_diagnostics)
+        app_dirs = tuple(resolve_output_dir(root, t.path, t.path) for t in tours.targets if t.type == "app-assets")
+        return cls(
+            enabled=tours.enabled,
+            default_opt_in=tours.default,
+            build_id_raw=tours.build_id,
+            locales=locales,
+            default_locale=default_locale,
+            test_id_attribute=tours.test_id_attribute,
+            guide_base_url=base,
+            guide_origin=origin_of(base) if base else None,
+            layouts=tuple((tours.layouts or {}).items()),
+            replay=tours.replay,
+            project_root=root,
+            tours_root=resolve_output_dir(root, config.output.tours_dir, DEFAULT_TOURS_DIR),
+            app_assets_dirs=app_dirs,
+            publishes_guide=any(t.type == "guide" for t in tours.targets),
+            app_urls={role: app.url for role, app in config.apps.items()},
+            screenshot_widths={name: layout.width for name, layout in config.screenshot.layouts.items()},
+        )
+
+
+# ── Layout media-query sanity check ───────────────────────────────────────────
+
+_TERM = re.compile(r"\(\s*(min|max)-width\s*:\s*(\d+(?:\.\d+)?)px\s*\)")
+_PREFIX = re.compile(r"^(?:only\s+screen|screen|all)\s+and\s+", re.I)
+
+
+def parse_simple_media(query: str) -> Optional[tuple[float, float]]:
+    """``(lo, hi)`` widths a simple ``(min|max)-width: Npx`` query accepts, else None."""
+    text = _PREFIX.sub("", query.strip())
+    lo, hi = 0.0, float("inf")
+    for part in re.split(r"\s+and\s+", text):
+        m = _TERM.fullmatch(part.strip())
+        if not m:
+            return None
+        value = float(m.group(2))
+        if m.group(1) == "min":
+            lo = max(lo, value)
+        else:
+            hi = min(hi, value)
+    return lo, hi
+
+
+def settings_diagnostics(config: SteppyConfig, settings: ToursSettings) -> list[Diagnostic]:
+    """Config-level checks that need more than one block at a time."""
+    out: list[Diagnostic] = []
+    tours = config.tours
+    if tours is not None and tours.guide_base_url and "${" in tours.guide_base_url:
+        out.append(
+            Diagnostic(
+                "warning",
+                "app-url-unresolved",
+                f"tours.guide_base_url {tours.guide_base_url!r} references an unset environment variable; "
+                "tour files get no 'Open the full guide' link",
+            )
+        )
+    for locale in settings.locales:
+        if base_language(locale) not in CHROME_STRING_LOCALES:
+            out.append(
+                Diagnostic(
+                    "warning",
+                    "chrome-strings-missing",
+                    f"tour locale {locale!r} has no built-in overlay strings (buttons, progress, generic hints); "
+                    f"the overlay shows them in English next to {locale} text unless your app sets the host's "
+                    f"`strings` for {locale!r}",
+                    hint=f"built in: {', '.join(CHROME_STRING_LOCALES)}",
+                )
+            )
+    widths = settings.screenshot_widths
+    for name, query in settings.layouts:
+        bounds = parse_simple_media(query)
+        width = widths.get(name)
+        if bounds is None or width is None:
+            out.append(
+                Diagnostic(
+                    "info",
+                    "layout-media-unchecked",
+                    f"tours.layouts[{name!r}] = {query!r} is not a simple width query; "
+                    "the tour replay will still check it in the browser",
+                )
+            )
+            continue
+        lo, hi = bounds
+        if not lo <= width <= hi:
+            out.append(
+                Diagnostic(
+                    "error",
+                    "layout-media-mismatch",
+                    f"tours.layouts[{name!r}] = {query!r} does not match the {name} viewport width ({width}px) "
+                    "from screenshot.layouts, so the overlay would skip that layout's steps where CI runs them",
+                )
+            )
+        for other, other_width in widths.items():
+            if other != name and other in dict(settings.layouts) and lo <= other_width <= hi:
+                out.append(
+                    Diagnostic(
+                        "warning",
+                        "layout-media-overlap",
+                        f"tours.layouts[{name!r}] = {query!r} also matches the {other} viewport ({other_width}px); "
+                        f"{name}-only steps would show on {other} screens too",
+                    )
+                )
+    return out