Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sootsim
✓ import { sootsim } from 'sootsim'
✗ const s = require('sootsim')
ESM-only package since v0.1.0. CommonJS require will fail.
SootSimBridgeClient
✓ import { SootSimBridgeClient } from 'sootsim/sdk'
✗ import { SootSimBridgeClient } from 'sootsim'
The bridge client is located under the 'sdk' subpath export, not the package root.
detoxPreset
✓ import { detoxPreset } from 'sootsim/detox'
✗ import detoxPreset from 'sootsim/detox'
detoxPreset is a named export, not a default export.
VitePlugin
✓ import { VitePlugin } from 'sootsim/vite'
✗ import VitePlugin from 'sootsim/vite'
The Vite plugin is exported as a named export. Using default import will result in undefined.
MetroPlugin
✓ import { MetroPlugin } from 'sootsim/metro'
✗ import { MetroPlugin } from 'sootsim/vite'
Metro plugin is under 'metro' subpath, not 'vite'.
Programmatic usage: connect to the sootsim bridge daemon, inspect and interact with the simulated UI tree, and capture screenshots.
// Install: npm install sootsim
// 1. Start the bridge daemon (if not already running)
import { SootSimBridgeClient } from 'sootsim/sdk';
const client = new SootSimBridgeClient({ port: 7668 });
await client.connect();
// 2. Find the root view in the simulated iOS shell
const root = await client.find({ text: 'Home Screen' });
if (!root) throw new Error('Home screen not found');
// 3. Interact: tap an app icon
await client.do({ action: 'tap', target: { id: 'settings-icon' } });
// 4. Wait for a screen to appear
await client.wait({ text: 'Settings' }, { timeout: 5000 });
// 5. Take a screenshot
await client.screenshot({ path: './screenshot.png' });
// Disconnect
client.disconnect();
Debug
Known issues
breakingThe 'sootsim' package is ESM-only since v0.1.0. CommonJS require() will throw.fixUse 'import' syntax or set { "type": "module" } in package.json. affects: >=0.1.0
breakingSubpath exports ('sdk', 'vite', 'metro', 'detox', 'skills') are not available at the package root. Attempting to import from 'sootsim' instead of a subpath will result in undefined exports.fixUse correct subpath, e.g. import from 'sootsim/sdk'.
affects: >=0.1.0
breakingVite peer dependency requires version >=8.0.14. Using an older Vite version will cause the plugin to crash at module resolution time.fixUpgrade Vite to >=8.0.14 or remove the Vite plugin if not needed.
affects: >=0.1.0
deprecatedThe 'record' command (sootsim record) is deprecated in v0.1.120+. Use 'sootsim capture flow' instead.fixReplace 'sootsim record' with 'sootsim capture flow'.
affects: >=0.1.120 <0.2.0
gotchaThe bridge daemon (SootSimBridgeHost) listens on port 7668 by default. If another process occupies this port, the CLI will fail to start with 'EADDRINUSE'.fixKill existing daemon with 'sootsim daemon stop' or set a custom port via environment variable SOOTSIM_PORT.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Cannot find module 'sootsim'
Attempting to import from 'sootsim' without installing the package or using a wrong subpath.
fixRun 'npm install sootsim' and ensure you are using the correct import path. For the SDK use 'sootsim/sdk'.
TypeError: (0 , _sootsim.require) is not a function
Trying to use CommonJS require() on an ESM-only package.
fixReplace 'const s = require("sootsim")' with 'import s from "sootsim"' (if supported) or set "type": "module". Error: listen EADDRINUSE :::7668
The default port 7668 is already occupied by another process or a previous daemon instance.
fixRun 'sootsim daemon stop' or set SOOTSIM_PORT environment variable to a different port.
Vite plugin error: Unrecognized Vite version. Expected >=8.0.14.
Vite version is lower than the required peer dependency.
fixUpgrade Vite: npm install vite@^8.0.14
Audit
Dependencies
viteoptionalpeer dependency for the Vite plugin (vite-plugin.ts, vite-plugin-one.ts). Required at version >=8.0.14 to serve the engine runtime.