This is the documentation for the SimGadget API.
An overall introduction to the library is at simgadget.dev/library.html. To drive simulators from an AI agent rather than from code, see simgadget-mcp.
import { createSimulator } from "simgadget";
// Creates on the latest installed iOS runtime and waits until the device is
// actually driveable
const sim = await createSimulator({ deviceType: "iPhone 16 Pro" });
console.log(sim.udid, sim.lastBoot); // { ready: true, waitedMs: 41000, ... }
await sim.installApp("./build/MyApp.app");
await sim.launchApp("com.example.myapp"); // -> { pid: 18900 }
// Resolves the element and taps it. Refuses if the element is disabled or not visible.
const result = await sim.tap({ label: "Sign Up" });
// { acted: "touch", x: 201, y: 442, count: 1, durationSeconds: 0.1, element: {...} }
await sim.tap({ label: "Email" });
await sim.typeText("test@example.com");
// null is the ordinary "not on screen" answer, not an error.
const banner = await sim.findByLabel("Welcome back");
if (banner === null) {
console.log("Can't find Welcome back");
}
await sim.screenshot({ path: "/tmp/signup.png" });
// And finally delete the sim when you're finished.
await sim.delete();
CommonJS works the same way:
const { createSimulator } = require("simgadget").
Nothing in the library deletes a simulator except a delete() written by the
caller.
Two functions return a Simulator:
Additionally:
simctl knows about, without
creating or attaching anything.Arguments to tap, swipe and describePoint, and the frames inside every
AXElement, are logical points in the orientation the interface is currently
displaying. This is the space the accessibility tree reports, and the space
visible on screen.
Functions and methods that perform an action (eg tap) generally return the outcome
of what happened. However swipe and typeText are the exception and return void.
Every error extends SimGadgetError and carries a code from the ErrorCode
union. Subclasses add a payload where there is one to inspect:
DeviceTypeNotFoundError carries the list of available device types,
TapObstructedError carries the obstructing element, UntypeableTextError
carries the offending characters.