"""Unit: the failed-turn frontend contract (phase 120, task 03). Pins the phase-120 client contract as source assertions (the house ``test_frontend_*`` style — no browser): the three live failure paths route through the single ``finalizeFailedTurn`` funnel (persist ``failed: true`` + the capped detail, end retryable), the zero-frame fallback bubble persists the marker too, ``appendFailedNote`` mirrors the stopped note (one per bubble, textContent-only detail), ``FAILED_TURN_TEXT`` is a distinct constant (NOT ``EMPTY_ANSWER_FALLBACK``), the restore branch renders the failed note and excludes the Save-as-doc / Tune buttons, and — the phase's explicit "NOT touched" contract — ``showErrorBanner`` and ``retryLastTurn`` are byte-unchanged (their full sources are pinned below). """ from __future__ import annotations import re from pathlib import Path FRONTEND = Path(__file__).resolve().parents[2] / "frontend" APP_JS = FRONTEND / "assets" / "app.js" STYLES_CSS = FRONTEND / "assets" / "styles.css" def _js() -> str: return APP_JS.read_text(encoding="utf-8") def _css() -> str: return STYLES_CSS.read_text(encoding="utf-8") def _find_body_brace(js: str, start: int) -> int: """The index of the REAL opening brace of a function at *start* — the first ``{`` OUTSIDE the parameter list (paren depth 0), so empty object defaults (``opts = {}``) and destructured parameters (``{ acc, thinking }``) are skipped (the phase-111 banner-test convention, extended).""" i = start paren = 0 while i < len(js): c = js[i] if c == "(": paren += 1 elif c == ")": paren -= 1 elif c == "{" and paren == 0: return i i += 1 return -1 def _fn_source(js: str, name: str) -> str: """The full source of ``function name(…){…}`` (signature + body).""" start = js.index(f"function {name}(") brace = _find_body_brace(js, start) depth = 0 i = brace while True: c = js[i] if c == "{": depth += 1 elif c == "}": depth -= 1 if depth == 0: break i += 1 return js[start : i + 1] def _fn_body(js: str, name: str) -> str: """Just the body of ``function name(…){…}`` (between the braces).""" src = _fn_source(js, name) start = js.index(f"function {name}(") brace = _find_body_brace(js, start) rel = brace - start return src[rel + 1 : len(src) - 1] # --------------------------------------------------------------------------- # appendFailedNote — the in-bubble error note (the stopped-note mirror) # --------------------------------------------------------------------------- def test_append_failed_note_exists_and_guards_dedup() -> None: """``appendFailedNote(wrap, detail)`` exists and mirrors ``appendStoppedNote``: it reuses the ``.msg-meta`` row and adds at most ONE ``.failed-note`` per bubble (the duplicate guard).""" js = _js() body = _fn_body(js, "appendFailedNote") assert '.msg-body' in body, "the note must land in the bubble's .msg-body" assert ".msg-meta" in body, "the note rides the existing .msg-meta row" assert '.failed-note' in body assert ( 'if (meta.querySelector(".failed-note")) return;' in body ), "one .failed-note per bubble (the duplicate guard, the stopped-note way)" assert 'note.className = "failed-note";' in body def test_append_failed_note_is_text_and_color_never_color_alone() -> None: """The note is TEXT + color (B5): the "Failed" label is set through ``textContent``, the icon is aria-hidden decoration, and the detail goes through ``textContent`` too — the error string is NEVER innerHTML (no HTML from an error, ever).""" js = _js() body = _fn_body(js, "appendFailedNote") assert 'label.textContent = "Failed";' in body assert 'd.className = "failed-detail"' in body assert "d.textContent = detail" in body, "the detail is textContent, never innerHTML" # The icon itself is the only innerHTML — the static SVG constant, # aria-hidden decoration (the accessible meaning is the label + # detail text — B5: text + color, never color alone). assert "note.innerHTML = FAILED_ICON;" in body m_icon = re.search(r"const FAILED_ICON\s*=\s*\n?\s*'([^']*)'", js) assert m_icon, "const FAILED_ICON must exist" assert 'aria-hidden="true"' in m_icon.group(1), "the icon is decoration" def test_failed_turn_text_is_a_distinct_constant() -> None: """``FAILED_TURN_TEXT`` is its OWN string literal — NOT ``EMPTY_ANSWER_FALLBACK`` (that constant stays the zero-frame-but-COMPLETED case's answer text) and a short honest "my answer didn't make it" line (not the answer text, not the raw detail).""" js = _js() m_fail = re.search(r'const FAILED_TURN_TEXT\s*=\s*\n?\s*"([^"]*)"', js) assert m_fail, "const FAILED_TURN_TEXT must be a string literal" failed_text = m_fail.group(1) assert failed_text, "FAILED_TURN_TEXT must be non-empty" m_empty = re.search(r'const EMPTY_ANSWER_FALLBACK\s*=\s*\n?\s*"([^"]*)"', js) assert m_empty, "const EMPTY_ANSWER_FALLBACK must still be a string literal" assert failed_text != m_empty.group(1), ( "FAILED_TURN_TEXT must be DISTINCT from EMPTY_ANSWER_FALLBACK" ) # The zero-frame branch uses the constant, not a copy of the # fallback. assert 'addMessage("brain", FAILED_TURN_TEXT);' in js # --------------------------------------------------------------------------- # finalizeFailedTurn — the single funnel for the live failure paths # --------------------------------------------------------------------------- def test_finalize_failed_turn_persists_failed_in_both_shapes() -> None: """The funnel persists ``failed: true`` in BOTH shapes (partial wrap + the zero-frame bubble) with the capped detail, and the partial keeps the streamed text (``acc``).""" js = _js() body = _fn_body(js, "finalizeFailedTurn") # Both branches persist the marker… assert body.count("failed: true") == 2, ( "both funnel shapes must persist failed: true" ) # …the detail trimmed + capped at 500 before persistence (the # schema's ChatMessage.error bound is the backstop)… assert '(detail || "").trim().slice(0, 500)' in body # …the zero-frame shape creates the FAILED_TURN_TEXT bubble… assert 'addMessage("brain", FAILED_TURN_TEXT);' in body assert "appendFailedNote(fwrap, error);" in body # …and the partial shape settles the block + calls closed (the # stop-finalize pattern) and adds the note. assert "closeThinkingBlock(wrap);" in body assert "closeToolCalls(wrap);" in body assert "appendFailedNote(wrap, error);" in body # Both shapes land the record through rememberBrainTurn (local # storage + the phase-55 auto-save ride) and set lastBrainWrap # BEFORE the caller's setUiState(error, …). assert body.count("rememberBrainTurn(") == 2 assert body.count("lastBrainWrap =") == 2 def test_finalize_failed_turn_ends_retryable() -> None: """The funnel ENDS with ``markLastRetryable()`` (the last statement — a trailing comment is fine) — the in-bubble Retry button lands on the failed bubble (the last brain wrap).""" js = _js() body = _fn_body(js, "finalizeFailedTurn").rstrip() last_line = body.splitlines()[-1].strip() assert last_line.startswith("markLastRetryable();"), ( "finalizeFailedTurn must end with the markLastRetryable() call" ) def test_error_catch_else_routes_through_the_funnel() -> None: """The error catch's ``else`` branch (non-abort, non-stop — network error, pre-stream HTTP error, the SSE ``error`` frame's throw) calls ``finalizeFailedTurn`` BEFORE ``setUiState(UI_STATE.error, …)`` — the funnel sets lastBrainWrap, so the banner's EXISTING ``opts.retryable && lastBrainWrap`` condition reveals the Retry.""" js = _js() # The stop branch ends where the plain else begins. stop_branch = js.index('} else if (stoppedByUser || err?.name === "AbortError") {') else_branch = js.index("} else {", stop_branch) finally_branch = js.index("} finally {", else_branch) else_body = js[else_branch:finally_branch] assert "finalizeFailedTurn(detail, {" in else_body # The persistence (the funnel) precedes the error state — the # banner's Retry precondition is set before the banner shows. assert else_body.index("finalizeFailedTurn(detail, {") < else_body.index( "setUiState(UI_STATE.error, detail," ) def test_navigate_away_is_not_a_failed_turn() -> None: """A REAL departure is not a failed turn (phase-120 verification fix): the pagehide handler sets a turn-scoped ``leftThePage`` flag (module scope, like ``persistedOnLeave``), and the error catch's ``else`` branch skips the failed funnel when it is set — the browser's teardown rejection of the cancelled in-flight fetch (a TypeError, NOT an AbortError) must not persist a failed brain record: the phase-20 convention stands (thinking-only navigate-away persists nothing brain-side; a partial navigate-away persists the pagehide partial as a plain record). The flag is set unconditionally on pagehide (a merely-hidden tab in some browsers also fires it — the stream keeps arriving, so no rejection follows and it stays inert there) and reset per turn at the top of ``runTurn`` with the other turn locals.""" js = _js() # Module-scope declaration (column 0), exactly once. assert re.search(r"^let leftThePage = false", js, re.M), ( "leftThePage must be a module-scope flag (the pagehide handler " "reads it), like persistedOnLeave" ) assert js.count("let leftThePage = false;") == 1 # Set as the FIRST statement of the pagehide handler — before the # persistedOnLeave early return (a thinking-only navigate-away # returns early, but the flag must be set for the funnel skip). ph = js.index('window.addEventListener("pagehide", () => {') ph_end = js.index("\n});", ph) ph_body = js[ph:ph_end] idx_flag = ph_body.find("leftThePage = true;") idx_return = ph_body.find("if (persistedOnLeave) return;") assert 0 <= idx_flag < idx_return, ( "leftThePage must be set BEFORE the pagehide early returns" ) # Reset per turn at the top of runTurn (the persistedOnLeave group). turn = js.index("async function runTurn") abort_idx = js.index("turnAbort = new AbortController()", turn) turn_top = js[turn:abort_idx] assert "leftThePage = false;" in turn_top, ( "leftThePage must be reset per turn at the top of the turn handler" ) assert turn_top.index("persistedOnLeave = false;") < turn_top.index( "leftThePage = false;" ) # The catch's else branch (non-abort, non-stop) skips the funnel # when the flag is set — the funnel call itself stays intact (the # real-network-error path, no pagehide). stop_branch = js.index('} else if (stoppedByUser || err?.name === "AbortError") {') else_branch = js.index("} else {", stop_branch) finally_branch = js.index("} finally {", else_branch) else_body = js[else_branch:finally_branch] idx_guard = else_body.find("if (!leftThePage) {") idx_funnel = else_body.find("finalizeFailedTurn(detail, {") assert 0 <= idx_guard < idx_funnel, ( "the failed funnel must be skipped after a real page departure " "(the teardown rejection is not a failed turn)" ) def test_stream_drop_guard_routes_through_the_funnel() -> None: """The stream-drop guard (frames arrived, no ``done`` — the connection died mid-turn) routes through the SAME funnel: the half-answer persists as failed (its text + the error note + a working Retry) BEFORE the error state.""" js = _js() guard = js.index("if (!sawDone && !aborted && (acc || thinkingAcc)) {") zero_frame = js.index("if (!aborted && !wrap) {", guard) guard_body = js[guard:zero_frame] assert "finalizeFailedTurn(detail, {" in guard_body assert guard_body.index("finalizeFailedTurn(detail, {") < guard_body.index( "setUiState(UI_STATE.error, detail);" ) def test_zero_frame_fallback_persists_failed_marker() -> None: """The zero-frame-but-COMPLETED fallback bubble (the stream settled with no events) is a failed turn too (task 01 ASSUMPTION): the bubble text stays ``EMPTY_ANSWER_FALLBACK`` (a meaningful record text) but the record gains ``failed: true`` + the error note, and the bubble ends retryable.""" js = _js() zero_frame = js.index("if (!aborted && !wrap) {") catch = js.index("} catch (err) {", zero_frame) block = js[zero_frame:catch] assert "const fallback = EMPTY_ANSWER_FALLBACK;" in block, ( "the bubble text stays the EMPTY_ANSWER_FALLBACK answer text" ) assert "appendFailedNote(fwrap, nothing);" in block assert "failed: true," in block assert "error: nothing," in block assert "markLastRetryable();" in block def test_only_the_three_failed_paths_persist_failed() -> None: """No call site OUTSIDE the three failed paths persists ``failed: true`` (task 01 completion criterion, grep-level): exactly three CODE sites — two in ``finalizeFailedTurn`` (the partial + zero-frame shapes) and one in the zero-frame-but- completed fallback — the done, stop, and restore paths never set the marker (they read it, or don't touch it).""" js = _js() fn = _fn_body(js, "finalizeFailedTurn") zero_frame = js.index("if (!aborted && !wrap) {") catch = js.index("} catch (err) {", zero_frame) fallback_block = js[zero_frame:catch] fn_start = js.index("function finalizeFailedTurn(") fn_src = _fn_source(js, "finalizeFailedTurn") code_outside = js[:fn_start] + js[fn_start + len(fn_src) :] code_outside = code_outside.replace(fallback_block, "") # Comments may mention the marker; code must not (the file's # block-comment lines start with * or /* after stripping). code_lines = [ line for line in code_outside.splitlines() if not line.strip().startswith(("//", "*", "/*")) ] assert "failed: true" not in "\n".join(code_lines), ( "only the three failed paths may persist failed: true" ) assert fn.count("failed: true") == 2 assert fallback_block.count("failed: true") == 1 # --------------------------------------------------------------------------- # restore — a failed record renders as an error bubble with the note # --------------------------------------------------------------------------- def test_restore_renders_the_failed_note() -> None: """The restore branch re-renders the in-bubble error note from the persisted ``error`` detail — and only when it is present (a record whose ``error`` is null has the detail in its ``text`` already).""" js = _js() body = _fn_body(js, "renderStoredMessage") assert "if (m.failed && m.error) appendFailedNote(wrap, m.error);" in body, ( "the failed note restores from the persisted error detail" ) def test_restore_excludes_save_as_doc_and_tune_for_failed() -> None: """A failed turn is a NOTE, not an answer: the restore excludes both the Save-as-doc button (the ``m.stopped`` exclusion extended with ``!m.failed``) and the Tune button (``!m.failed``). Stopped and successful records keep their buttons — the pre-phase-120 behavior for them is byte-identical.""" js = _js() body = _fn_body(js, "renderStoredMessage") assert "if (!m.stopped && !m.failed) appendSaveAsDocButton(wrap, m.text);" in body assert "if (!m.failed) appendTuneButton(wrap);" in body # --------------------------------------------------------------------------- # NOT touched — the phase's explicit contract (byte-pinned sources) # --------------------------------------------------------------------------- #: The FULL source of ``showErrorBanner`` as of phase 120 — the #: phase-111 button + the phase-114 hint, byte-unchanged by this phase #: (the phase makes ``lastBrainWrap`` EXIST on the error paths instead #: of changing the condition). A diff here is a contract violation. PINNED_SHOW_ERROR_BANNER = """function showErrorBanner(detail, opts = {}) { banner.hidden = false; banner.classList.add("is-error"); banner.setAttribute("role", "alert"); // Phase 114 (TODO L6): a frame-carried hint (the "question too long" // case — reachability is fine, only the length is the problem) replaces // the default reachability hint when present. bannerText.textContent = detail ? `${detail} ${opts.hint ?? ERROR_HINT}` : (opts.hint ?? ERROR_HINT); // Phase 111 (task 01): reveal the banner Retry button only for failed // chat turns (opts.retryable) AND when a retryable bubble exists. if (opts.retryable) { const btn = document.querySelector("#banner-retry"); if (btn && lastBrainWrap) { btn.hidden = false; // Bind click once per reveal — the old listener is removed after // the first click, so re-binding on every reveal is safe. btn.addEventListener("click", () => retryLastTurn(lastBrainWrap)); } } }""" def test_show_error_banner_is_byte_unchanged() -> None: """``showErrorBanner`` is byte-unchanged by phase 120 (the "NOT touched" contract): its full source must match the pin — the ``opts.retryable && lastBrainWrap`` condition, the phase-114 hint merge, and the once-per-reveal binding included.""" assert _fn_source(_js(), "showErrorBanner") == PINNED_SHOW_ERROR_BANNER #: The FULL source of ``retryLastTurn`` as of phase 120 — the phase-49 #: redo-in-place (pop the last brain record, re-ask the preceding #: question). It works on a failed record UNCHANGED (locked A1): the #: question's user record immediately precedes the failed record. PINNED_RETRY_LAST_TURN = """function retryLastTurn(wrap) { if (uiState === UI_STATE.thinking || uiState === UI_STATE.streaming) return; if (wrap !== lastBrainWrap) return; // stale click — the button moved on let lastIdx = -1; for (let i = conversation.length - 1; i >= 0; i -= 1) { if (conversation[i].who === "brain") { lastIdx = i; break; } } if (lastIdx === -1) return; // Invariant: every brain record follows its user record — the // question to re-ask is the record immediately before the popped one. const prev = conversation[lastIdx - 1]; if (!prev || prev.who !== "user") return; const text = prev.text; conversation.splice(lastIdx, 1); // redo in place: the old answer is gone // Save BEFORE the rerun: what the user saw — the removed answer — is // what is stored from this point on (the question stays, the replaced // answer never comes back). saveConversation(); wrap.remove(); lastBrainWrap = null; // Re-ask without re-adding: the reask turn skips the user append and // persistence save point 1 (the question is already in both). // Phase 53: the promise is returned (the Regenerate await above); // runTurn never rejects — a failure surfaces as the error banner. return runTurn(text, { reask: true }); }""" def test_retry_last_turn_is_byte_unchanged() -> None: """``retryLastTurn`` is byte-unchanged by phase 120 (locked A1 — the redo-in-place is REUSED, not extended): the full source must match the pin — the pop-the-last-brain-record + re-ask logic, the in-flight guard, and the stale-click guard included.""" assert _fn_source(_js(), "retryLastTurn") == PINNED_RETRY_LAST_TURN # --------------------------------------------------------------------------- # CSS — the in-bubble error line (the .stopped-note family, error color) # --------------------------------------------------------------------------- def test_failed_note_css_uses_the_error_token() -> None: """``.failed-note`` exists in styles.css, colored by the theme's error TOKEN (``--err-ink`` — the monochrome theme grays it automatically; the contrast floor is the stopped-note family's) — never a literal color (the phase-92 zero-literal convention).""" css = _css() m = re.search(r"\.failed-note \{([\s\S]*?)\n\}", css) assert m, "styles.css must define .failed-note" body = m.group(1) assert "color: var(--err-ink);" in body, ( ".failed-note must use the theme's error token" ) assert "pointer-events: none;" in body, "the note is non-interactive (the stopped-note way)" def test_failed_detail_wraps_long_details() -> None: """The detail span WRAPS (a 500-char error detail must not blow out the 46rem chat column — the stopped note's nowrap fits a one-word label, not a detail).""" css = _css() m = re.search(r"\.failed-detail \{([\s\S]*?)\n\}", css) assert m, "styles.css must define .failed-detail" assert "overflow-wrap: anywhere;" in m.group(1)