English · 日本語
Network observation (request assertions)¶
Verify the HTTP(S) traffic an app makes, as a step/expect assertion. On iOS and Android, observation is in-app: the app reports each exchange to a collector bajutsu runs. On web, Playwright observes the page's traffic natively, with no app-side reporting involved. On every platform, a
requestassertion checks the accumulated exchanges.Implementation:
bajutsu/common/evidence/network.py: the model and the collectorbajutsu/assertions/network.py: therequestevaluationbajutsu/common/drivers/web_network.py: the Playwright-native collector and mocking (BE-0054)- the in-app software development kit (SDK):
BajutsuKiton iOS andBajutsuAndroidon AndroidThe web (Playwright) backend needs no SDK.
How traffic is observed¶
A Simulator app runs as a host process and shares the Mac's loopback. Traffic observation then proceeds in three stages:
- On
run, bajutsu starts a collector (NetworkCollector) on127.0.0.1:<port>and injects its URL into the app via theBAJUTSU_COLLECTORlaunch env, together with a per-run shared token viaBAJUTSU_COLLECTOR_TOKEN. - The app (linked with BajutsuKit) installs a
URLProtocolthat records each request/response and POSTs it to the collector after TLS (Transport Layer Security). The capture uses no proxy and no certificate authority (CA). It works regardless of which backend drives the app, and programs can read it. Each POST proves the token. The collector rejects any request that does not (401), so another local process cannot inject fabricated exchanges into the run's evidence. - bajutsu always announces
BAJUTSU_COLLECTOR_AUTH=hmac. A current BajutsuKit then signs each request with the token. - An older BajutsuKit sends the token as an
Authorization: Bearerheader instead. A loopback collector still accepts that header. - On a real device the collector accepts signed requests alone (the real-device guide).
- The collector keeps the exchanges in memory. A step's
requestassertion is evaluated against them in real time, and bajutsu writes them (redacted) to<sid>/network.jsonas scenario evidence.
--no-network disables the collector. Apps without the SDK report nothing, so the collector stays
empty; the feature is opt-in per app.
On iOS, the same collector also receives screen-transition events on a separate /transitions
endpoint (BE-0310). BajutsuKit's BajutsuScreen swizzles UIViewController.viewDidAppear(_:)
and reports each completed view-controller appearance there. The collector keeps these events in
their own store, independent of the network exchanges above. The signal does not concern the
request assertion: the post-launch readiness gate and the settled wait consult it instead. See
run-loop.
Android¶
Android works the same way, with two differences (BE-0283).
- The app links
BajutsuAndroidand addsBajutsuNet.interceptor()to its OkHttp client. Android has no single OS-level HTTP hook like iOS'sURLProtocol, so the interceptor is per-client and captures OkHttp traffic. - The emulator's
127.0.0.1is its own loopback, not the host's. bajutsu bridges the collector to the device withadb reverse, using the same port on both sides so the injectedBAJUTSU_COLLECTORURL resolves unchanged.
That one port number must be bindable on both sides, so an Android lane takes the collector's port from a small reserved band rather than letting the operating system pick a free one. An operating-system pick comes from the host's ephemeral range, which is also the range the emulator hands out to its own sockets. The pick periodically names a port the guest already holds, and the bridge then fails to bind.
The band applies to Android alone. The iOS Simulator shares the Mac's loopback, bridges nothing, and keeps the operating-system pick. The collector, the token check, and the assertion pipeline are identical.
Web¶
Web (Playwright) needs none of this in-app machinery, because Playwright already sees every
request the page makes (BE-0054). PlaywrightDriver.network_collector() hooks the page's
requestfinished event directly into the same NetworkExchange model. The page needs no
BAJUTSU_COLLECTOR launch env, no port, and no token; the driver is the collector. The
resulting NetworkExchange records match the same request assertion as on iOS and Android.
The in-app path is the chosen mechanism. RocketSim's GUI network inspector and a TLS-intercepting proxy were both rejected. The inspector is not exposed on its CLI, so automated assertions cannot use it. The proxy needs a CA install and breaks on certificate pinning. See the design notes.
The request assertion¶
request is an assertion kind (alongside exists / value / count / …). Match fields
are AND-ed. Each plain request corresponds to one observed exchange. Each request
assertion in a block pairs one-to-one with a distinct exchange, so two request lines
need two separate requests. count is the exception: an explicit aggregate (exact when set,
otherwise the lone matcher needs at least one).
expect:
- request: { method: POST, path: /login, status: 200, bodyMatches: "\"user\"" } # one login POST
- request: { method: GET, urlMatches: "q=hello&n=42" } # a *different* request
- request: { pathMatches: "^/items", count: 2 } # aggregate: exactly 2
| field | meaning |
|---|---|
method |
HTTP method (case-insensitive) |
url |
exact full URL (the endpoint) |
urlMatches |
regex/substring over the full URL |
path |
exact URL path (query ignored) |
pathMatches |
regex over the path |
query |
key/value dictionary over the URL-decoded query parameters, order-independent (BE-0463) |
body |
key/value dictionary over the JavaScript Object Notation (JSON) request body, nested maps and lists included (BE-0463) |
status |
response status code |
bodyMatches |
regex/substring over the raw request body |
count |
exact number of matching exchanges; an aggregate, exempt from the 1:1 rule (omit ⇒ at least one) |
Deterministic mocks¶
A scenario's mocks make the network deterministic. When an outgoing request matches a
rule, the platform's collector returns the canned response instead of hitting the network, so
a test never depends on a live server and runs offline.
- On iOS, BajutsuKit serves the stub inside the URL protocol, after TLS, with no proxy or CA.
- On web,
WebNetworkCollectorfulfills the stub in-process via Playwright'spage.route. - BajutsuAndroid observes but does not yet stub (a follow-up to BE-0283).
On iOS and web, the stub is still observed: network.json lists it flagged mocked, and
request assertions match it like any exchange.
mocks:
- match: { method: GET, urlMatches: "example.com" } # request-side matcher
respond:
status: 418 # default 200
headers: { Content-Type: text/plain }
body: "stubbed by bajutsu"
# delayMs: 200 # optional artificial latency
- match: { method: POST, pathMatches: "/login$" }
respond: { status: 201, body: "{\"token\":\"t\"}" }
The first matching rule wins. match reuses the request matcher's request-side fields
(method / url / urlMatches / path / pathMatches / bodyMatches). A mock refuses the
query / body dictionaries, since the in-app matcher would ignore them.
Mocks ride the same channel as observation, so they need --network. On iOS, the rules reach the
app via the BAJUTSU_MOCKS launch env (like BAJUTSU_COLLECTOR). On web, no app launches,
so network_collector() takes the scenario's mocks directly and fulfills them in-process.
On iOS, a setMocks step replaces the stub table while the app runs (BE-0365). The collector
queues the new table, and the app drains it over the in-app control channel. The step waits until
the app confirms the new table. setMocks needs the xcuitest backend with network collection on.
run refuses a scenario that uses it anywhere else, before the scenario starts.
scenarios covers the step in full.
Timing¶
Network I/O is asynchronous, so a step can run before the response lands. Bridge the gap with a
wait on the UI that reflects the response before the request assertion. Use
wait: { until: settled }, or wait for an element the response reveals.
On iOS and Android the SDK POSTs on completion, and on web Playwright's own requestfinished
event fires then. On every platform, the exchange is in the collector by the time the UI has
updated.
App contract¶
iOS: link BajutsuKit and call BajutsuNet.startIfEnabled() early.
The call is inert unless BAJUTSU_COLLECTOR is set, captures URLSession HTTP(S) only, and is
test/debug-only. It records headers and bodies, so keep it out of release builds and use
redact.
BajutsuKit forwards the intercepted request as-is, with the same method, headers, body, and
timeout. URLProtocol cannot recover the app's own URLSessionConfiguration, though. An app
with TLS pinning or client-cert auth in its delegate can see the check fail once intercepted.
Android: link BajutsuAndroid, call BajutsuNet.configure(env) at
launch (with the launch-env map), and add BajutsuNet.interceptor() to the app's OkHttpClient.
The interceptor is inert unless BAJUTSU_COLLECTOR is set, captures OkHttp HTTP(S) only, and
is likewise test/debug-only: it records headers and bodies, so keep it out of release builds
and use redact, the same caveat as on iOS.
Android also needs a network_security_config cleartext exception for 127.0.0.1 in the
test/debug build. The collector URL is plain HTTP, which API 28+ blocks by default. iOS exempts
loopback from App Transport Security (ATS) and needs no exception. Without the exception, the
report POST fails. The app logs the error and stays otherwise silent, so no exchange ever reaches
the collector.
Web: the app has no side of the contract at all. Playwright observes and mocks the page's traffic natively, so nothing in the app under test needs to change.