diff --git a/.github/workflows/pinned-agents.yml b/.github/workflows/pinned-agents.yml index 229cdad3..b2d7a415 100644 --- a/.github/workflows/pinned-agents.yml +++ b/.github/workflows/pinned-agents.yml @@ -2,7 +2,7 @@ # # Deliberately NOT part of CI. These tests download UiAutomator2 and # WebDriverAgent from their upstream GitHub releases, so they fail when -# GitHub, Appium or the WebDriverAgent project has a bad day — none of which +# GitHub or either project has a bad day — none of which # is a reason to block a pull request. Failing here means "go look", not # "the change is wrong". # diff --git a/CLAUDE.md b/CLAUDE.md index d5ce31ee..48034223 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,7 @@ binary, driven from a CLI, an MCP server, or five language clients. ## Tech Stack - Go: the `mobium` binary, no runtime dependencies -- Appium's UiAutomator2 server (Android) and WebDriverAgent (iOS), driven directly over HTTP — no Appium, no Node +- The UiAutomator2 server (Android) and WebDriverAgent (iOS), driven directly over HTTP — no Node - CDP (Android WebViews) and WebKit's Remote Web Inspector (iOS WebViews) - MCP server on stdio (`mobium mcp`) - Clients: Go, Python, JavaScript, Java, .NET — each spawns `mobium pipe` diff --git a/README.md b/README.md index d82b0e14..951f593d 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ the wrong string. | Files | `upload` and `download` between this machine and where the device keeps downloads — the Download folder on Android, an app's Documents on an iOS simulator | | Device state | permissions, appearance, accessibility settings for the session (reduce motion, bold text, contrast, text size and more; a simulator and Android), orientation, per-app language, hardware buttons, shake and biometrics (enroll, then a matching or a stranger's face or finger) on emulators and simulators, screen lock, simulated calls and messages, notifications, timezone and the device's clock, battery, clipboard, geolocation and routes | | Dialogs | `alert` reads, answers and types into a system or app dialog; `dialogs` declares answers for one that gets in an action's way | -| Diagnostics | device logs, crash reports and ANRs, screen recording, a session `trace` for the Playwright trace viewer, `hit-test` — which view UIKit would really give a tap, below accessibility (iOS; before every tap with `launch --hit-test` on a simulator), `audit` — Apple's own accessibility audit of the screen (iOS), `doctor` | +| Diagnostics | device logs, crash reports and ANRs, screen recording, a session `trace` in Vibium's record format, for player.vibium.dev, `hit-test` — which view UIKit would really give a tap, below accessibility (iOS; before every tap with `launch --hit-test` on a simulator), `audit` — Apple's own accessibility audit of the screen (iOS), `doctor` | | Batches | `batch` runs a known sequence of calls in one, each checked before the first runs, stopping at the first failure | [docs/API.md](docs/API.md) lists every tool and which front door reaches it, @@ -172,13 +172,12 @@ happened rather than on an exit code. | two fingers, drag, double tap | yes | no | yes | | a screen that never stops moving | fine | cannot read it | fine | -**Android** uses [Appium's UiAutomator2 server](https://github.com/appium/appium-uiautomator2-server) -directly over HTTP — the same device-side server Appium uses, with no Node in -between. Pick `--driver uiautomator` when you cannot install anything on the +**Android** uses the [UiAutomator2 server](https://github.com/appium/appium-uiautomator2-server) +directly over HTTP, with no Node in between. Pick `--driver uiautomator` when you cannot install anything on the device; it reads through `uiautomator dump`, which waits for the screen to go idle and so cannot read one that animates. -**iOS simulators** use Appium's prebuilt +**iOS simulators** use the prebuilt [WebDriverAgent](https://github.com/appium/WebDriverAgent) runner, installed with `simctl`. **A real iPhone** takes the same backend: turn on Developer Mode and Settings > Developer > Enable UI Automation, add an Apple ID to @@ -299,8 +298,7 @@ err = dev.Tap(ctx, el.Ref) ``` `start` opens the session on the device and launches the app fresh; `quit` -ends it and puts back anything it changed for the session, as Appium's new -session and quit do. On the command line they are `mobium session start` and +ends it and puts back anything it changed for the session. On the command line they are `mobium session start` and `mobium session end`. Every client spawns `mobium pipe`, which forwards to the shared daemon: a diff --git a/clients/dotnet/Mobium/Device.cs b/clients/dotnet/Mobium/Device.cs index c2128943..7d8bfc79 100644 --- a/clients/dotnet/Mobium/Device.cs +++ b/clients/dotnet/Mobium/Device.cs @@ -100,7 +100,7 @@ public IList Find(string locator) => Elements("app_find", Args("locator", locator)); /// - /// The raw hierarchy — what Appium calls the page source — for when + /// The raw hierarchy — the page source — for when /// leaves out the thing you need to see; map is what /// to act on. source is the platform's XML, or in a WebView the /// page's markup; units is "px" on Android and "pt" on iOS, where @@ -1009,8 +1009,8 @@ public void IncomingCall(string action, string number) => /// /// Stops the trace and saves it at , a .zip on - /// this machine, in the Playwright trace format that - /// trace.playwright.dev and player.vibium.dev open. A relative path is + /// this machine, in Vibium's record format, which player.vibium.dev + /// opens. A relative path is /// this process's. Throws when no trace is running. /// /// @@ -1072,7 +1072,7 @@ public string Eval(string expression) => /// /// The current WebView's cookies: the ones its page's URL is sent, /// HttpOnly ones included. Needs a web context — Context first. - /// Each has Playwright's and Vibium's keys: name, value, domain, path, + /// Each has Vibium's keys: name, value, domain, path, /// expires (seconds since the epoch, absent for a session cookie), /// httpOnly, secure and sameSite. /// @@ -1097,8 +1097,8 @@ public void ClearCookies(string? name = null) => Data("app_cookies", string.IsNullOrEmpty(name) ? Args("action", "clear") : Args("action", "clear", "name", name)); /// - /// The current page's storage state, in the shape Playwright and - /// Vibium save: cookies, and origins with origin, localStorage and + /// The current page's storage state, in the shape Vibium saves: + /// cookies, and origins with origin, localStorage and /// sessionStorage. /// public IDictionary Storage() @@ -1205,8 +1205,7 @@ public void Dispose() } /// - /// Ends the session on the device, as Appium's quit does, and closes - /// the connection. The teardown is the daemon's own: accessibility + /// Ends the session on the device and closes the connection. The teardown is the daemon's own: accessibility /// settings put back, a recording or route stopped, WebViews detached, /// the device-side server stopped, and the app Start launched, if any, /// stopped too. Quitting a session that is not open succeeds, and a @@ -1381,8 +1380,7 @@ public DeviceBuilder CallTimeout(TimeSpan timeout) public DeviceBuilder App(string id) { _app = id ?? ""; return this; } /// - /// Connects and opens the session on the device, as Appium's new - /// session does: the device-side server is started now and, given an + /// Connects and opens the session on the device: the device-side server is started now and, given an /// , it is launched and in front when this returns. /// /// diff --git a/clients/dotnet/Mobium/Mobium.csproj b/clients/dotnet/Mobium/Mobium.csproj index c7a3cb91..10f3fc7c 100644 --- a/clients/dotnet/Mobium/Mobium.csproj +++ b/clients/dotnet/Mobium/Mobium.csproj @@ -35,7 +35,7 @@ https://github.com/mobiumdev/mobium https://github.com/mobiumdev/mobium git - mobile;automation;testing;android;ios;appium;uiautomator2;webdriveragent;mcp + mobile;automation;testing;android;ios;uiautomator2;webdriveragent;mcp README.md icon.png diff --git a/clients/dotnet/README.md b/clients/dotnet/README.md index fe5e5eb2..7b714576 100644 --- a/clients/dotnet/README.md +++ b/clients/dotnet/README.md @@ -14,8 +14,8 @@ device.Type("role=input", "someone@example.com"); // the using block quits: the session on the device ends here ``` -`Start()` opens the session on the device and launches the app fresh, as -Appium's new session does; `Quit()` — or the end of the `using` block — ends +`Start()` opens the session on the device and launches the app fresh; +`Quit()` — or the end of the `using` block — ends it. `Device.Connect()` opens a connection without touching the device, and disposing it leaves the session open for whoever started it. The [quick start](https://github.com/mobiumdev/mobium/blob/main/docs/quickstart/dotnet.md) walks through it on Android diff --git a/clients/go/README.md b/clients/go/README.md index 476348f5..2c2282c4 100644 --- a/clients/go/README.md +++ b/clients/go/README.md @@ -22,8 +22,8 @@ elements, err := dev.Map(ctx) // find a row by its label, tap its ref, wait for the next screen ... ``` -`Start` opens a session on the device and launches the app fresh, as -Appium's new session does; `Quit` ends it. `WithPlatform("ios")` drives an +`Start` opens a session on the device and launches the app fresh; +`Quit` ends it. `WithPlatform("ios")` drives an iOS simulator or iPhone the same way. - [Quick start for Go](https://github.com/mobiumdev/mobium/blob/main/docs/quickstart/go.md) diff --git a/clients/go/mobium.go b/clients/go/mobium.go index 8c3e609c..e2f28e60 100644 --- a/clients/go/mobium.go +++ b/clients/go/mobium.go @@ -7,8 +7,8 @@ // // go install github.com/mobiumdev/mobium/cmd/mobium@latest // -// Start opens a session on the device and launches the app fresh, as Appium's -// new session does; Quit ends it: +// Start opens a session on the device and launches the app fresh; Quit ends +// it: // // ctx := context.Background() // dev, err := mobium.Start(ctx, mobium.WithPlatform("android"), mobium.WithApp("com.example.shop")) @@ -164,8 +164,8 @@ type Session struct { App string `json:"app"` } -// Start connects and opens the session on the device, as Appium's new -// session does: the device-side server is started now, and the app, if one +// Start connects and opens the session on the device: the device-side +// server is started now, and the app, if one // was named with WithApp, launched and in front. End it with Quit. // // Nothing requires it — every call opens a session on first use — but it puts @@ -200,8 +200,7 @@ func Start(ctx context.Context, opts ...Option) (*Device, error) { // nil for a Device from Connect. func (d *Device) Session() *Session { return d.started } -// Quit ends the session on the device, as Appium's quit does, and closes the -// connection. The session's teardown is the daemon's own: accessibility +// Quit ends the session on the device and closes the connection. The session's teardown is the daemon's own: accessibility // settings put back, a recording or route stopped, WebViews detached, the // device-side server stopped, and the app Start launched, if any, stopped // too. Quitting a session that is not open succeeds, and a second Quit — a @@ -685,8 +684,8 @@ type PageSource struct { Redacted int `json:"redacted"` } -// Source returns the raw hierarchy — what Appium calls the page source — for -// when Map leaves out the thing you need to see. Map is what to act on. +// Source returns the raw hierarchy — the page source — for when Map leaves +// out the thing you need to see. Map is what to act on. func (d *Device) Source(ctx context.Context) (PageSource, error) { var out PageSource err := d.data(ctx, "app_source", map[string]any{}, &out) @@ -1758,9 +1757,8 @@ func (d *Device) TraceStart(ctx context.Context, opts *TraceOptions) (*Trace, er return &out, nil } -// TraceStop ends the trace and saves it to path as a zip in the Playwright -// trace format, which trace.playwright.dev and player.vibium.dev open. A -// relative path is this process's: `mobium pipe` resolves it before the +// TraceStop ends the trace and saves it to path as a zip in Vibium's record +// format, which player.vibium.dev opens. A relative path is this process's: `mobium pipe` resolves it before the // daemon sees it. func (d *Device) TraceStop(ctx context.Context, path string) (*Trace, error) { if path == "" { @@ -1886,8 +1884,8 @@ func (d *Device) Eval(ctx context.Context, expression string) (string, error) { return out.Value, nil } -// Cookie is one of a page's cookies. The JSON keys are Playwright's and -// Vibium's, so a storage state saved by either restores here. +// Cookie is one of a page's cookies. The JSON keys are Vibium's, so a +// storage state Vibium saved restores here. type Cookie struct { Name string `json:"name"` Value string `json:"value"` @@ -1914,8 +1912,8 @@ type OriginStorage struct { SessionStorage []StorageItem `json:"sessionStorage"` } -// StorageState is a page's cookies and web storage, in the shape Playwright -// and Vibium save. +// StorageState is a page's cookies and web storage, in the shape Vibium +// saves. type StorageState struct { Cookies []Cookie `json:"cookies"` Origins []OriginStorage `json:"origins"` diff --git a/clients/java/README.md b/clients/java/README.md index e94f66a3..563b90b5 100644 --- a/clients/java/README.md +++ b/clients/java/README.md @@ -17,8 +17,8 @@ try (Mobium device = Mobium.builder().platform("android").app("com.example.shop" } // try-with-resources quits: the session on the device ends here ``` -`start()` opens the session on the device and launches the app fresh, as -Appium's new session does; `quit()` — or the end of try-with-resources — ends +`start()` opens the session on the device and launches the app fresh; +`quit()` — or the end of try-with-resources — ends it. `Mobium.connect()` opens a connection without touching the device, and its `close()` leaves the session open for whoever started it. The [quick start](../../docs/quickstart/java.md) walks through it on Android and diff --git a/clients/java/src/main/java/dev/mobium/Mobium.java b/clients/java/src/main/java/dev/mobium/Mobium.java index b722482f..0b8385a3 100644 --- a/clients/java/src/main/java/dev/mobium/Mobium.java +++ b/clients/java/src/main/java/dev/mobium/Mobium.java @@ -156,8 +156,7 @@ public Builder callTimeout(Duration timeout) { public Builder session(String name) { this.session = name; return this; } /** - * Connects and opens the session on the device, as Appium's new - * session does: the device-side server is started now and, given an + * Connects and opens the session on the device: the device-side server is started now and, given an * {@link #app}, it is launched and in front when this returns. * *

Nothing requires it -- every call opens a session on first use -- @@ -260,7 +259,7 @@ public List find(String locator) { } /** - * The raw hierarchy — what Appium calls the page source — for when + * The raw hierarchy — the page source — for when * {@link #map} leaves out the thing you need to see; map is what to act * on. {@code source} is the platform's XML, or in a WebView the page's * markup; {@code units} is "px" on Android and "pt" on iOS, where map, taps @@ -1598,8 +1597,8 @@ public Map traceStart(String name, boolean screenshots, boolean } /** - * Stops the trace and saves it as a zip in the Playwright trace format, - * which trace.playwright.dev and player.vibium.dev open. A relative path + * Stops the trace and saves it as a zip in Vibium's record format, + * which player.vibium.dev opens. A relative path * is this process's. * * @param path where to save the trace on this machine, a {@code .zip} @@ -1685,7 +1684,7 @@ public String eval(String expression) { /** * The current WebView's cookies: the ones its page's URL is sent, HttpOnly * ones included. Needs a web context -- {@link #context(String)} first. - * Each map has Playwright's and Vibium's keys: name, value, domain, path, + * Each map has Vibium's keys: name, value, domain, path, * expires (seconds since the epoch, absent for a session cookie), * httpOnly, secure and sameSite. * @@ -1726,8 +1725,7 @@ public void clearCookies(String... name) { } /** - * The current page's storage state, in the shape Playwright and Vibium - * save: cookies, and origins, each with origin, localStorage and + * The current page's storage state, in the shape Vibium saves: cookies, and origins, each with origin, localStorage and * sessionStorage. * * @return the storage state @@ -1874,8 +1872,7 @@ public Map call(String tool, Map arguments) { public Session session() { return session; } /** - * Ends the session on the device, as Appium's quit does, and closes the - * connection. The teardown is the daemon's own: accessibility settings put + * Ends the session on the device and closes the connection. The teardown is the daemon's own: accessibility settings put * back, a recording or route stopped, WebViews detached, the device-side * server stopped, and the app {@code start()} launched, if any, stopped * too. Quitting a session that is not open succeeds, and a second quit -- diff --git a/clients/javascript/README.md b/clients/javascript/README.md index f9a227c7..11a1b04b 100644 --- a/clients/javascript/README.md +++ b/clients/javascript/README.md @@ -20,8 +20,8 @@ try { } ``` -`start()` opens a session on the device and launches the app fresh, as -Appium's new session does; `quit()` ends it. `platform: 'ios'` drives an iOS +`start()` opens a session on the device and launches the app fresh; +`quit()` ends it. `platform: 'ios'` drives an iOS simulator or iPhone the same way. ## Requirements diff --git a/clients/javascript/index.d.ts b/clients/javascript/index.d.ts index 629ed877..2075081b 100644 --- a/clients/javascript/index.d.ts +++ b/clients/javascript/index.d.ts @@ -87,7 +87,7 @@ export interface Session { app: string } -/** One of a page's cookies, with Playwright's and Vibium's keys. */ +/** One of a page's cookies, with Vibium's keys. */ export interface Cookie { name: string value: string @@ -102,7 +102,7 @@ export interface Cookie { sameSite?: 'Strict' | 'Lax' | 'None' } -/** A page's cookies and web storage, in the shape Playwright and Vibium save. */ +/** A page's cookies and web storage, in the shape Vibium saves. */ export interface StorageState { cookies: Cookie[] origins: { @@ -208,7 +208,7 @@ export interface WaitOptions { // -- connecting ------------------------------------------------------------ /** - * Connect and open the session on the device, as Appium's new session does. + * Connect and open the session on the device. * End it with `quit()`. */ export function start(options?: StartOptions): Promise @@ -349,7 +349,7 @@ export class Device { crashes(options?: { app?: string; limit?: number }): Promise crash(id: string): Promise record(options?: { action?: 'start' | 'stop'; path?: string }): Promise - /** Start, stop or ask about a trace; stop with a path saves a Playwright trace zip. */ + /** Start, stop or ask about a trace; stop with a path saves a zip in Vibium's record format. */ traceStart(options?: { name?: string; screenshots?: boolean; maps?: boolean }): Promise traceStop(path: string): Promise trace(): Promise @@ -377,8 +377,7 @@ export class Device { /** The sessions open on the daemon. */ sessions(): Promise<{ device: string; platform: string; driver: string }[]> /** - * End the session on the device, as Appium's quit does, and close the - * connection. The app start() launched, if any, is stopped too. + * End the session on the device and close the connection. The app start() launched, if any, is stopped too. */ quit(): Promise /** Close the connection; the session stays open. Resolves once mobium has exited. */ diff --git a/clients/javascript/index.js b/clients/javascript/index.js index c93dcc3d..a1068655 100644 --- a/clients/javascript/index.js +++ b/clients/javascript/index.js @@ -216,8 +216,7 @@ function toElements(data) { } /** - * Connect and open the session on the device, as Appium's new session does: - * the device-side server is started now and, given an app, it is launched and + * Connect and open the session on the device: the device-side server is started now and, given an app, it is launched and * in front when this resolves. End it with `quit()`. * * `platform` is "android" or "ios"; "ios" picks the wda driver, so none need @@ -562,7 +561,7 @@ export class Device { } /** - * The raw hierarchy — what Appium calls the page source — for when map + * The raw hierarchy — the page source — for when map * leaves out the thing you need to see; map is what to act on. `source` is * the platform's XML, or in a WebView the page's markup; `format` is "xml" * or "html"; `units` is "px" on Android and "pt" on iOS, where map, taps and @@ -1428,8 +1427,8 @@ export class Device { } /** - * Stop the trace and save it to `path`: a zip in the Playwright trace - * format, which trace.playwright.dev and player.vibium.dev open. A relative + * Stop the trace and save it to `path`: a zip in Vibium's record + * format, which player.vibium.dev opens. A relative * path is this process's. */ async traceStop(path) { @@ -1488,7 +1487,7 @@ export class Device { /** * The current WebView's cookies: the ones its page's URL is sent, HttpOnly * ones included. Needs a web context — context() first. Each has - * Playwright's and Vibium's keys: name, value, domain, path, expires + * Vibium's keys: name, value, domain, path, expires * (seconds since the epoch, absent for a session cookie), httpOnly, secure, * sameSite. */ @@ -1511,8 +1510,7 @@ export class Device { } /** - * The current page's storage state, in the shape Playwright and Vibium - * save: { cookies, origins: [{ origin, localStorage, sessionStorage }] }. + * The current page's storage state, in the shape Vibium saves: { cookies, origins: [{ origin, localStorage, sessionStorage }] }. */ async storage() { const data = (await this.#data('app_storage', { action: 'get' })) || {} @@ -1594,8 +1592,7 @@ export class Device { } /** - * Ends the session on the device, as Appium's quit does, and closes the - * connection. The teardown is the daemon's own: accessibility settings put + * Ends the session on the device and closes the connection. The teardown is the daemon's own: accessibility settings put * back, a recording or route stopped, WebViews detached, the device-side * server stopped, and the app start() launched, if any, stopped too. * Quitting a session that is not open succeeds, and a second quit does diff --git a/clients/javascript/package.json b/clients/javascript/package.json index 13ef65c8..d0c3834b 100644 --- a/clients/javascript/package.json +++ b/clients/javascript/package.json @@ -2,7 +2,7 @@ "name": "mobium", "version": "0.1.0", "description": "Drive native apps on Android emulators, Android phones, iOS simulators and iPhones. No dependencies.", - "keywords": ["mobile", "automation", "testing", "android", "ios", "appium", "uiautomator2", "webdriveragent", "mcp"], + "keywords": ["mobile", "automation", "testing", "android", "ios", "uiautomator2", "webdriveragent", "mcp"], "homepage": "https://github.com/mobiumdev/mobium/blob/main/docs/quickstart/javascript.md", "bugs": "https://github.com/mobiumdev/mobium/issues", "repository": { diff --git a/clients/python/README.md b/clients/python/README.md index ad6ff0db..156fc3b1 100644 --- a/clients/python/README.md +++ b/clients/python/README.md @@ -18,8 +18,8 @@ with start(platform="android", app="com.android.settings") as device: # the with block has quit: the session on the device is over ``` -`start()` opens a session on the device and launches the app fresh, as -Appium's new session does; `quit()` — or leaving the `with` block — ends it. +`start()` opens a session on the device and launches the app fresh; +`quit()` — or leaving the `with` block — ends it. `platform="ios"` drives an iOS simulator or iPhone the same way. ## Requirements diff --git a/clients/python/mobium/_device.py b/clients/python/mobium/_device.py index 2ddb294a..9f9b3c1d 100644 --- a/clients/python/mobium/_device.py +++ b/clients/python/mobium/_device.py @@ -122,7 +122,7 @@ def start( call_timeout: float | None = None, session: str | None = None, ) -> "Device": - """Connect and open the session on the device, as Appium's new session does. + """Connect and open the session on the device. platform: "android" or "ios"; "ios" picks wda, so the driver need not be named. @@ -174,8 +174,7 @@ def close(self) -> None: self._conn.close() def quit(self) -> None: - """End the session on the device, as Appium's quit does, and close the - connection. + """End the session on the device and close the connection. The teardown is the daemon's own: accessibility settings put back, a recording or route stopped, WebViews detached, the device-side server @@ -286,8 +285,7 @@ def clear_dialog_rules(self) -> None: self._call("app_dialogs", {"clear": True}) def source(self) -> dict: - """The raw hierarchy — what Appium calls the page source — for when - map leaves out the thing you need to see. map is what to act on. + """The raw hierarchy — the page source — for when map leaves out the thing you need to see. map is what to act on. ``source`` is the platform's XML, or in a WebView the page's markup; ``format`` is "xml" or "html"; ``units`` is "px" on Android and "pt" @@ -1151,8 +1149,8 @@ def trace_start( return self._data("app_trace", args) or {} def trace_stop(self, path: str) -> dict: - """Stop the trace and save it to ``path``: a zip in the Playwright - trace format, which trace.playwright.dev and player.vibium.dev open. + """Stop the trace and save it to ``path``: a zip in Vibium's + record format, which player.vibium.dev opens. ``mobium pipe`` makes a relative path absolute. Returns ``calls``, ``path`` and ``bytes``. """ @@ -1214,7 +1212,7 @@ def cookies(self) -> list[dict]: """The current WebView's cookies: the ones its page's URL is sent, HttpOnly ones included. Needs a web context -- ``context()`` first. - Each is a dict with Playwright's and Vibium's keys: ``name``, + Each is a dict with Vibium's keys: ``name``, ``value``, ``domain``, ``path``, ``expires`` (seconds since the epoch, absent for a session cookie), ``httpOnly``, ``secure``, ``sameSite``. """ @@ -1236,8 +1234,7 @@ def clear_cookies(self, name: str | None = None) -> None: self._data("app_cookies", args) def storage(self) -> dict: - """The current page's storage state, in the shape Playwright and - Vibium save: ``{"cookies": [...], "origins": [{"origin", + """The current page's storage state, in the shape Vibium saves: ``{"cookies": [...], "origins": [{"origin", "localStorage", "sessionStorage"}]}``.""" data = self._data("app_storage", {"action": "get"}) or {} return data.get("state") or {"cookies": [], "origins": []} diff --git a/clients/python/pyproject.toml b/clients/python/pyproject.toml index 216cbf69..7fe3d142 100644 --- a/clients/python/pyproject.toml +++ b/clients/python/pyproject.toml @@ -12,7 +12,7 @@ requires-python = ">=3.9" license = "MIT" license-files = ["LICENSE"] authors = [{ name = "Lana Begunova" }] -keywords = ["mobile", "automation", "testing", "android", "ios", "appium", "uiautomator2", "webdriveragent", "mcp"] +keywords = ["mobile", "automation", "testing", "android", "ios", "uiautomator2", "webdriveragent", "mcp"] classifiers = [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", diff --git a/cmd/mobium/cookies.go b/cmd/mobium/cookies.go index d8e4faa8..0123b33b 100644 --- a/cmd/mobium/cookies.go +++ b/cmd/mobium/cookies.go @@ -78,8 +78,8 @@ func newStorageCmd() *cobra.Command { Short: "Save, restore or clear the current WebView's cookies and web storage", Long: "Vibium's storage command, on a WebView — `mobium context WEBVIEW_...` first.\n\n" + "With no argument, prints the page's storage state — its cookies, and its\n" + - "origin's localStorage and sessionStorage — in the shape Playwright and\n" + - "Vibium save, so a state saved by one restores in another; -o writes it to a\n" + + "origin's localStorage and sessionStorage — in the shape Vibium saves, so a\n" + + "state saved by one restores in the other; -o writes it to a\n" + "file. `restore` sets a saved state's cookies and writes each origin's\n" + "storage only into a page on that origin. `clear` empties all three.", Example: ` mobium storage -o state.json diff --git a/cmd/mobium/session.go b/cmd/mobium/session.go index 94c792bd..2d291eda 100644 --- a/cmd/mobium/session.go +++ b/cmd/mobium/session.go @@ -10,14 +10,13 @@ func newSessionCmd() *cobra.Command { // command, since it could mean one device's session, every device's, // or one app. The three are suggested instead of one being guessed. SuggestFor: []string{"stop"}, - Long: "The explicit start and end of a device session, as Appium's new session\n" + - "and quit are. Never required: every other command opens a session on\n" + + Long: "The explicit start and end of a device session. Never required: every other command opens a session on\n" + "first use.\n\n" + "start opens it now, so the slow first start — installing UiAutomator2,\n" + "building WebDriverAgent on an iPhone — happens here rather than inside\n" + "your first tap. --platform ios picks wda; --app launches an\n" + "app fresh once the session is up: stopped first if it was running,\n" + - "as Appium does, so the session begins at its first screen. Its data\n" + + "so the session begins at its first screen. Its data\n" + "is kept.\n\n" + "end closes one device's session with the daemon's own teardown:\n" + "accessibility settings put back, a recording or route stopped, WebViews\n" + diff --git a/cmd/mobium/test.go b/cmd/mobium/test.go index 51f37c8f..a410e1b5 100644 --- a/cmd/mobium/test.go +++ b/cmd/mobium/test.go @@ -243,7 +243,7 @@ func newTestCmd() *cobra.Command { f.BoolVar(&noShot, "no-screenshots", false, "Keep no screenshot of a failure — on a real phone it is somebody's screen") f.StringVar(&configPath, "config", "", "The config to use (default: mobium.config.json here or above)") f.StringVar(&outDir, "output", "", "Where reports go (default: mobium-report beside the config)") - f.StringVar(&trace, "trace", "off", "Keep a screenshot and the map after every step, and the test as a Playwright trace zip: on, off, or retain-on-failure") + f.StringVar(&trace, "trace", "off", "Keep a screenshot and the map after every step, and the test as a recording in Vibium's record format: on, off, or retain-on-failure") f.BoolVar(&debug, "debug", false, "Stop before each step, show it and the screen, and wait: Enter steps, c continues, q quits") f.BoolVar(&ui, "ui", false, "Serve a page on this machine to pick tests, run them and watch each step (docs/decisions/0009)") f.IntVar(&uiPort, "ui-port", 0, "With --ui, the port on 127.0.0.1 (default: any free one)") diff --git a/cmd/mobium/text.go b/cmd/mobium/text.go index 270877f6..53a81e83 100644 --- a/cmd/mobium/text.go +++ b/cmd/mobium/text.go @@ -24,7 +24,7 @@ func newSourceCmd() *cobra.Command { return &cobra.Command{ Use: "source", Short: "Print the raw hierarchy, as the device-side server sent it", - Long: "What Appium calls the page source: the platform's own XML on a native screen,\n" + + Long: "The page source: the platform's own XML on a native screen,\n" + "the page's current markup in a WebView context. `map` is what to act on; this is\n" + "for when map leaves out the thing you need to see.\n\n" + "Password fields have their contents hidden, keeping the length. Geometry is in\n" + diff --git a/cmd/mobium/trace.go b/cmd/mobium/trace.go index a19370c2..c36e6065 100644 --- a/cmd/mobium/trace.go +++ b/cmd/mobium/trace.go @@ -12,18 +12,18 @@ func newTraceCmd() *cobra.Command { var noShots, noMaps bool cmd := &cobra.Command{ Use: "trace [start | stop]", - Short: "Record a session as a trace, for the Playwright trace viewer", + Short: "Record a session as a trace, in Vibium's record format", Long: "`trace start` begins; every call on the device is then a step, with the\n" + "screen after it and the map's elements drawn over it. `trace stop -o t.zip`\n" + - "saves a zip in the Playwright trace format, which trace.playwright.dev and\n" + - "player.vibium.dev open. `trace` alone says whether one is running.\n\n" + + "saves a zip in Vibium's record format, which player.vibium.dev opens.\n" + + "`trace` alone says whether one is running.\n\n" + "Text typed into a field is not recorded, only its length. On a real phone\n" + "the screenshots are its owner's screen: --no-screenshots keeps none.", Example: ` mobium trace start --name "sign in" mobium tap "label=Login Demo" mobium fill testid=username mobium mobium trace stop -o sign-in.zip - # open sign-in.zip at https://trace.playwright.dev`, + # open sign-in.zip at https://player.vibium.dev`, Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { call := map[string]interface{}{} diff --git a/docs/CHALLENGES.md b/docs/CHALLENGES.md index 3dd3d04c..d92bf013 100644 --- a/docs/CHALLENGES.md +++ b/docs/CHALLENGES.md @@ -158,7 +158,7 @@ else — a rule that had been copied without being understood. *session* being gone is invisible to it. The shared W3C client now recovers: a call failing with "invalid session id" reopens the session, rewrites the dead id out of the request path, and retries once. Without it, anything else -attaching to the device — a second Mobium, or Appium — breaks every subsequent +attaching to the device — a second Mobium, or another tool — breaks every subsequent command until the daemon restarts. ### 9. Stale sessions across emulator restarts @@ -1360,7 +1360,7 @@ route does not exist. UiAutomator2's own endpoints do: a POST to It answers `""` whatever the clipboard holds. Since Android 10 only an app with focus may read the clipboard, and the UiAutomator2 server has no activity of its own; foregrounding a different app does not help, because the restriction -is on the *reading* app. Appium works around it with a separate helper +is on the *reading* app. Working around it takes a separate helper application. Mobium installs no such thing, which is the whole bet, so the read is genuinely unavailable here. @@ -2216,7 +2216,7 @@ reading them as the server's problem rather than Mobium's. The server's own `/shutdown` does not exist in 10.6.6 (measured: unknown command). A force-stop of both its packages, before the host is cancelled, -ends it with no record — Appium stops it the same way. Measured after the +ends it with no record. Measured after the fix: three sessions, three stops, and a SIGTERM with a session live, the dropbox count unchanged at 12 and no server process left. Only a server this session started is stopped, as on iOS. @@ -2815,7 +2815,7 @@ center is aimed around at the clear point nearest it, as a native target is (115). A check that fails is waited out within the implicit wait and then refused as "`@e7` failed check receivesEvents: covered by "full cover"". `aria-disabled` is refused although the page's handler would have run, -because Playwright and Vibium refuse it and a page that honors the attribute +because Vibium refuses it and a page that honors the attribute would not act. Unlike a native tree, a page hit-tests, so the plain div that a native screen can only report is refused here. @@ -3510,7 +3510,7 @@ after verifying the source and before building, refuses to build if the line it attaches to is gone, and rebuilds a phone's runner built before the patch. After the rebuild both ports answered over the tunnel and both refused the Wi-Fi address, and `ios-device.sh` passed. The simulator's runner is -Appium's prebuilt release, unpatched; there the Mac's firewall is the +the prebuilt release, unpatched; there the Mac's firewall is the mitigation (152). A runner already running when a session starts is used rather than started @@ -3541,7 +3541,7 @@ that is not a result for the same reason: nothing known to answer there was tried first. Unlike WebDriverAgent (153), the server has no setting that chooses an -interface: it calls Netty's `bind(port)`, and Mobium installs Appium's +interface: it calls Netty's `bind(port)`, and Mobium installs the prebuilt APK rather than building it. Binding it to `127.0.0.1` would lose nothing — `adb forward` reaches the server on the device's localhost — so the fix is upstream: a bind address the server reads, as WebDriverAgent @@ -3863,7 +3863,7 @@ and on Android that test can never fail once any of the target is in: a child's bounds are clipped to its container, so a card 683 pixels wide of which 101 showed reported `[937,476][1038,896]`, inside the pager. It was reachable — a tap there presses it, which is all `mobium-app.sh` asked — but -not shown, and Playwright's scroll-into-view brings the whole element in. Two +not shown, and scrolling an element into view should bring the whole of it in. Two signs mark clipped bounds together: flush against the container's edge on the scroll axis, and shorter along it than a sibling of the same kind. A whole row can sit flush, the same height as its neighbors, so flush alone is not @@ -3885,9 +3885,9 @@ A rule (`app_dialogs`) answered a dialog only when an action resolved its target and found the dialog over it. Sign-in is a tap, and iOS raises the sheet a moment after the tap has returned, so the next call to meet it was the wait, which reported it and timed out. On a simulator the sheet does not -come, which is why the suite passed there. Playwright's locator handlers run -before an auto-retrying assertion as well as an action, and a wait is -Mobium's assertion. So `app_wait_for` now answers a rule for a dialog over +come, which is why the suite passed there. A dialog rule should run before +an auto-retrying assertion as well as an action, and a wait is Mobium's +assertion. So `app_wait_for` now answers a rule for a dialog over its target, or, on Android, where the tree holds only the dialog's window, when its target is not there at all. It is bounded as an action is, and reported in `dialogs_handled` as an action is. A wait for the target to go @@ -4218,7 +4218,7 @@ MobiumApp in front, attached. ### 189. Another tool removed Mobium's runner from the iPhone, and Mobium put it back in silence **Found by:** comparing another tool's session on the iPhone 15 Plus, -2026-09-30. Before installing its own WebDriverAgent, appium-xcuitest-driver +2026-09-30. Before installing its own WebDriverAgent, that tool uninstalls every user app whose `CFBundleName` is `WebDriverAgentRunner-Runner` except its own, whatever the bundle id. Mobium's runner is built from WebDriverAgent's source and carried that name, so it went, along with runners @@ -4239,9 +4239,9 @@ between sessions, the next one said "Mobium's WebDriverAgent … is no longer installed on iPhone 15 Plus — something removed it since the last session" and started; and the session after that said nothing. -The sweep was then run on the phone: appium-xcuitest-driver 12.13.3's own -lookup and removal, called directly, without the install of Appium's runner -that follows it. The phone held no runner but Mobium's. As a positive +The sweep was then run on the phone: the other tool's own lookup and +removal, called directly, without the install of its own runner that +follows it. The phone held no runner but Mobium's. As a positive control, Mobium's runner was first built and installed under the old name; the sweep listed it and removed it. A Mobium session then announced it missing and installed `MobiumWDA-Runner`, and the same sweep listed nothing @@ -4702,8 +4702,8 @@ Worth recording because each one closed off an approach that looked obvious. - **A WKWebView is unreachable unless the app opted in, and no amount of driving changes that.** On iOS 16.4+ WebKit only publishes a target for a - `WKWebView` whose owner set `isInspectable`. Measured on Appium's TheApp - v1.12.0 — a real React Native hybrid app, installed and running on iOS 26.5, + `WKWebView` whose owner set `isInspectable`. Measured on TheApp + v1.12.0, a third-party demo app — a real React Native hybrid app, installed and running on iOS 26.5, page loaded and rendering — which produces zero attachable contexts. Writing `WebKitDeveloperExtrasEnabledPreferenceKey` into the *app's own* defaults domain does nothing; that key is Safari's. So this is not something a better @@ -4728,7 +4728,7 @@ Worth recording because each one closed off an approach that looked obvious. knowing before writing a rule tuned on Settings, where one label is one node. - **`map` labels an empty text input with its placeholder.** A URL field - containing nothing printed as `https://appiumpro.com (input)`, which reads + containing nothing printed as its placeholder URL followed by `(input)`, which reads exactly like a field already filled in. It cost two wrong turns here — a "Go" button was tapped twice against an empty field — before a screenshot showed the text was gray. Not wrong, since a placeholder is the best label an diff --git a/docs/PHILOSOPHY.md b/docs/PHILOSOPHY.md index c17eee4d..89da2e9f 100644 --- a/docs/PHILOSOPHY.md +++ b/docs/PHILOSOPHY.md @@ -95,7 +95,6 @@ necessary changes made: | One locator vocabulary | every platform's element tree | compiled per platform, instead of a dialect per platform | | The built-in drivers | third-party drivers, as separate processes | only the platform layer; waiting, scrolling and refs come for free ([decision 0003](decisions/0003-drivers-are-processes-not-plugins.md)) | | The Go client's connection | the Python, JavaScript, Java and .NET clients | each language's idiom: a lock, a timeout, the same failure rules | -| Appium's session | `start` and `quit` on every surface | the names; the idea — open it, work, end it — is Appium's | The rule's negative form is the one that catches mistakes: **a proposal that duplicates a layer is almost always the wrong one.** Before adding a second diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index fd24bdcc..09229e00 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -96,21 +96,20 @@ this is what is not. on a phone, where Mobium could reach a probe only over the phone's network; it refuses, and `hit-test` there stays the debugger's. - ~~**Session recording and `diff map`.**~~ Done 2026-09-29. `mobium trace - start|stop` records a session as Vibium does: a zip in the Playwright - trace format, with every call a step, the screen after it and the map - drawn over it. trace.playwright.dev opens it (`docs/checks/trace.sh`, - measured with `MOBIUM_TRACE_VIEWER=1`). `mobium map --diff` answers what + start|stop` records a session as Vibium does: a zip in Vibium's record + format, with every call a step, the screen after it and the map drawn + over it (`docs/checks/trace.sh`). `mobium map --diff` answers what changed since the last map (`docs/checks/map-diff.sh`). Since 2026-10-01 `mobium test --trace` writes the same zip for each test it keeps, beside the filmstrip, and the HTML report links it; the runner's own screenshots and maps are sent with MCP's `_meta` marking them untraced, so the zip holds the test's calls alone (`test-runner.sh`). - And since 2026-10-01 it plays in Vibium's player, player.vibium.dev, as - well as trace.playwright.dev, checked on a simulator and an emulator by - `trace.sh` with `MOBIUM_TRACE_VIEWER=1`. Getting there: the player names a - fill by Playwright's `selector` and `value`, which Mobium did not send, so + And since 2026-10-01 it plays in Vibium's player, player.vibium.dev, + checked on a simulator and an emulator by `trace.sh` with + `MOBIUM_TRACE_VIEWER=1`. Getting there: the player names a fill by the + record format's `selector` and `value`, which Mobium did not send, so it read `Type "" into field` — they are recorded now, the value masked a - dot a character; and both viewers show at each step the frame kept after + dot a character; and the player shows at each step the frame kept after the one before, which after a launch was blank — an action's frame is now taken once the screen has settled, as `mobium test` reads its own. Next, if wanted: a batch's steps as a group in it. @@ -401,8 +400,8 @@ this is what is not. 3. **iOS second, and harder.** Mobium builds WebDriverAgent from source and signs it with a team from the local keychain; a farm's host has neither, and re-signs uploaded apps with its own identity. The route to find out - is whether the host provides a signed WebDriverAgent — farms that run - Appium must — and whether Mobium can be pointed at a runner it did not + is whether the host provides a signed WebDriverAgent — farms that drive + iOS must — and whether Mobium can be pointed at a runner it did not build. Until that is answered, iOS on a farm is a question, not a step. 4. **Budget.** A check takes two to five minutes of device time, so a trial of the size last seen covers a few hundred runs. Spend it on breadth — a diff --git a/docs/SETUP.md b/docs/SETUP.md index dd95491b..94d78dee 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -524,8 +524,8 @@ MP4, and none has been tried. ### WebViews and Safari -They work on a phone, reached through the same lockdown service Appium uses -and speaking the same protocol as a simulator's +They work on a phone, reached through the phone's lockdown service and +speaking the same protocol as a simulator's ([decisions/0002](decisions/0002-ios-webviews-are-reachable.md)). It needs the phone connected by cable — usbmuxd, which carries it, is USB — and: @@ -713,9 +713,9 @@ Nothing else, and nothing at all with `--driver uiautomator`. On an **iOS simulator**, `com.facebook.WebDriverAgentRunner.xctrunner`. On a **real iPhone**, `dev.mobium.wda..xctrunner`, signed for your team -and named MobiumWDA-Runner. Appium's XCUITest driver removes every runner -named WebDriverAgentRunner-Runner before installing its own, and leaves this -one alone (measured, CHALLENGES 189). If it +and named MobiumWDA-Runner. Another tool that installs its own WebDriverAgent +removed every runner named WebDriverAgentRunner-Runner before installing its +own, and left this one alone (measured, CHALLENGES 189). If it is removed anyway, the next session says so as it installs it again. Mobium stops it when the session ends; `mobium --device uninstall dev.mobium.wda..xctrunner` removes it. On the phone, also turn Enable UI diff --git a/docs/THREAT-MODEL.md b/docs/THREAT-MODEL.md index b016c278..77a18cb9 100644 --- a/docs/THREAT-MODEL.md +++ b/docs/THREAT-MODEL.md @@ -56,7 +56,7 @@ needs nothing more. | Server | Listens on | Reachable from | Lifetime | State | | --- | --- | --- | --- | --- | | UiAutomator2, the Mac end of `adb forward` | `127.0.0.1` | Any process of any user on the Mac — it returned the whole screen's hierarchy through the running session. Not from the LAN: refused | Stops with the daemon | Local exposure, **open**: UiAutomator2 has no authentication | -| UiAutomator2, on the device (port 6790, and its MJPEG stream on 7810) | **Every interface** (`*:6790`, `*:7810`) | **The LAN, on a real phone**: on the Pixel 8 Pro, from the Mac over Wi-Fi, the server answered "ready to accept commands" and the stream answered (CHALLENGES 154). On the emulator, only the device itself: its network is behind its own NAT. The cellular IPv6 address did not answer from the internet, with no positive control — not a result | Stops within 2s of the daemon stopping | **Open.** The server has no bind setting (Netty `bind(port)`) and Mobium installs Appium's prebuilt APK; the fix is upstream, a bind address it reads — written up with a tested patch in [upstream/](upstream/uiautomator2-server-binds-every-interface.md) — which Mobium would set to `127.0.0.1` since `adb forward` reaches the device's localhost. **Meanwhile:** starting a session on a real phone says so in its answer (`exposure`), and names `--driver uiautomator`, which runs no server — measured, a dump session added no listening socket. Whether an ordinary app on the device can reach the server: **inconclusive** — `su` to an app's uid keeps `su`'s groups and context, and a uid that should have had no network got through too, so the test could not fail | +| UiAutomator2, on the device (port 6790, and its MJPEG stream on 7810) | **Every interface** (`*:6790`, `*:7810`) | **The LAN, on a real phone**: on the Pixel 8 Pro, from the Mac over Wi-Fi, the server answered "ready to accept commands" and the stream answered (CHALLENGES 154). On the emulator, only the device itself: its network is behind its own NAT. The cellular IPv6 address did not answer from the internet, with no positive control — not a result | Stops within 2s of the daemon stopping | **Open.** The server has no bind setting (Netty `bind(port)`) and Mobium installs the project's prebuilt APK; the fix is upstream, a bind address it reads — written up with a tested patch in [upstream/](upstream/uiautomator2-server-binds-every-interface.md) — which Mobium would set to `127.0.0.1` since `adb forward` reaches the device's localhost. **Meanwhile:** starting a session on a real phone says so in its answer (`exposure`), and names `--driver uiautomator`, which runs no server — measured, a dump session added no listening socket. Whether an ordinary app on the device can reach the server: **inconclusive** — `su` to an app's uid keeps `su`'s groups and context, and a uid that should have had no network got through too, so the test could not fail | | WebDriverAgent server, simulator | `127.0.0.1` since `USE_IP` (was every interface) | Any process on the Mac; the LAN was refused after the change, and answered before it | Stops with the session | Local exposure, as UiAutomator2's | | WebDriverAgent MJPEG stream, simulator | **Every interface** — it ignores `USE_IP` | **The LAN**: an iPhone on the same Wi-Fi opened the Mac's address in Safari and got a live 1206×2622 frame of the simulator's screen | Stops with the session | **Open** in Mobium: it does not use the stream, and closing it needs WebDriverAgent to bind it as it binds the server ([upstream/](upstream/webdriveragent-mjpeg-ignores-use-ip.md)). Building the simulator's runner from the patched source, as the phone's is, does not work as things stand: a runner built by `xcodebuild` aborts under `simctl launch` for want of `lib_TestingInterop.dylib`, which only `xcodebuild`'s own launch supplies — so it would mean launching simulators the way phones are. **Mitigated by the macOS firewall, measured:** with the runner set to "Block incoming connections", the same probe from the iPhone got "the network connection was lost" while the Mac itself still read the stream. The firewall had allowed the runner by itself — "Automatically allow downloaded signed software" is on by default — and a reinstalled runner is a new path, allowed again unless that option is off | | WebDriverAgent server on a real iPhone (port 8100) | The CoreDevice tunnel's address since CHALLENGES 153 (was every interface) | Over the cable's tunnel only: the Wi-Fi address was refused after the change, and answered with the live session before it | Stopped within 2s of the daemon stopping | **Fixed**, measured on the iPhone 15 Plus. A runner already running is checked from the Mac at the phone's Wi-Fi address: Mobium's own is replaced when it answers there, and anyone else's is refused — measured both ways | diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index f19419cd..0a028136 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -20,7 +20,7 @@ Said here rather than in a footnote, because it is the first question anyone asks and the answer is structural rather than a gap in the work. Mobium drives iOS through `xcrun simctl` — 41 call sites in `internal/device` -alone — and through WebDriverAgent, which it installs as Appium's prebuilt +alone — and through WebDriverAgent, which it installs as the prebuilt `WebDriverAgentRunner-Build-Sim-arm64.zip`. `simctl` ships inside Xcode and Xcode is macOS-only; the artifact is a *simulator* build for Apple Silicon, and a simulator is a macOS process. There is no configuration, no port and no diff --git a/docs/checks/README.md b/docs/checks/README.md index 1b7063b5..16f974e7 100644 --- a/docs/checks/README.md +++ b/docs/checks/README.md @@ -43,7 +43,7 @@ Each script takes a device serial and exits non-zero on failure. | [netnewswire-ios.sh](netnewswire-ios.sh) | **A second third-party app on iOS**, NetNewsWire, built from its source for a simulator or from the App Store on a phone, and CHALLENGES 191–197 held against it: no XCUITest type names or disclosure-arrow names in labels, headers not buttons, the chosen search scope read as selected and its move seen by `map --diff`, the back button found apart from a link of the same name, `label=URL` refused naming `text=URL`, a row behind the toolbar scrolled out before it is tapped, and an article row's swipe actions revealed by `swipe left`, Star tapped by name, and the row unstarred again | | [compose-app.sh](compose-app.sh) | **A Jetpack Compose app**, Seal from F-Droid, the first Compose app driven here, and CHALLENGES 176–178 held against it. Its icon buttons map once each as buttons. Its first-launch dialog, which the platform's alert endpoint does not know, is read by `alert` and not accepted, a tap on what it covers is refused naming it, and a rule answers it by its Close button. A switch row is set by its words, read back and put back, and a row with no state is refused. An app the check installed is uninstalled after, and on a phone nothing read off it is printed. Emulators and phones | | [map-diff.sh](map-diff.sh) | **`map --diff`**, on MobiumApp's Form Demo. The first diff of a session says it had nothing to compare with and adds the whole screen. A map with nothing done between says nothing changed, the control that it can come back empty. A box checked is its state and what it was, and on iOS, where its row grows, what is under it moves as one line, not five. A screen left is its elements gone and the next screen's added, and a ref from the diff acts. Emulators and simulators | -| [trace.sh](trace.sh) | **`mobium trace`**, a sign-in on MobiumApp's Login Demo traced and the zip held to what the viewers read. context-options comes first with its name. Every call has a before and an after, and a failed tap carries its error. After every call there is a screencast frame with its image and a snapshot with the map drawn over it, and a tap's point is recorded. A typed password appears nowhere in the zip, only its length. A second start and a stop with none are refused. With `MOBIUM_TRACE_VIEWER=1` and Vibium installed, the zip is opened in Playwright's own viewer at trace.playwright.dev, and every step must be listed there. Emulators and simulators | +| [trace.sh](trace.sh) | **`mobium trace`**, a sign-in on MobiumApp's Login Demo traced and the zip held to Vibium's record format and what its player reads. context-options comes first with its name. Every call has a before and an after, and a failed tap carries its error. After every call there is a screencast frame with its image and a snapshot with the map drawn over it, and a tap's point is recorded. A typed password appears nowhere in the zip, only its length. A second start and a stop with none are refused. With `MOBIUM_TRACE_VIEWER=1` and Vibium installed, the zip is opened in Vibium's player at player.vibium.dev, which must count every call and name each step, a fill included. Emulators and simulators | | [accessibility.sh](accessibility.sh) | **Accessibility settings** through `app_accessibility`: every setting the platform has is changed, MobiumApp's Accessibility Demo is shown to be told of each it can see, what the platform lacks is refused with the alternative, and once the daemon stops every raw value is back as it was — an unset key unset again. On a real iPhone, where Mobium goes through the Settings app, each of the six switches is flipped from how it was found, and after the daemon stops every switch and what the app is told are back as they were (CHALLENGES 160); invert, grayscale and text size are refused naming Settings. Emulators, simulators and phones | | [login.sh](login.sh) | **The login demo** — mobile automation's hello world, on MobiumApp's Login screen, and the script to show when showing Mobium. Negative paths first, each judged by the message the app shows: an empty form, a username too short, one with characters it does not allow, a password too short, a wrong password and an unknown user, told apart by nothing. Then positive: one field valid while the other is not, a username sanitized on submit, the welcome screen waited for rather than slept for, and log-out. A typed password is never printed. If iOS raises "Save Password?" over the app, log-out is skipped and the dialog quoted, rather than a swallowed tap reported as a timeout | | [otp.sh](otp.sh) | **A one-time code**, on MobiumApp's OTP Demo: the code read where it arrives — the notification shade on Android, the banner on iOS, read through rather than landing on SpringBoard (CHALLENGES 155) — six one-digit boxes that move focus on, filled digit by digit and then as one string into the first box, which either arrives whole or names the digit that never did (156); no code, verified, already used, wrong twice, locked, and expired after `background 62`; and Resend refused while the screen disables it | diff --git a/docs/checks/test-runner.sh b/docs/checks/test-runner.sh index dfa44f26..f1d55d17 100755 --- a/docs/checks/test-runner.sh +++ b/docs/checks/test-runner.sh @@ -19,7 +19,7 @@ # - Iteration 2: the soft control fails with both of its soft failures and # still reaches its last step; a retain-on-failure trace keeps a failed # test's steps, each with a screenshot, and nothing of a passing one — and -# the failed test as a Playwright trace zip, holding its calls and none of +# the failed test as a recording in Vibium's record format, holding its calls and none of # the runner's own screenshots and maps; and # --debug, answered through a pipe, stops before each step and quits. # The suite's form.test.json is written in the step shorthand. @@ -166,17 +166,18 @@ if 'class="film"' not in open(os.path.join(out, "index.html")).read(): sys.exit("FAIL: the HTML report shows no filmstrip") print(" %-14s %-58s ok" % ("trace", "a failed test's every step kept; a passing test's, none")) -# The same test as a Playwright trace: a zip trace.playwright.dev opens, -# holding the test's calls and not the runner's own screenshots and maps. +# The same test as a recording in Vibium's record format: a zip +# player.vibium.dev opens, holding the test's calls and not the runner's own +# screenshots and maps. import zipfile for r in json.load(open(os.path.join(out, "results.json")))["results"]: zf = r.get("trace_file") if r["status"] == "passed": if zf: - sys.exit("FAIL: retain-on-failure kept a Playwright trace of %s, which passed" % r["title"]) + sys.exit("FAIL: retain-on-failure kept a recording of %s, which passed" % r["title"]) continue if not zf or not os.path.exists(os.path.join(out, zf)): - sys.exit("FAIL: %s has no Playwright trace (%r)" % (r["title"], zf)) + sys.exit("FAIL: %s has no recording (%r)" % (r["title"], zf)) with zipfile.ZipFile(os.path.join(out, zf)) as z: events = [json.loads(l) for l in z.read("trace.trace").decode().splitlines() if l.strip()] frames = [n for n in z.namelist() if n.startswith("resources/")] @@ -184,11 +185,11 @@ for r in json.load(open(os.path.join(out, "results.json")))["results"]: if any(m in ("mobium:app_map", "mobium:app_screenshot") for m in methods): sys.exit("FAIL: the runner's own screenshots or maps are in %s's trace: %s" % (r["title"], methods)) if len(methods) < len(r["trace"]) or not frames: - sys.exit("FAIL: %s's Playwright trace has %d calls and %d frames for %d steps" % (r["title"], len(methods), len(frames), len(r["trace"]))) + sys.exit("FAIL: %s's recording has %d calls and %d frames for %d steps" % (r["title"], len(methods), len(frames), len(r["trace"]))) calls = len(methods) -if "trace.playwright.dev" not in open(os.path.join(out, "index.html")).read(): - sys.exit("FAIL: the HTML report does not link the Playwright trace") -print(" %-14s %-58s ok" % ("trace zip", "the failed test as a Playwright trace, %d calls, none the runner's" % calls)) +if "player.vibium.dev" not in open(os.path.join(out, "index.html")).read(): + sys.exit("FAIL: the HTML report does not link the recording") +print(" %-14s %-58s ok" % ("trace zip", "the failed test as a recording, %d calls, none the runner's" % calls)) EOF # --- debug: stops before each step, and quits ------------------------------ diff --git a/docs/checks/trace.sh b/docs/checks/trace.sh index 77758f4f..9429bb73 100755 --- a/docs/checks/trace.sh +++ b/docs/checks/trace.sh @@ -1,5 +1,5 @@ #!/bin/sh -# `mobium trace`, held to what the trace viewers read. A sign-in on +# `mobium trace`, held to Vibium's record format and to what its player reads. A sign-in on # MobiumApp's Login Demo is traced — a password typed, a wait, and a tap on # something that is not there — and the zip is checked: # @@ -12,11 +12,10 @@ # - a second start refused while one runs, and a stop with none refused. # # With MOBIUM_TRACE_VIEWER=1 and Vibium installed, the zip is also opened in -# Playwright's own viewer at trace.playwright.dev — a consumer that is not -# ours — and every step must be listed there; and in Vibium's player at -# player.vibium.dev, which must count every call and name each as it steps -# through, a fill included. That needs the network; both read the file in -# the browser and send it nowhere. +# Vibium's player at player.vibium.dev — a consumer that is not ours — which +# must count every call and name each as it steps through, a fill included. +# That needs the network; the player reads the file in the browser and sends +# it nowhere. # # docs/checks/trace.sh # @@ -92,27 +91,9 @@ row "password" "not in the zip, only its length" if [ "${MOBIUM_TRACE_VIEWER:-}" = 1 ] && command -v vibium >/dev/null 2>&1; then V="vibium --headless --session mobium-trace-check" - $V go https://trace.playwright.dev >/dev/null - # The page renders after the load: wait for its Select file button. - for _ in 1 2 3 4 5 6 7 8 9 10; do - [ "$($V eval '[...document.querySelectorAll("button")].some(b => b.textContent.includes("Select file"))' 2>/dev/null)" = true ] && break - sleep 1 - done - # The page makes its file input only when Select file is clicked. - $V eval 'HTMLInputElement.prototype.click = function(){ this.id = "pwfile"; document.body.appendChild(this); }; - [...document.querySelectorAll("button")].find(b => b.textContent.includes("Select file")).click(); "ok"' >/dev/null - $V upload '#pwfile' "$OUT/t.zip" >/dev/null - sleep 5 - page=$($V eval 'document.body.innerText') - for step in "launch $APP" "tap label=Login Demo" "fill testid=password" "tap testid=noSuchButton"; do - echo "$page" | grep -q -F "$step" || fail "Playwright's viewer does not list \"$step\"" - done - row "viewer" "trace.playwright.dev lists every step" - - # And Vibium's player, which plays Playwright traces too: it takes the - # zip from its file input, says how many actions it holds, and names each - # as it steps — a fill by Playwright's selector and value, which Mobium - # records masked, a dot a character. + # Vibium's player takes the zip from its file input, says how many actions + # it holds, and names each as it steps — a fill by the record format's + # selector and value, which Mobium records masked, a dot a character. $V go https://player.vibium.dev >/dev/null for _ in 1 2 3 4 5 6 7 8 9 10; do [ "$($V eval 'document.querySelectorAll("input[type=file]").length' 2>/dev/null)" = 1 ] && break diff --git a/docs/checks/web-actionability.sh b/docs/checks/web-actionability.sh index 4a1466cb..bc46ca83 100755 --- a/docs/checks/web-actionability.sh +++ b/docs/checks/web-actionability.sh @@ -80,7 +80,7 @@ press "Arm: disable the next one for 2 s" reached "Enabled after Arm + 2 s" "target wEnabling" row "enabled late" "waited for it, then reached it" refused "aria-disabled" enabled "aria-disabled" -row "aria-disabled" "refused, as Playwright and Vibium do" +row "aria-disabled" "refused, as Vibium does" # --- receives events ----------------------------------------------------- refused "Fully covered" receivesEvents "full cover" diff --git a/docs/decisions/0001-cdp-not-webdriver-bidi.md b/docs/decisions/0001-cdp-not-webdriver-bidi.md index ab5fa1d6..c5666e92 100644 --- a/docs/decisions/0001-cdp-not-webdriver-bidi.md +++ b/docs/decisions/0001-cdp-not-webdriver-bidi.md @@ -75,8 +75,7 @@ error entered. This would have preserved the original design exactly. Rejected: it puts a chromedriver binary on the user's machine, matched to the WebView's Chromium version. That breaks the single-binary, zero-runtime-dependency property, which -is the first of Mobium's three design commitments and the main reason to build -it instead of using Appium. +is the first of Mobium's three design commitments. **B. Implement a BiDi mapper inside Mobium.** Rejected on cost. Chromedriver's mapper is a substantial piece of software, and Mobium needs roughly two calls' @@ -109,16 +108,12 @@ be wrong wherever the WebView does not fill the screen, which is most hybrid apps. (The viewport choice has its own trap; see [CHALLENGES.md](../CHALLENGES.md#6-the-visual-viewport).) -## Corroboration, from the side that pays for it +## The cost avoided -Appium's own newsletter documents the cost this decision avoided, in more -detail than the decision itself did: chromedriver's version must match the -device's Chrome, Appium bundles one version, and a device whose Chrome has -fallen behind fails with `Chrome version must be >= 76`. Four mitigations -exist, including a capability to download chromedrivers at run time -(`chromedriver_autodownload`). - -That is the option-A cost, described by the people living with it. +Chromedriver's version must match the device's Chrome: a tool that bundles +one version fails on a device whose Chrome has fallen behind, with `Chrome +version must be >= 76`, and the remedies are to download a matching +chromedriver at run time or keep several. That is option A's cost. ## Consequences diff --git a/docs/decisions/0002-ios-webviews-are-reachable.md b/docs/decisions/0002-ios-webviews-are-reachable.md index 389a5719..aa2fab18 100644 --- a/docs/decisions/0002-ios-webviews-are-reachable.md +++ b/docs/decisions/0002-ios-webviews-are-reachable.md @@ -170,8 +170,8 @@ The same protocol, reached a different way. Verified on an iPhone 15 Plus on iOS 26.6.2: MobiumApp's WebViews, two at once, and Safari's pages, through [../checks/mobium-app.sh](../checks/mobium-app.sh). -**The route is usbmuxd and lockdown** — the one Appium and -ios_webkit_debug_proxy take, and the "remote debugger proxy" people mean when +**The route is usbmuxd and lockdown** — the one ios_webkit_debug_proxy +takes, and the "remote debugger proxy" people mean when they say Safari on a device needs one: | Step | What | Measured | @@ -205,4 +205,4 @@ protocol — measured. But: not a transport. The lockdown route needs the phone connected by cable, which the tunnel route -would not have. That is the price, and it is the same one Appium pays. +would not have. That is the price. diff --git a/docs/decisions/0003-drivers-are-processes-not-plugins.md b/docs/decisions/0003-drivers-are-processes-not-plugins.md index 0c1aaafd..43b40597 100644 --- a/docs/decisions/0003-drivers-are-processes-not-plugins.md +++ b/docs/decisions/0003-drivers-are-processes-not-plugins.md @@ -3,8 +3,7 @@ **2026-09-13.** Answers a structural criticism of the design: the extension point is private. `mobiumdriver.Driver` lives under `internal/`, so nobody outside this repository can add a Roku, Flutter, tvOS or Tizen backend without forking. -Appium's ecosystem exists precisely because strangers can, and that is the -single largest advantage it has over Mobium. +An ecosystem of drivers exists only where strangers can add one. ## The three ways to open it @@ -35,8 +34,8 @@ talks to it for the life of the session. - **The single-binary property survives.** Mobium still ships as one static executable with no runtime dependencies. A driver is a separate file the user chooses to install; nothing is required to run Mobium without one. -- **No language lock-in.** Appium's ecosystem is Node-only because Appium is - Node. A Mobium driver can be a shell script, a Python file, a Go binary or a +- **No language lock-in.** A plugin must be written in its host's language. + A Mobium driver can be a shell script, a Python file, a Go binary or a Rust one. For a device whose SDK is Python — which is most of the odd ones — that is the difference between possible and not. - **Nothing internal is frozen.** The contract is the wire format, which is @@ -171,8 +170,8 @@ typed value straight into `text`, and mobium leaked one until it honored this `displayed` and `enabled` are the two fields that default to **true** when absent, so a driver that does not track them does not accidentally report an empty screen or a screen of dead controls. `enabled` is acted on since -2026-09-26: an action waits for its target to be enabled, as Playwright's and -Vibium's do, and refuses one that stays disabled — so a driver that sends +2026-09-26: an action waits for its target to be enabled, as Vibium's do, and +refuses one that stays disabled — so a driver that sends `enabled:false` for a control the user can tap will find every tap on it refused. Sending `false` explicitly is believed, and it is the only field a driver can diff --git a/docs/decisions/0004-an-app-under-test-of-our-own.md b/docs/decisions/0004-an-app-under-test-of-our-own.md index 249de3c4..49037762 100644 --- a/docs/decisions/0004-an-app-under-test-of-our-own.md +++ b/docs/decisions/0004-an-app-under-test-of-our-own.md @@ -23,14 +23,15 @@ unless the app sets `isInspectable`.** An app that does not opt in publishes no target, so mobium cannot attach to it whatever mobium does — and the opt-in is a property of the app, not of the device or the debugger. -Measured, not read: Appium's TheApp v1.12.0 is a React Native hybrid app whose +Measured, not read: TheApp v1.12.0, a third-party demo app, is a React Native +hybrid app whose prebuilt simulator bundle installs and runs fine on iOS 26.5. mobium drives its native side — launch, map, tap, type, navigation. Its WebView is unreachable. Writing the developer-extras default into the app's own domain, in both spellings, changes nothing: ```sh -xcrun simctl spawn defaults write com.appiumpro.the_app \ +xcrun simctl spawn defaults write \ WebKitDeveloperExtrasEnabledPreferenceKey -bool true ``` @@ -150,12 +151,13 @@ platform's and not one app's: verified — so nothing is broken, but a hand-written `label=` or `testid=` locator is unreliable against any RN app. Use a ref from `map`. - **An empty text input is labeled with its placeholder**, so `map` prints - `https://appiumpro.com (input)` for a field containing nothing. It reads + the placeholder, a URL, followed by `(input)` for a field containing + nothing. It reads exactly like a value and cost two wrong turns here. ## A correction -ROADMAP recorded that Appium's TheApp "still cannot be installed on this +ROADMAP recorded that TheApp "still cannot be installed on this machine — `TheApp-v1.10.0.apk` ships `armeabi-v7a` and `x86` against an `arm64-v8a` emulator." **v1.12.0 ships `arm64-v8a` and `x86_64`.** That blocker was true of v1.10.0 and is stale. @@ -164,7 +166,7 @@ TheApp was used here only as a reference for what an app under test should contain, and nothing was taken from it: it carries **no license at all** — no `LICENSE` file, no `license` field, `"license": null` from GitHub's API — so there is nothing to take. The screens here are chosen against this project's -defect log rather than against Appium's feature list. +defect log rather than against another tool's feature list. ## What Android found diff --git a/docs/decisions/0006-a-test-runner.md b/docs/decisions/0006-a-test-runner.md index fb231db0..f2043625 100644 --- a/docs/decisions/0006-a-test-runner.md +++ b/docs/decisions/0006-a-test-runner.md @@ -1,9 +1,8 @@ # 0006 — A test runner: `mobium test`, over JSON test files **2026-09-28. Iteration 1 built the same day** — see "What iteration 1 -showed", at the end. Mobium gets a test runner in -the shape of Playwright's — `mobium test`, projects, workers, retries, -reporters, a report to open — whose tests are **JSON files of the steps +showed", at the end. Mobium gets a test runner — +`mobium test`, projects, workers, retries, reporters, a report to open — whose tests are **JSON files of the steps `app_batch` already runs**, executed by the Go binary itself. ## Why now @@ -12,12 +11,10 @@ Every tool a test needs exists: actions that wait and refuse, `app_wait_for` for every state an assertion checks (visible, hidden, text, value, enabled, checked, focused), `app_batch` to run checked sequences, sessions that put the device back, and four kinds of device verified. What does not exist is the -thing a CI job runs and publishes. The competitor notes say it plainly: -"Mobium produces no artifact a CI job can publish. This is the difference -between a tool and a testing framework, and most buyers want the framework" -(`landscape/mobilewright.md`, gap 2). Until now the tests of Mobium itself -have been the shell scripts in `docs/checks/`, which is the same gap from the -inside. +thing a CI job runs and publishes: an artifact a CI job can publish is the +difference between a tool and a testing framework. Until now the tests of +Mobium itself have been the shell scripts in `docs/checks/`, which is the +same gap from the inside. ## What was decided @@ -47,8 +44,8 @@ are programs that call Mobium, as they are today. "Assertions" below). Mutatis mutandis: no second vocabulary. A step is `{"name": "app_tap", "arguments": {...}}`; an expectation is an `app_wait_for` step, which already retries until -its timeout and fails saying what the screen showed — Playwright's -auto-retrying `expect`. A dedicated `expect` shorthand is a later nicety, not +its timeout and fails saying what the screen showed — an auto-retrying +assertion. A dedicated `expect` shorthand is a later nicety, not a new mechanism. **The runner is a client of the tools, not a tool.** It lives in @@ -64,23 +61,23 @@ is the clients' kind of code. If agents need to run a test file over MCP, an Three layers, each the existing mechanism with what it lacks added, never a parallel one. -**On screen: `app_wait_for`.** Playwright's `expect(locator)` is a check that +**On screen: `app_wait_for`.** An assertion on the screen is a check that retries until its timeout, and a failure that says what it found. That is what `app_wait_for` already is — "timed out after 10s waiting for -testid=username to hold \"mo\" — its value is \"mob\"". Against -Playwright's matchers: +testid=username to hold \"mo\" — its value is \"mob\"". What a test needs +to assert, against what it had: -| Playwright | `app_wait_for` | Gap | +| A test asserts | `app_wait_for` | Gap | | --- | --- | --- | -| `toBeVisible`, `toBeHidden` | `visible`, `hidden` | — | -| `toBeEnabled`, `toBeDisabled` | `enabled`, `disabled` | — | -| `toBeChecked`, `not.toBeChecked` | `checked`, `unchecked` | — | -| `toBeFocused` | `focused` | its negation | -| `toHaveValue` | `value`, exact; a password field is refused | its negation | -| `toContainText` | `text`, a substring | its negation | -| `toHaveText`, exact or a pattern | — | missing | -| `toHaveCount` | — | missing | -| `.not` in general | only where a pair exists | missing | +| shown, hidden | `visible`, `hidden` | — | +| enabled, disabled | `enabled`, `disabled` | — | +| checked, unchecked | `checked`, `unchecked` | — | +| focused | `focused` | its negation | +| a field's value | `value`, exact; a password field is refused | its negation | +| text containing | `text`, a substring | its negation | +| text, exactly | — | missing | +| how many match | — | missing | +| the opposite of any of these | only where a pair exists | missing | Iteration 1 adds three arguments to `app_wait_for` — `exact` for `text`, a `count` condition, and `not`, which inverts any condition — so the CLI, MCP @@ -172,33 +169,33 @@ directory: } ``` -A project is a device — Playwright's browsers, mapped onto what Mobium drives. +A project is a device. A device serial in a checked-in file is fine for an emulator and a simulator; a real phone's identifier is personal and belongs in a local override or the command line, never the repository (the UDID scrub of 2026-09-23 is why). -## The commands, against Playwright's +## The commands -| Playwright | `mobium` | Iteration | +| `mobium` | What it does | Iteration | | --- | --- | --- | -| `test` | `mobium test` — every `*.test.json` under `testDir` | 1 | -| `test ` | `mobium test tests/login.test.json` | 1 | -| `test -g "login"` | `mobium test -g login` — tests whose name matches | 1 | -| `test --last-failed` | `mobium test --last-failed`, from `.mobium-test/last-run.json` | 1 | -| `test --project=chromium` | `mobium test --project=android` | 1 | -| `test --workers=4` | `--workers`: one per device, projects in parallel; a device holds one session, so never two workers on one | 1 | -| `test --retries=2` | `--retries=2`, and a pass after a retry is reported **flaky**, not passed | 1 | -| `test --timeout=30000` | `--timeout=30000`, per test | 1 | -| `test --reporter=html` | `--reporter=list` (default), `json`, `junit`, `html` | 1 | -| `show-report` | `mobium show-report` — opens the last HTML report | 1 | +| `mobium test` | every `*.test.json` under `testDir` | 1 | +| `mobium test tests/login.test.json` | one file | 1 | +| `mobium test -g login` | tests whose name matches | 1 | +| `mobium test --last-failed` | what failed last time, from `.mobium-test/last-run.json` | 1 | +| `--project=android` | one project | 1 | +| `--workers` | one per device, projects in parallel; a device holds one session, so never two workers on one | 1 | +| `--retries=2` | a pass after a retry is reported **flaky**, not passed | 1 | +| `--timeout=30000` | per test | 1 | +| `--reporter` | `list` (default), `json`, `junit`, `html` | 1 | +| `mobium show-report` | opens the last HTML report | 1 | | `--version`, `test --help` | exist already | — | -| `test --headed` | a simulator is headless until `open -a Simulator`; an emulator decides at launch | later | -| `test --debug` | `--debug`: stop before each step, show it and the map; Enter steps, `c` continues, `q` quits | 2 | -| `test --ui` | an interactive mode | later | -| `test --trace on` | `--trace on` or `retain-on-failure`: each step's screenshot and map, a filmstrip in the HTML report | 2 | -| `show-trace ` | the trace is in the HTML report, so `show-report` opens it | 2 | -| `codegen ` | record the tool calls a person or agent makes as a test file — the daemon already sees every call | later | -| `install`, `install --with-deps` | `mobium doctor` checks; the device-side agents install themselves, pinned and checksummed | mostly exists | +| a window | a simulator is headless until `open -a Simulator`; an emulator decides at launch | later | +| `--debug` | stop before each step, show it and the map; Enter steps, `c` continues, `q` quits | 2 | +| `--ui` | an interactive mode | later | +| `--trace on`, `retain-on-failure` | each step's screenshot and map, a filmstrip in the HTML report | 2 | +| a trace viewer | the trace is in the HTML report, so `show-report` opens it | 2 | +| recording a test | the tool calls a person or agent makes, kept as a test file — the daemon already sees every call | later | +| setting up | `mobium doctor` checks; the device-side agents install themselves, pinned and checksummed | mostly exists | What a failure leaves: the step that failed, its error code and message, and a screenshot and a `map` taken at the moment of failure, in the report. `map` @@ -314,13 +311,13 @@ on the Pixel 7 AVD and the iPhone 17 Pro simulator: that failed leaves nothing after it worth checking. The control, `tests/controls/soft.test.json`, fails with both of its soft failures and reaches its last step, which is how it shows the test carried on. -- **A trace per test**, Playwright's names: `--trace on` or +- **A trace per test**: `--trace on` or `retain-on-failure`, or `trace` in the config. Steps run one at a time rather than as a batch, and after each the runner keeps a screenshot and the map; the HTML report shows them as a filmstrip. A traced run is slower by a screenshot and a map a step, which is why it is off by default. `--no-screenshots` keeps the maps and no picture, for a phone. Since - 2026-10-01 each kept attempt is also a Playwright trace, `trace.zip` in + 2026-10-01 each kept attempt is also a recording in Vibium's record format, `trace.zip` in its trace directory, as `mobium trace` writes one, linked from the report and named in `trace_file`: the runner starts a session trace before the app is launched and stops it after the last step, and sends its own @@ -338,8 +335,8 @@ person does (`codegen`), and test parameters. ## Parameters -Added 2026-10-01: Playwright's parameterized test, a test in a loop over -its data, as a key on the test. `"each"` is a list of cases, objects, and +Added 2026-10-01: a parameterized test, a test in a loop over its data, as +a key on the test. `"each"` is a list of cases, objects, and the test runs once per case as a test of its own: ```json diff --git a/docs/decisions/0007-an-inspector.md b/docs/decisions/0007-an-inspector.md index 2ed18f29..e1e4afd4 100644 --- a/docs/decisions/0007-an-inspector.md +++ b/docs/decisions/0007-an-inspector.md @@ -11,12 +11,9 @@ the locator to write — acts on it, and keeps what was done as a test file. Every other surface asks the reader to already know the vocabulary: which locator names this button, whether `text=` or `label=` finds it on this platform, whether it is one element or three. The answer is on the device, -and until now reaching it meant running `map` and reading coordinates. Of -the tools in [landscape/mobilewright](../landscape/mobilewright.md), the -inspector is the one feature marked "enormous for adoption: it is how -someone learns the locator vocabulary without reading anything", and -Appium's own Inspector is the reason many people first get anything -working in Appium. +and until now reaching it meant running `map` and reading coordinates. An +inspector is how someone learns the locator vocabulary without reading +anything, and often how they first get anything working at all. It is also the missing half of `mobium test`: decision 0006 left recording a test from what a person does as "later", and the daemon already sees every diff --git a/docs/decisions/0009-a-test-ui.md b/docs/decisions/0009-a-test-ui.md index c47c37bc..284aa287 100644 --- a/docs/decisions/0009-a-test-ui.md +++ b/docs/decisions/0009-a-test-ui.md @@ -1,7 +1,7 @@ # 0009 — A test UI: `mobium test --ui` **2026-10-01. Iteration 1.** The interactive mode decision 0006 left for -later, after Playwright's `test --ui`: a page on this machine that lists the +later: a page on this machine that lists the suite, runs any part of it on any of its projects, shows every step with the screen after it as it happens, and runs again what failed. @@ -10,9 +10,8 @@ screen after it as it happens, and runs again what failed. `mobium test` answers once a run is over, in a terminal and a report. The loop a person is in while writing a test is shorter than that: change a step, run that one test, look at the screen it stopped on, change it again. `--debug` -serves one test at a time in a terminal. Playwright's UI mode is the tool -people reach for in that loop, and the one feature of its runner most often -named when someone explains why they moved to it. +serves one test at a time in a terminal; a page that runs any test and +shows its steps as they happen serves the whole loop. ## What was decided @@ -37,7 +36,7 @@ and from nowhere else. **The files are read again for every list and every run**, so an edited test is the test that runs, without restarting anything — the part of -Playwright's watch mode that matters while writing one. +a watch mode that matters while writing one. **When a run ends** its HTML and JSON reports are written as `--reporter html,json` writes them, and `--last-failed` sees its failures. diff --git a/docs/quickstart/README.md b/docs/quickstart/README.md index 5b93954e..d993978b 100644 --- a/docs/quickstart/README.md +++ b/docs/quickstart/README.md @@ -115,7 +115,7 @@ emulator-5554 device (android emulator, model: sdk_ ## 4. Start, work, quit -Every client does the same three things, as an Appium script does: +Every client does the same three things: | | Start a session | Quit it | | --- | --- | --- | diff --git a/internal/agent/backend.go b/internal/agent/backend.go index 5b416882..25140b5b 100644 --- a/internal/agent/backend.go +++ b/internal/agent/backend.go @@ -248,8 +248,8 @@ func (h *Handlers) resolveSession(ctx context.Context, args map[string]interface } backend = parsed } else if open := h.openSessionFor(serial); open != nil && backend == DefaultBackend { - // No driver named: the session already open is the context, as it is - // in Appium. Without this, a session started with platform "ios" was + // No driver named: the session already open is the context. Without + // this, a session started with platform "ios" was // followed by a call with no driver, which took Android's default // and failed asking for "wda" — from every client, since platform is // sent only with start. diff --git a/internal/agent/backend_test.go b/internal/agent/backend_test.go index 260873ba..9780bce2 100644 --- a/internal/agent/backend_test.go +++ b/internal/agent/backend_test.go @@ -26,7 +26,7 @@ func TestParseBackend(t *testing.T) { // of a possible third-party driver, and whether one exists is decided // when a session opens, where PATH can be named in the failure. See // docs/decisions/0003. - {"appium", "appium", false}, + {"tizen", "tizen", false}, {"roku", "roku", false}, // A near miss on a built-in name is still an error, because it is a // typo rather than a driver nobody has installed. diff --git a/internal/agent/cookies.go b/internal/agent/cookies.go index 8eb9e264..a8d0fd71 100644 --- a/internal/agent/cookies.go +++ b/internal/agent/cookies.go @@ -12,8 +12,8 @@ import ( ) // app_cookies and app_storage: Vibium's cookies and storage commands, carried -// onto a WebView. The command set and the saved-state shape are Vibium's and -// Playwright's, so a state saved by one restores in another; underneath, it +// onto a WebView. The command set and the saved-state shape are Vibium's, so a +// state saved by one restores in the other; underneath, it // is each platform's own inspector protocol for cookies and the page itself // for web storage (internal/webview/cookies.go says why each). // @@ -37,8 +37,8 @@ type CookiesView struct { Device string `json:"device"` } -// StorageState is a page's cookies and web storage, in the shape Playwright -// and Vibium save: {cookies, origins: [{origin, localStorage, sessionStorage}]}. +// StorageState is a page's cookies and web storage, in the shape Vibium +// saves: {cookies, origins: [{origin, localStorage, sessionStorage}]}. type StorageState struct { Cookies []webview.Cookie `json:"cookies"` Origins []webview.OriginStorage `json:"origins"` diff --git a/internal/agent/enabled_test.go b/internal/agent/enabled_test.go index d58e29e4..3cf1ef21 100644 --- a/internal/agent/enabled_test.go +++ b/internal/agent/enabled_test.go @@ -25,8 +25,7 @@ func button(t *testing.T, enabled bool) *uitree.Tree { return tree } -// An action waits for its target to be enabled, as Playwright's and Vibium's -// do, and taps once it is: MobiumApp's Log In is disabled while it signs in. +// An action waits for its target to be enabled, as Vibium's do, and taps once it is: MobiumApp's Log In is disabled while it signs in. func TestATapWaitsForItsTargetToBeEnabled(t *testing.T) { h, s, f := withFake(t, button(t, false), button(t, false), button(t, true)) h.implicitWait = 2 * time.Second diff --git a/internal/agent/handlers.go b/internal/agent/handlers.go index 345b192d..5d9daf12 100644 --- a/internal/agent/handlers.go +++ b/internal/agent/handlers.go @@ -947,7 +947,7 @@ func matchedNothing(err error) bool { } // The checks an action makes before it touches anything, named as a -// WebView's checks are and as Playwright and Vibium name them. +// WebView's checks are and as Vibium names them. const ( checkVisible = "visible" checkEnabled = "enabled" @@ -1041,7 +1041,7 @@ func keyboardOver(loc uitree.Locator, covered bool) error { // nonEditableRoles are the roles that are certainly not a text field. Typing // into one was passed to the server, which answered UiAutomator2's "invalid // element state: Cannot set the element to 'hello'" — measured on a Pixel 8 -// Pro, typing into a button. Playwright and Vibium refuse before trying. +// Pro, typing into a button. Vibium refuses before trying. var nonEditableRoles = []string{"button", "checkbox", "radio", "switch", "link", "image", "text", "tab"} // notEditable names the role that makes a node certainly not a text field, or @@ -1408,8 +1408,8 @@ func (h *Handlers) resolveNodeOnce(ctx context.Context, s *session, target strin return false, err } } - // Enabled is part of being actionable, as it is in Playwright and - // Vibium: a disabled control ignores a tap, which then reports + // Enabled is part of being actionable, as it is in Vibium: a + // disabled control ignores a tap, which then reports // success for nothing. Waited for within the same budget, since a // button the app is about to enable is the ordinary case. if resolveErr == nil && !node.Enabled { @@ -1504,7 +1504,7 @@ func (h *Handlers) resolveNodeOnce(ctx context.Context, s *session, target strin // is where it will be in a moment. A row sliding in, a sheet still animating // up, a list finishing a fling — all of them resolve cleanly and report // bounds that are already stale by the time the tap lands. This is the last -// piece of what Playwright calls actionability, and the one Mobium was +// piece of actionability, and the one Mobium was // missing. // // It costs one extra snapshot and one settleWindow per action: about 140ms on diff --git a/internal/agent/schema.go b/internal/agent/schema.go index 8464a4ba..2bbd6247 100644 --- a/internal/agent/schema.go +++ b/internal/agent/schema.go @@ -633,9 +633,9 @@ func GetToolSchemas() []Tool { { Name: "app_storage", Description: "Save, restore or clear the current WebView's storage state: its cookies and its " + - "origin's localStorage and sessionStorage, in the shape Playwright and Vibium save — " + + "origin's localStorage and sessionStorage, in the shape Vibium saves — " + "{cookies, origins: [{origin, localStorage, sessionStorage}]} — so a state saved by one " + - "restores in another. Vibium's storage command, on a WebView: switch with app_context first. " + + "restores in the other. Vibium's storage command, on a WebView: switch with app_context first. " + "\"get\" (the default) answers the state; \"restore\" sets its cookies and writes each origin's " + "storage only into a page on that origin, saying which it skipped; \"clear\" empties all three. " + "Every write is read back. A page with no origin of its own — an app's inline HTML, about:blank " + @@ -738,8 +738,8 @@ func GetToolSchemas() []Tool { Name: "app_trace", Description: "Record a session as a trace: start, then every call on this device is a step — " + "before and after, the point an action touched, a failure's error — and after each the " + - "screen, with the map's elements drawn over it; stop with a path saves a zip in the " + - "Playwright trace format that trace.playwright.dev and player.vibium.dev open. Omit the " + + "screen, with the map's elements drawn over it; stop with a path saves a zip in " + + "Vibium's record format, which player.vibium.dev opens. Omit the " + "action to ask whether one is running. Text typed into a field is not recorded, only its " + "length. On a real phone the screenshots are its owner's screen; screenshots false keeps " + "none. One trace per device; ending the session discards it.", @@ -1300,13 +1300,12 @@ func GetToolSchemas() []Tool { }, { Name: "app_session", - Description: "Start or end the session on a device, as Appium's new session and quit " + - "do. Every other tool opens a session on first use, so this is never required; " + + Description: "Start or end the session on a device. Every other tool opens a session on first use, so this is never required; " + "it is for putting the slow first start — installing UiAutomator2, building " + "WebDriverAgent on an iPhone — where you asked for it, and for ending one " + "device's session without stopping the daemon. \"start\" opens it (or keeps " + "one already open, reported as reused) and, given an app, launches it fresh — " + - "stopped first if it was running, as Appium does, so the session begins at the " + + "stopped first if it was running, so the session begins at the " + "app's first screen; its data is kept — and waits for it to be in front. \"end\" closes it with the daemon's own teardown: " + "accessibility settings put back, a recording or route stopped, WebViews " + "detached, the device-side server stopped, and the device's refs and dialog " + @@ -1552,7 +1551,7 @@ func GetToolSchemas() []Tool { Name: "app_source", Description: "The raw hierarchy, as the device-side server sent it: UiAutomator2's or " + "uiautomator's XML on Android, WebDriverAgent's on iOS, and in a WebView context " + - "the page's current markup. What Appium calls the page source. app_map is what " + + "the page's current markup: the page source. app_map is what " + "to act on — it hands out refs and leaves out what cannot be acted on; this is " + "for when map leaves out the thing you need to see. Password fields have their " + "contents hidden, keeping the length. Geometry is in the platform's units: " + diff --git a/internal/agent/session.go b/internal/agent/session.go index 07e84e85..d2a0b839 100644 --- a/internal/agent/session.go +++ b/internal/agent/session.go @@ -44,8 +44,7 @@ type SessionInfo struct { Driver string `json:"driver"` } -// sessionTool is app_session: the explicit start and end of a device session, as -// Appium's new session and quit are. +// sessionTool is app_session: the explicit start and end of a device session. // // Every other tool opens a session on first use and nothing closed one short // of stopping the daemon, which ends every device's at once. start opens it @@ -133,8 +132,7 @@ func (h *Handlers) sessionStart(ctx context.Context, args map[string]interface{} } if app := stringArg(args, "app"); app != "" { - // Stopped first, as Appium's UiAutomator2 driver stops the app before - // a session launches it, so the session begins at the app's first + // Stopped first, before the session launches it, so the session begins at the app's first // screen rather than wherever it was left. Settings resumes on the // last page it showed, and a quick start that tapped a row on the // main screen found the page it had opened last time instead. Data is @@ -174,8 +172,7 @@ func (h *Handlers) sessionEnd(args map[string]interface{}) (*ToolsCallResult, er sort.Strings(keys) if len(keys) == 0 { - // Idempotent, as Appium's quit on a session already gone: the state - // asked for is the state the device is in. + // Idempotent: the state asked for is the state the device is in. where := "any device" if want != "" { where = want diff --git a/internal/agent/session_test.go b/internal/agent/session_test.go index 28acb8e3..8ab91c4b 100644 --- a/internal/agent/session_test.go +++ b/internal/agent/session_test.go @@ -84,7 +84,7 @@ func TestEndingWithTwoOpenAndNoDeviceIsRefused(t *testing.T) { } func TestEndingASessionThatIsNotOpenSucceeds(t *testing.T) { - // Idempotent, as Appium's quit on a session already gone. + // Idempotent: a session already gone is a session ended. h := NewHandlers() v, err := sessionCall(t, h, map[string]interface{}{"action": "end", "device": "emulator-5554"}) if err != nil { @@ -173,7 +173,7 @@ func TestACallNamingNoDriverUsesTheSessionOpen(t *testing.T) { // A session started with platform "ios" is followed by calls that name // no driver — from every client, since platform goes only with start. // Before this, those calls took Android's default and failed asking for - // "wda". The session open is the context, as in Appium. + // "wda". The session open is the context. h := NewHandlers() ios := &session{dev: &device.Device{Serial: "457C7DC2-C706-45D9-8D68-1D26953E28B1"}, driver: &fakeDriver{}, backend: BackendWDA} h.sessions[ios.dev.Serial] = ios diff --git a/internal/agent/tracing.go b/internal/agent/tracing.go index 47a1a321..00e6bddf 100644 --- a/internal/agent/tracing.go +++ b/internal/agent/tracing.go @@ -19,8 +19,8 @@ import ( "github.com/mobiumdev/mobium/internal/uitree" ) -// app_trace: a session recorded as Vibium records one, into a zip that -// trace.playwright.dev and player.vibium.dev open. See internal/trace for +// app_trace: a session recorded as Vibium records one, into a zip in +// Vibium's record format, which player.vibium.dev opens. See internal/trace for // the format. The recording itself happens in Call, which every front door // goes through: while a device has a trace running, each call on it is a // before/after pair, and after it the screen is kept with its map. @@ -127,8 +127,7 @@ func (h *Handlers) traceTool(ctx context.Context, args map[string]interface{}) ( // TraceSavedMessage is app_trace stop's answer once the zip is saved, the // same whether the daemon saved it or a remote caller did. func TraceSavedMessage(path string, v TraceView) string { - return fmt.Sprintf("saved a trace of %d calls to %s (%d bytes) — open it at https://trace.playwright.dev "+ - "or https://player.vibium.dev", v.Calls, path, v.Bytes) + return fmt.Sprintf("saved a trace of %d calls to %s (%d bytes) — open it at https://player.vibium.dev", v.Calls, path, v.Bytes) } func platformOf(s *session) string { @@ -172,13 +171,13 @@ func traceBefore(t *sessionTrace, name string, args map[string]interface{}) stri if text, ok := params["text"].(string); ok { n := len([]rune(text)) params["text"] = fmt.Sprintf("(%d characters, not recorded)", n) - // Playwright's name for typed text, which player.vibium.dev + // The record format's name for typed text, which player.vibium.dev // shows as "Type "…" into ": a dot a character, // so it reads as masked and says how much was typed. params["value"] = strings.Repeat("•", min(n, 20)) } } - // Playwright's name for the element acted on, which player.vibium.dev + // The record format's name for the element acted on, which player.vibium.dev // reads — without it a fill showed as `Type "" into field`. if target, ok := args["target"].(string); ok && target != "" { params["selector"] = target diff --git a/internal/agent/tracing_test.go b/internal/agent/tracing_test.go index a98084c1..dc5d5325 100644 --- a/internal/agent/tracing_test.go +++ b/internal/agent/tracing_test.go @@ -71,7 +71,7 @@ func TestATraceKeepsNoTypedText(t *testing.T) { if strings.Contains(out, "Sup3rSecret") { t.Fatal("the typed text is in the trace") } - // Playwright's names, which player.vibium.dev reads to say what a step + // The record format's names, which player.vibium.dev reads to say what a step // typed into: the element, and the text as a dot a character. for _, want := range []string{`"selector":"testid=password"`, `"value":"••••••••••••"`, `"selector":"@e3"`} { if !strings.Contains(out, want) { diff --git a/internal/agent/wait.go b/internal/agent/wait.go index 490bcd1b..56d5acb2 100644 --- a/internal/agent/wait.go +++ b/internal/agent/wait.go @@ -243,8 +243,7 @@ func (h *Handlers) waitOn(ctx context.Context, s *session, args map[string]inter nodes = shown } // A declared rule answers a dialog in a wait's way as it does in an - // action's, as Playwright's locator handlers run for an assertion - // too: login.test.json's rule for "Save Password?" answered it in + // action's: login.test.json's rule for "Save Password?" answered it in // front of a tap and not in front of the wait for the next screen, // which timed out on a real iPhone. Not for a wait until the target // is gone, which a dialog over it already satisfies. On Android the diff --git a/internal/agent/waitstate_test.go b/internal/agent/waitstate_test.go index a6f38421..445c7088 100644 --- a/internal/agent/waitstate_test.go +++ b/internal/agent/waitstate_test.go @@ -177,7 +177,7 @@ func TestWaitNotInvertsTheCondition(t *testing.T) { } } -// exact is Playwright's toHaveText where text is its toContainText. +// exact matches the whole text, where text matches a part of it. func TestWaitExactText(t *testing.T) { h, sess, _ := withFake(t, screen(t, "Sent!")) _, err := wait(h, sess, map[string]interface{}{"target": "testid=b", "condition": "text", "text": "Sent", @@ -194,7 +194,7 @@ func TestWaitExactText(t *testing.T) { } } -// count is Playwright's toHaveCount: a list growing to three rows, and a +// count waits for a number of matches: a list growing to three rows, and a // list that never does, which must say how many it saw. func TestWaitCount(t *testing.T) { rows := func(n int) *uitree.Tree { diff --git a/internal/device/lockdown.go b/internal/device/lockdown.go index f289427c..237f1635 100644 --- a/internal/device/lockdown.go +++ b/internal/device/lockdown.go @@ -14,8 +14,8 @@ import ( "github.com/mobiumdev/mobium/internal/plist" ) -// A real iPhone's Web Inspector is reached the way Appium and -// ios_webkit_debug_proxy reach it, and every step was measured on an iPhone +// A real iPhone's Web Inspector is reached the way ios_webkit_debug_proxy +// reaches it, and every step was measured on an iPhone // 15 Plus on iOS 26.6.2 before any of this was written: // // 1. usbmuxd, a Unix socket on every Mac, lists the phone and hands over the diff --git a/internal/device/uia2install.go b/internal/device/uia2install.go index bf89c95b..4d85cf49 100644 --- a/internal/device/uia2install.go +++ b/internal/device/uia2install.go @@ -16,12 +16,12 @@ import ( "github.com/mobiumdev/mobium/internal/paths" ) -// The UiAutomator2 server is Appium's, under Apache-2.0, downloaded from its -// GitHub releases the same way vibium downloads Chrome on first use. +// The UiAutomator2 server is under Apache-2.0, downloaded from its GitHub +// releases the same way vibium downloads Chrome on first use. // // The version is pinned rather than tracking latest: a server that changes -// under the user is exactly the version-drift tax that makes Appium painful, -// and the checksums below only mean anything against a fixed release. +// under the user is exactly the version-drift tax that makes a mobile setup +// painful, and the checksums below only mean anything against a fixed release. const ( UIA2Version = "10.6.6" uia2Release = "https://github.com/appium/appium-uiautomator2-server/releases/download/v" + UIA2Version diff --git a/internal/device/wdainstall.go b/internal/device/wdainstall.go index 47aa56e6..d7b3813a 100644 --- a/internal/device/wdainstall.go +++ b/internal/device/wdainstall.go @@ -12,10 +12,10 @@ import ( "strings" ) -// WebDriverAgent is Appium's, under Apache-2.0. Appium publishes a prebuilt -// runner for arm64 simulators, so mobium downloads that rather than requiring -// an xcodebuild of WDA from source — the step that makes an Appium iOS setup -// slow and version-fragile. +// WebDriverAgent is under Apache-2.0. Its project publishes a prebuilt runner +// for arm64 simulators, so mobium downloads that rather than requiring an +// xcodebuild of WDA from source — the step that makes an iOS setup slow and +// version-fragile. // // Pinned, not tracked, for the same reason as the UiAutomator2 server: a // device-side agent that changes underneath you is the drift this tool exists diff --git a/internal/device/wdaphone.go b/internal/device/wdaphone.go index be362481..ba73bc44 100644 --- a/internal/device/wdaphone.go +++ b/internal/device/wdaphone.go @@ -22,7 +22,7 @@ import ( // A real iPhone cannot run the prebuilt simulator runner. WebDriverAgent has // to be built from source and code-signed with the user's own development -// team, so on a phone Mobium does what an Appium setup does by hand — and does +// team, so on a phone Mobium does what an iOS automation setup does by hand — and does // it from a pinned, checksummed source release rather than a git checkout, so // the runner on the phone is the same version the simulator uses. // @@ -58,8 +58,8 @@ func PhoneWDABundleID(team string) string { // // Tools that install their own WebDriverAgent find the runners already on a // phone by that CFBundleName and uninstall every one but their own, whatever -// its bundle id: on 2026-09-30 appium-xcuitest-driver's session removed -// Mobium's runner from the iPhone 15 Plus that way (CHALLENGES 189). A name +// its bundle id: on 2026-09-30 another tool's session removed Mobium's +// runner from the iPhone 15 Plus that way (CHALLENGES 189). A name // of Mobium's own takes it out of that sweep. Only the runner target is // renamed — the build setting is looked up by target name, so // WebDriverAgentLib keeps its name and the runner still links it. diff --git a/internal/mobiumdriver/driver.go b/internal/mobiumdriver/driver.go index f2ad3c96..25ceca0f 100644 --- a/internal/mobiumdriver/driver.go +++ b/internal/mobiumdriver/driver.go @@ -418,7 +418,7 @@ const ( ) // Source is a hierarchy as the device-side server sent it, before any -// parsing: what Appium calls the page source. Units says what its geometry +// parsing: the page source. Units says what its geometry // is in, since on iOS that is points and not the pixels map and taps use; // Scale is pixels per point there. type Source struct { diff --git a/internal/mobiumdriver/multitouch.go b/internal/mobiumdriver/multitouch.go index 8f4ba972..23c43400 100644 --- a/internal/mobiumdriver/multitouch.go +++ b/internal/mobiumdriver/multitouch.go @@ -30,7 +30,7 @@ import ( // later lift named a pointer nobody was tracking and never arrived. Measured // on a Pixel 7 AVD against MobiumApp's Multi-Touch pad and Android's // pointer-location overlay, which read "P: 0 / 1" for a press-tap the tool -// had reported as sent (appium-uiautomator2-server 10.6.6, +// had reported as sent (UiAutomator2 server 10.6.6, // ActionsExecutor.executeMotionEvents; CHALLENGES 84). Pinch never met either, because both // its fingers move in every step. On WebDriverAgent a move to the current // point is simply a finger that did not move. diff --git a/internal/mobiumdriver/uia2.go b/internal/mobiumdriver/uia2.go index 9282d82a..d00d1409 100644 --- a/internal/mobiumdriver/uia2.go +++ b/internal/mobiumdriver/uia2.go @@ -16,8 +16,8 @@ import ( "github.com/mobiumdev/mobium/internal/uitree" ) -// UiAutomator2 is Appium's device-side server, driven directly over HTTP with -// no Appium process in between. It replaces `uiautomator dump`, which costs a +// UiAutomator2 is the device-side server, driven directly over HTTP with no +// other process in between. It replaces `uiautomator dump`, which costs a // couple of seconds per snapshot and cannot type or gesture at all. const ( // uia2DevicePort is the port the server listens on inside the device. diff --git a/internal/mobiumdriver/w3c.go b/internal/mobiumdriver/w3c.go index 6ffe68a1..b7b96390 100644 --- a/internal/mobiumdriver/w3c.go +++ b/internal/mobiumdriver/w3c.go @@ -29,7 +29,7 @@ type w3cClient struct { // reopen re-establishes a session that the server no longer knows about. // Both servers hold exactly one session per device, so anything else that - // attaches — a second mobium process, or Appium — silently invalidates + // attaches — a second mobium process, or another tool — silently invalidates // ours. Recovering beats failing every later command. reopen func(context.Context) error } @@ -440,8 +440,8 @@ func (c *w3cClient) wdaDoubleTap(ctx context.Context, x, y int) error { // There is deliberately no counterpart. `get_clipboard` exists on the same // server and returns an empty string on Android 10 and later whatever the // clipboard holds: reading it requires the *requesting* app to have focus, and -// the UiAutomator2 server has no activity of its own. Appium works around that -// with a separate helper app; mobium installs no such thing, so the honest +// the UiAutomator2 server has no activity of its own. Working around that takes +// a separate helper app; mobium installs no such thing, so the honest // answer is to refuse rather than to report an empty clipboard that may be // full. Measured on Android 15 — see CHALLENGES 60. func (c *w3cClient) setClipboard(ctx context.Context, text string) error { diff --git a/internal/mobiumdriver/wda.go b/internal/mobiumdriver/wda.go index c513eaea..ab9889d7 100644 --- a/internal/mobiumdriver/wda.go +++ b/internal/mobiumdriver/wda.go @@ -19,8 +19,7 @@ import ( // and the first launch on a cold simulator includes its own startup. const wdaReadyTimeout = 90 * time.Second -// WDA drives an iOS simulator or a real iPhone through Appium's -// WebDriverAgent. +// WDA drives an iOS simulator or a real iPhone through WebDriverAgent. // // It shares the W3C client with the UiAutomator2 backend — the two servers // expose the same endpoints — so this file is only the parts that differ: diff --git a/internal/mobiumdriver/wdalocale.go b/internal/mobiumdriver/wdalocale.go index cd5ef394..f592f430 100644 --- a/internal/mobiumdriver/wdalocale.go +++ b/internal/mobiumdriver/wdalocale.go @@ -17,7 +17,6 @@ import ( // for an app that ships more than one language, and only by hand — but an // app reads its languages from its defaults, and launch arguments are the // first place those are looked up: `-AppleLanguages (ja) -AppleLocale ja_JP`. -// That is what Appium's language and locale capabilities do too. // // So the language lives in the session and goes with every launch Mobium // makes: it lasts until it is cleared or the session ends, and an app opened diff --git a/internal/mobiumerr/mobiumerr.go b/internal/mobiumerr/mobiumerr.go index ccd4c5c2..16e0b0f1 100644 --- a/internal/mobiumerr/mobiumerr.go +++ b/internal/mobiumerr/mobiumerr.go @@ -9,7 +9,7 @@ // matching message text. See docs/decisions/0005-errors.md. // // The codes are modeled on W3C WebDriver's — lowercase, underscore-separated, -// stable — because that is the vocabulary Selenium and Appium users already +// stable — because that is the vocabulary WebDriver users already // catch, and the one WebDriverAgent and UiAutomator2 answer in. Where a W3C // code names the same thing, the Mobium code has the same spelling // (no_such_element, no_such_alert, timeout). `not_confirmed` has no W3C diff --git a/internal/testrun/each_test.go b/internal/testrun/each_test.go index 2914d268..4cf29b14 100644 --- a/internal/testrun/each_test.go +++ b/internal/testrun/each_test.go @@ -5,7 +5,7 @@ import ( "testing" ) -// A test with "each" is one test per case, Playwright's parameterized test: +// A test with "each" is one test per case: // ${key} in its steps is the case's value, a step argument that is nothing // but ${key} keeps the value's type, and with no ${key} in the name each // case is numbered rather than named after its values. diff --git a/internal/testrun/file.go b/internal/testrun/file.go index 02131a85..6b4fdc27 100644 --- a/internal/testrun/file.go +++ b/internal/testrun/file.go @@ -36,7 +36,7 @@ type Test struct { Name string `json:"name"` Description string `json:"description,omitempty"` Steps []Step `json:"steps"` - // Each runs the test once per case, Playwright's parameterized test: + // Each runs the test once per case, a test over its data: // ${key} in its name and steps is that case's value. See expandEach. Each []map[string]interface{} `json:"each,omitempty"` } @@ -488,8 +488,8 @@ func Discover(cfg *Config, paths []string) ([]string, error) { // placeholderRe is ${key} in a test's name or steps; $${ is a literal ${. var placeholderRe = regexp.MustCompile(`\$\$\{|\$\{([A-Za-z_][A-Za-z0-9_]*)\}`) -// expandEach makes a test with "each" one test per case, as a Playwright -// test in a loop over its data is. ${key} anywhere in a step's strings is +// expandEach makes a test with "each" one test per case, as a test in a +// loop over its data is. ${key} anywhere in a step's strings is // the case's value, and a string that is nothing but ${key} takes the // value's own type, so a count stays a number. The name is the case's too: // with a ${key} in it, substituted, and without one, numbered — "[1]", diff --git a/internal/testrun/report.go b/internal/testrun/report.go index 1a537289..54d90aa6 100644 --- a/internal/testrun/report.go +++ b/internal/testrun/report.go @@ -223,8 +223,8 @@ img{max-width:320px;width:100%;border:1px solid var(--line);border-radius:8px} } } if r.TraceFile != "" { - fmt.Fprintf(&b, `

Playwright trace: %s — open it at `+ - `trace.playwright.dev

`, + fmt.Fprintf(&b, `

Recording: %s — open it at `+ + `player.vibium.dev

`, html.EscapeString(filepath.ToSlash(r.TraceFile)), html.EscapeString(filepath.Base(r.TraceFile))) } if len(r.Trace) > 0 { diff --git a/internal/testrun/run.go b/internal/testrun/run.go index a7f476db..0e047f97 100644 --- a/internal/testrun/run.go +++ b/internal/testrun/run.go @@ -135,8 +135,8 @@ type Result struct { // Trace is every step of that attempt with the screen after it, when the // run was traced. Trace []TraceStep `json:"trace,omitempty"` - // TraceFile is that attempt as a Playwright trace — a zip that - // trace.playwright.dev opens, as `mobium trace` writes — relative to the + // TraceFile is that attempt as a recording in Vibium's record format — + // a zip that player.vibium.dev opens, as `mobium trace` writes — relative to the // output directory. TraceFile string `json:"trace_file,omitempty"` } @@ -508,7 +508,7 @@ func traceDir(j job, t Test, attempt int) string { return filepath.Join("artifacts", "trace", fmt.Sprintf("%s-%d", traceStem(j, t), attempt)) } -// traceZip is the Playwright trace in an attempt's trace directory. +// traceZip is the recording in an attempt's trace directory. const traceZip = "trace.zip" // traced says whether a run keeps a trace of its tests. @@ -582,7 +582,7 @@ func runOnce(j job, t Test, opts Options, call Caller, attempt int) ([]*Failure, if traced(opts) { h.single = true dir := traceDir(j, t, attempt) - // The test as a Playwright trace too: every call it makes on the + // The test as a recording too: every call it makes on the // device, the app's launch included, with the screen after each. // The runner's own screenshots and maps are kept out of it. A trace // already running on the device — the person's own — is left diff --git a/internal/testrun/run_test.go b/internal/testrun/run_test.go index 6c4cce51..5daacd0c 100644 --- a/internal/testrun/run_test.go +++ b/internal/testrun/run_test.go @@ -573,11 +573,11 @@ func TestATraceIsEveryStepAndRetainOnFailureKeepsFailures(t *testing.T) { } } -// A traced test is a Playwright trace too: app_trace starts before the app +// A traced test is a recording too: app_trace starts before the app // is launched and stops after the last step, into the attempt's trace // directory, and the runner's own screenshots and maps are sent untraced so // the zip holds the test. retain-on-failure keeps a failed test's zip only. -func TestATracedTestIsAPlaywrightTrace(t *testing.T) { +func TestATracedTestIsARecording(t *testing.T) { dir := t.TempDir() p := write(t, dir, "login.test.json", loginFile) for _, mode := range []string{TraceOn, TraceRetainOnFailure} { diff --git a/internal/testui/page.html b/internal/testui/page.html index 91537961..66b4fde1 100644 --- a/internal/testui/page.html +++ b/internal/testui/page.html @@ -159,7 +159,7 @@

Steps

box.append(head); if (done && done.failure) box.append(el("div", {class: "err", text: "step " + done.failure.step + ": " + done.failure.message})); if (done && done.trace_file) box.append(el("div", {}, el("a", {href: artifact(done.trace_file), text: "trace.zip"}), - document.createTextNode(" — open it at trace.playwright.dev or player.vibium.dev"))); + document.createTextNode(" — open it at player.vibium.dev"))); box.append(frames(live ? live.steps : done.trace)); } if (!any) box.append(el("div", {class: "muted", text: "Not run yet. ▶ runs it on every project."})); diff --git a/internal/trace/trace.go b/internal/trace/trace.go index 8ce12da8..3317ff0a 100644 --- a/internal/trace/trace.go +++ b/internal/trace/trace.go @@ -1,6 +1,5 @@ -// Package trace records a session as Vibium records one: a zip in the -// Playwright trace format, which trace.playwright.dev and player.vibium.dev -// both open. Every tool call is a before/after pair, an action on an element +// Package trace records a session as Vibium records one: a zip in Vibium's +// record format, which player.vibium.dev opens. Every tool call is a before/after pair, an action on an element // adds the point it touched, and after each call the screen is kept twice — // as a screencast frame for the film strip, and as a frame snapshot, where // Vibium keeps the page's DOM and Mobium keeps the screenshot with the map's @@ -96,8 +95,8 @@ func (r *Recorder) Input(id string, x, y int, box *Box) { r.events = append(r.events, ev) } -// After closes a call. A failure is recorded as Playwright records one, so -// the viewers mark the step red and show why. +// After closes a call. A failure is recorded as the record format records +// one, so the player marks the step red and shows why. func (r *Recorder) After(id string, err error, result string) { r.mu.Lock() defer r.mu.Unlock() diff --git a/internal/webview/actionable.go b/internal/webview/actionable.go index 5aa9e7e3..3179ea56 100644 --- a/internal/webview/actionable.go +++ b/internal/webview/actionable.go @@ -11,8 +11,8 @@ import ( // Actionability is what a page says about one element just before a touch: // whether it can be touched, and if so where. // -// The checks are Vibium's, from clicker/internal/api/actionability.go, which -// are Playwright's matrix for a click: visible, enabled and receives events, +// The checks are Vibium's, from clicker/internal/api/actionability.go: for a +// click, visible, enabled and receives events, // with stability compared across two calls by the caller. Two things are // Mobium's. The element is scrolled into view first — measured on MobiumApp's // Actionability page, a target below the fold was tapped at y=6221 on a diff --git a/internal/webview/console.go b/internal/webview/console.go index bd3a6847..33628d3f 100644 --- a/internal/webview/console.go +++ b/internal/webview/console.go @@ -15,8 +15,8 @@ import ( // one feature. It does not need one: a script can buffer console output in the // page and a second script can read the buffer back, which is the same // evaluate-and-read shape as `Map` and `Text`. One implementation serves both -// platforms, where Appium needs two mechanisms with two different data shapes -// — chromedriver's `browser` log type on Android, a non-standard +// platforms, where the platforms' own routes are two mechanisms with two +// different data shapes — chromedriver's `browser` log type on Android, a non-standard // `safariConsole` on iOS whose entries are themselves JSON. // consoleBufferLimit bounds what the page holds. A chatty app can log diff --git a/internal/webview/cookies.go b/internal/webview/cookies.go index beb7b3fb..4685d9dc 100644 --- a/internal/webview/cookies.go +++ b/internal/webview/cookies.go @@ -30,8 +30,8 @@ import ( // it already expired — so every write is read back by the caller. // Cookie is one cookie, the same on both platforms. The JSON keys are -// Playwright's and Vibium's rather than Mobium's usual snake_case, so a -// storage state saved by one tool can be restored by another. +// Vibium's rather than Mobium's usual snake_case, so a storage state saved +// by one can be restored by the other. type Cookie struct { Name string `json:"name"` Value string `json:"value"` @@ -296,8 +296,7 @@ type StorageItem struct { Value string `json:"value"` } -// OriginStorage is one origin's web storage, in the shape Playwright and -// Vibium save it. +// OriginStorage is one origin's web storage, in the shape Vibium saves it. type OriginStorage struct { Origin string `json:"origin"` LocalStorage []StorageItem `json:"localStorage"` diff --git a/packaging/mcp/manifest.json b/packaging/mcp/manifest.json index 1800b182..45f38750 100644 --- a/packaging/mcp/manifest.json +++ b/packaging/mcp/manifest.json @@ -4,7 +4,7 @@ "display_name": "Mobium", "version": "@VERSION@", "description": "Drive native Android and iOS apps on emulators, phones, simulators and iPhones, WebViews included.", - "long_description": "Mobium automates native mobile apps for AI agents: map the screen, tap, type and swipe by locator, wait for states, answer system dialogs, reach into WebViews, take screenshots and recordings, and set network conditions, location and accessibility settings. It drives Android through UiAutomator2 and iOS through WebDriverAgent, directly, with no Appium and no Node. It needs the platform's own tools on the machine: Android's platform-tools for Android, Xcode for iOS.", + "long_description": "Mobium automates native mobile apps for AI agents: map the screen, tap, type and swipe by locator, wait for states, answer system dialogs, reach into WebViews, take screenshots and recordings, and set network conditions, location and accessibility settings. It drives Android through UiAutomator2 and iOS through WebDriverAgent, directly, with no Node. It needs the platform's own tools on the machine: Android's platform-tools for Android, Xcode for iOS.", "author": { "name": "Lana Begunova", "url": "https://github.com/mobiumdev" diff --git a/tests/mobiumapp/login.test.json b/tests/mobiumapp/login.test.json index 5b966d7b..f555a2dd 100644 --- a/tests/mobiumapp/login.test.json +++ b/tests/mobiumapp/login.test.json @@ -8,7 +8,7 @@ ], "tests": [ {"name": "a bad sign-in is refused, and says why: ${why}", - "description": "One test per case, Playwright's parameterized test; each names its own message under its own field.", + "description": "One test per case; each names its own message under its own field.", "each": [ {"why": "a wrong password", "user": "mobium", "pass": "wrongpass1", "error": "loginError", "message": "Incorrect username or password."},