Files
Jarvis/packages/Bus/Tests/BusTests/WebviewBridgeTests.swift
james.maesandClaude Opus 4.7 5ebe510627 docs: scrub Phase-7 + JarvisBusWorld doc drift (#19, #45) (#195)
* docs(memory): scrub Phase-7 hedge language from MemoryStore (#19)

Audit 2026-05-12 flagged five doc-comment references that mis-described
the implementation state. The cited plans (07-02, 07-03, 07-06) shipped
months ago — the bounded extraction channel, the hybrid FTS5 + vec0 read
path, the ReplayEvent emission, the regression corpus test seams, and
`installMemory`'s replay-sink wiring are all live, not "wires" or
"will replace" promises.

Five touchpoints rewritten to describe the code as it is:

- `MemoryReplaySink` doc: drop the "Plan 07-06" plan reference; the seam
  is just used at startup.
- `MemoryStore` actor doc: replace the "Plan 07-02 wires / Plan 07-03
  wires" sentence with the actual contract (single writer; hybrid search
  through `MemoryReadStore`; `recordRetrieval` emits `memoryRetrieval`).
- Read-path MARK: drop the "Plan 07-03" plan label; keep the
  requirement-ID list (MEM-07 / TEXT-03 / D-02 / D-05) since those are
  still useful for traceability to the audit corpus.
- `recordRetrieval` doc: replace "Mirrors recordMemoryMutation from 07-02"
  with "Mirrors recordMemoryMutation on the write path."
- Test-seams MARK: drop "Plan 07-06" prefix; describe by the test target
  (JARVIS_REAL_MODELS=1 corpus suite) instead.

The 2026-05-11 D-5/D-6 markers and the "Boot policy (changed 2026-05-11)"
doc are preserved unchanged — they document current behaviour, not
historical hedges.

`swift build --package-path packages/Memory` clean.

Closes #19

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(bus): scrub JarvisBusWorld drift + add grep gate (#45)

`fb41c5f` (2026-05-02) unified `Injection.js` and the HUD bundle into the
default `WKContentWorld.page` and retired the prior isolated
`JarvisBusWorld` named world. The doc-comments and test fixtures across
20+ lines kept describing the bug-era topology — pre-existing-bus attach
"because cross-world isolation", message-handler-only-visible-in-named-
world, etc. — for months afterward. Result: a new reader following the
docs would conclude the bus uses two worlds when it actually uses one.

Five rationale rewrites:

- `WebviewBridge.swift` class doc — handler is on the page world, not an
  isolated named world. Page scripts in the loaded HUD bundle address it
  via `window.webkit.messageHandlers.jarvisBus`.
- `Injection.js` header — names the page world explicitly; one-line nod to
  `fb41c5f` for the historical context.
- `bridge.ts` JSDoc + `isJarvisBusShape` rationale — recast the H-02
  attach-to-existing path as a "defensive double-install guard" inside
  ONE page world. Injection.js fires first at document-start; the bundle
  installer fires later as a top-level `main.tsx` side-effect; the guard
  prevents the bundle from clobbering Injection.js's queued early
  messages and captured handshake state. The duck-type `isJarvisBusShape`
  CODE is unchanged — only the comment narrative was misleading.
- `webview/packages/hud/src/main.tsx` — drop the cross-world-isolation
  framing; describe the single-world reality.
- `App/AppDelegate.swift` install comment — page world, not isolated.

Test-side updates (same scrub, plus one latent test bug surfaced):

- `WebviewBridgeTests.test_scriptMessageHandlerIsRegisteredUnderConfigured-
  Name`: was removing from `WKContentWorld.world(name: "JarvisBusWorld")`
  while the bridge registered against `.page` — silent no-op since
  `removeScriptMessageHandler` doesn't throw on absent. Now removes from
  `.page` (the world the bridge actually uses), making the
  "registration-is-evidence-of-success" assertion meaningful again.
- `WebviewBridgeOutboundTests`: comment-only.
- `RealWKWebViewIntegrationTests`: comment-only (forensic narrative kept,
  literal world name replaced with "prior isolated named content world").
- `webview/packages/bus/tests/bridge.test.ts`: H-02 describe-block + one
  it-name rewritten to match the new defensive-double-install rationale.

Infrastructure:

- `scripts/check-no-jarvis-bus-world-references.sh`: new boundary gate.
  Greps for the literal `JarvisBusWorld` in tracked files; excludes
  `.planning/`, `docs/`, `webview/packages/*/dist/`, and this script
  itself. Wired into `CLAUDE.md`'s gate listing; the CI
  `boundary-gates` job auto-discovers all `scripts/check-*.sh`, so no
  workflow edit is needed.
- `webview/packages/bus/package.json`: 0.0.0 → 0.0.1 (per spec —
  comment-only changes still bump patch so consumers can pin).
- `webview/packages/bus/dist/bridge.{js,d.ts}`: rebuilt via `pnpm --filter
  @jarvis/bus build`; NOT committed because `dist/` is not tracked (the
  build phase regenerates on each xcodebuild invocation).

Verified locally:
- `swift build --package-path packages/Bus` clean
- `pnpm --filter @jarvis/bus test` — 37/37 pass
- `bash scripts/check-no-jarvis-bus-world-references.sh` — PASS
- `bash scripts/check-bus-protocol-version.sh` — PASS (v2.3.0)
- `bash scripts/check-bus-harness-parity.sh` — PASS

Closes #45

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-14 09:51:03 -05:00

198 lines
7.0 KiB
Swift

import XCTest
import WebKit
@testable import Bus
/// Exercises the inbound-decode-and-dispatch path via the internal
/// `handleInboundString` seam. Synthesizing `WKScriptMessage` instances from
/// user code is not supported — the test seam keeps the decode path covered
/// without reaching for WebKit internals.
@MainActor
final class WebviewBridgeTests: XCTestCase {
// MARK: - Fixtures
private func makeBridge() -> (WebviewBridge, WKWebView) {
let webView = WKWebView(frame: .zero, configuration: WKWebViewConfiguration())
let bridge = WebviewBridge(
webView: webView,
alertPresenter: { _, _ in
// Silent presenter — these tests assert the inbound dispatch
// path, not the alert path (covered by HandshakeTests).
}
)
return (bridge, webView)
}
/// Main-actor-scoped reply capture. `Any?` is not `Sendable`, so we
/// stash the reply values into main-actor-isolated storage and read them
/// after waiting on an expectation that the replyHandler fulfills.
private func runAndCaptureReply(
_ body: (ReplyCollector) -> Void,
timeout: TimeInterval = 1.0,
file: StaticString = #filePath,
line: UInt = #line
) -> ReplyCollector {
let collector = ReplyCollector()
body(collector)
let waiter = XCTWaiter()
_ = waiter.wait(for: [collector.expectation], timeout: timeout)
if !collector.received {
XCTFail("replyHandler never fired within \(timeout)s", file: file, line: line)
}
return collector
}
// MARK: - Success paths
func test_inboundDecodeSuccessCallsOnInbound() {
let (bridge, _) = makeBridge()
var recorded: [BusInbound] = []
bridge.onInbound = { msg in
recorded.append(msg)
return .success
}
let reply = runAndCaptureReply { collector in
bridge.handleInboundString(#"{"type":"uiReady"}"#, replyHandler: collector.replyHandler)
}
XCTAssertEqual(recorded, [.uiReady])
XCTAssertNil(reply.error)
XCTAssertEqual(reply.plist?["ok"] as? Bool, true)
}
func test_onInboundReturningNilYieldsImplicitSuccess() {
let (bridge, _) = makeBridge()
bridge.onInbound = { _ in nil }
let reply = runAndCaptureReply { collector in
bridge.handleInboundString(#"{"type":"uiReady"}"#, replyHandler: collector.replyHandler)
}
XCTAssertNil(reply.error)
XCTAssertEqual(reply.plist?["ok"] as? Bool, true)
}
// MARK: - Failure paths
func test_inboundDecodeFailureSurfacesAsFailureReply() {
let (bridge, _) = makeBridge()
var onInboundCalls = 0
bridge.onInbound = { _ in
onInboundCalls += 1
return .success
}
let reply = runAndCaptureReply { collector in
bridge.handleInboundString("{not json", replyHandler: collector.replyHandler)
}
XCTAssertNil(reply.plist)
XCTAssertTrue(
reply.error?.lowercased().contains("decode") ?? false,
"expected decode-error message, got: \(reply.error ?? "<nil>")"
)
XCTAssertEqual(onInboundCalls, 0, "onInbound must not fire on decode failure")
}
func test_inboundNonStringBodyIsFailureReply() {
let (bridge, _) = makeBridge()
let reply = runAndCaptureReply { collector in
// `nil` models the "body was not a string" guard at the top of
// `handleInboundString` — which the protocol method hits when
// `message.body as? String` fails.
bridge.handleInboundString(nil, replyHandler: collector.replyHandler)
}
XCTAssertNil(reply.plist)
XCTAssertEqual(reply.error, "bus: expected string payload")
}
func test_onInboundThrowingErrorSurfacesAsFailureReply() {
let (bridge, _) = makeBridge()
bridge.onInbound = { _ in
throw BusError.bridgeNotReady
}
let reply = runAndCaptureReply { collector in
bridge.handleInboundString(#"{"type":"uiReady"}"#, replyHandler: collector.replyHandler)
}
XCTAssertNil(reply.plist)
XCTAssertTrue(
reply.error?.contains("handler error") ?? false,
"expected handler-error prefix, got: \(reply.error ?? "<nil>")"
)
}
// MARK: - Handshake ack is handled inline
func test_helloAckHandledInlineDoesNotCallOnInbound() {
let (bridge, _) = makeBridge()
var onInboundCalls = 0
bridge.onInbound = { _ in
onInboundCalls += 1
return .success
}
bridge.startHandshake()
let payload = #"{"type":"helloAck","version":"\#(BUS_PROTOCOL_VERSION)"}"#
let reply = runAndCaptureReply { collector in
bridge.handleInboundString(payload, replyHandler: collector.replyHandler)
}
XCTAssertEqual(onInboundCalls, 0, "helloAck must not reach onInbound")
XCTAssertEqual(bridge.handshakeState, .armed)
XCTAssertNil(reply.error)
XCTAssertEqual(reply.plist?["ok"] as? Bool, true)
}
// MARK: - Content world / handler registration
func test_scriptMessageHandlerIsRegisteredUnderConfiguredName() {
let webView = WKWebView(frame: .zero, configuration: WKWebViewConfiguration())
_ = WebviewBridge(
webView: webView,
messageHandlerName: "jarvisBus",
alertPresenter: { _, _ in }
)
// Re-adding a handler with the same (contentWorld, name) pair would
// raise `NSInvalidArgumentException`. The constructor succeeding is
// itself evidence of registration. As a double-check, `remove` on a
// registered handler must succeed without throwing. We remove from
// `WKContentWorld.page` because that is the default world
// `WebviewBridge.init` registers the handler against since `fb41c5f`
// unified bus and bundle into the same page world.
let controller = webView.configuration.userContentController
controller.removeScriptMessageHandler(
forName: "jarvisBus",
contentWorld: .page
)
// No XCTAssert needed — the remove call succeeding on a registered
// handler is the assertion.
}
}
// MARK: - Reply collector
/// Main-actor-isolated reply storage. The replyHandler closure captures the
/// collector and writes into its mutable fields synchronously; the test
/// reads those fields after waiting on `expectation`.
@MainActor
final class ReplyCollector {
let expectation = XCTestExpectation(description: "bus reply")
var plist: [String: Any]?
var error: String?
var received: Bool = false
var replyHandler: @MainActor @Sendable (Any?, String?) -> Void {
{ [self] value, error in
self.plist = value as? [String: Any]
self.error = error
self.received = true
self.expectation.fulfill()
}
}
}