Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/pinned-agents.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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".
#
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
12 changes: 5 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
18 changes: 8 additions & 10 deletions clients/dotnet/Mobium/Device.cs
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ public IList<Element> Find(string locator) =>
Elements("app_find", Args("locator", locator));

/// <summary>
/// The raw hierarchy — what Appium calls the page source — for when
/// The raw hierarchy — the page source — for when
/// <see cref="Map"/> leaves out the thing you need to see; map is what
/// to act on. <c>source</c> is the platform's XML, or in a WebView the
/// page's markup; <c>units</c> is "px" on Android and "pt" on iOS, where
Expand Down Expand Up @@ -1009,8 +1009,8 @@ public void IncomingCall(string action, string number) =>

/// <summary>
/// Stops the trace and saves it at <paramref name="path"/>, 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.
/// </summary>
/// <returns>
Expand Down Expand Up @@ -1072,7 +1072,7 @@ public string Eval(string expression) =>
/// <summary>
/// The current WebView's cookies: the ones its page's URL is sent,
/// HttpOnly ones included. Needs a web context — <c>Context</c> 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.
/// </summary>
Expand All @@ -1097,8 +1097,8 @@ public void ClearCookies(string? name = null) =>
Data("app_cookies", string.IsNullOrEmpty(name) ? Args("action", "clear") : Args("action", "clear", "name", name));

/// <summary>
/// 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.
/// </summary>
public IDictionary<string, object?> Storage()
Expand Down Expand Up @@ -1205,8 +1205,7 @@ public void Dispose()
}

/// <summary>
/// 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
Expand Down Expand Up @@ -1381,8 +1380,7 @@ public DeviceBuilder CallTimeout(TimeSpan timeout)
public DeviceBuilder App(string id) { _app = id ?? ""; return this; }

/// <summary>
/// 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
/// <see cref="App"/>, it is launched and in front when this returns.
/// </summary>
/// <remarks>
Expand Down
2 changes: 1 addition & 1 deletion clients/dotnet/Mobium/Mobium.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<PackageProjectUrl>https://github.com/mobiumdev/mobium</PackageProjectUrl>
<RepositoryUrl>https://github.com/mobiumdev/mobium</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageTags>mobile;automation;testing;android;ios;appium;uiautomator2;webdriveragent;mcp</PackageTags>
<PackageTags>mobile;automation;testing;android;ios;uiautomator2;webdriveragent;mcp</PackageTags>
<PackageReadmeFile>README.md</PackageReadmeFile>
<PackageIcon>icon.png</PackageIcon>

Expand Down
4 changes: 2 additions & 2 deletions clients/dotnet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions clients/go/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
28 changes: 13 additions & 15 deletions clients/go/mobium.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"))
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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 == "" {
Expand Down Expand Up @@ -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"`
Expand All @@ -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"`
Expand Down
4 changes: 2 additions & 2 deletions clients/java/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
17 changes: 7 additions & 10 deletions clients/java/src/main/java/dev/mobium/Mobium.java
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
* <p>Nothing requires it -- every call opens a session on first use --
Expand Down Expand Up @@ -260,7 +259,7 @@ public List<Element> 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
Expand Down Expand Up @@ -1598,8 +1597,8 @@ public Map<String, Object> 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}
Expand Down Expand Up @@ -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.
*
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1874,8 +1872,7 @@ public Map<String, Object> call(String tool, Map<String, Object> 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 --
Expand Down
4 changes: 2 additions & 2 deletions clients/javascript/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 5 additions & 6 deletions clients/javascript/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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: {
Expand Down Expand Up @@ -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<Device>
Expand Down Expand Up @@ -349,7 +349,7 @@ export class Device {
crashes(options?: { app?: string; limit?: number }): Promise<Data[]>
crash(id: string): Promise<Data>
record(options?: { action?: 'start' | 'stop'; path?: string }): Promise<Data>
/** 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<Trace>
traceStop(path: string): Promise<Trace>
trace(): Promise<Trace>
Expand Down Expand Up @@ -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<void>
/** Close the connection; the session stays open. Resolves once mobium has exited. */
Expand Down
Loading
Loading