@goliapkg/smix

中文文档
25.1.0发布于 2026/11/11Apache-2.0 OR MITTypeScriptES Module零依赖近 30 天下载 3385

Playwright-shape iOS Simulator / Android emulator UI automation SDK for React Native + Expo + Detox-compatible TypeScript test runners.

原始使用文档
文档目录6 节
  1. What works today
  2. Installation
  3. Selector
  4. Session lifecycle
  5. ExpectationFailure
  6. License

@goliapkg/smix

TypeScript types and host-side building blocks for smix — AI-native UI automation for the iOS Simulator and Android emulator.

Live driving runs through the napi addon. This package ships the same typed API surface as the Swift / Kotlin / Rust SDKs; Smix.launchApp, App.tap, App.fill, and the rest drive a device by calling into @goliapkg/smix-node. Smix.launchApp loads the per-platform addon automatically (via loadNodeDriver); the addon is built by a per-triple prebuild matrix in CI, and its npm release follows in a later version — you can also inject a NodeDriver explicitly for tests or a custom transport. Three surfaces still throw SmixNotImplementedError pending their transport: App.screenshot and App.openUrl need a runner wire route, and App.launchFresh needs host-side state clearing. To drive a device without the addon today, use the smix CLI or one of the Swift / Kotlin / Rust SDKs.

What works today

  • Selector DSL — the full selector language, encoding to the exact JSON wire shape the Rust core resolves.
  • Session lifecycle — Session.open / stillValid / relaunchApp / renewActivation / close against a running smix runner, over HTTP.
  • ExpectationFailure — parse and produce smix's AI-readable failure JSON.
  • A11yNode — typed accessibility-tree model with flatten / findById / rectCenter helpers for working with smix tree --json output.

Installation

bun add -D @goliapkg/smix
# OR
npm install -D @goliapkg/smix

Test-target only: keep it in devDependencies, never bundled into a production RN / Expo app.

Selector

import { Selector, literal, regex } from '@goliapkg/smix'

Selector.id('btn-login')
Selector.text(literal('Sign In'))
Selector.text(regex('^Sub', 'i'))
Selector.label('Settings')
Selector.role('button', literal('Submit'))
Selector.localizedText({ en: 'Submit', ja: '送信' })

// Fluent modifier chaining (returns a new Selector)
Selector.id('btn').below(Selector.text(literal('Address'))).nth(0)
Selector.role('button').near(Selector.text(literal('Confirm')))

Wire JSON (untagged + flattened — byte-identical to Rust smix-selector):

{"id": "btn-login", "below": {"text": "Address"}, "nth": 0}

Session lifecycle

import { HttpSimRuntime, Session } from '@goliapkg/smix'

const runtime = new HttpSimRuntime('http://127.0.0.1:22087')
const session = await Session.open(runtime, 'com.example.app')
await session.relaunchApp()
await session.close()

HttpSimRuntime also exposes resolver / labelsResolver, which resolve a selector against a caller-supplied tree JSON via the runner's /select/resolve routes.

ExpectationFailure

import { ExpectationFailure } from '@goliapkg/smix'

try {
  // a driving call, once the native transport lands
} catch (e) {
  if (e instanceof ExpectationFailure) {
    e.code            // 'ELEMENT_NOT_FOUND' | 'AMBIGUOUS' | 'TIMEOUT' | ...
    e.visibleElements // A11yNode[] — context for AI diagnosis
    e.suggestions     // string[]
    e.toJson()        // single-line JSON for agent consumption
  }
}

License

Apache-2.0 OR MIT (dual, at your option).

版本与发布记录

@goliapkg/smix 共发布 90 个版本,首次发布于 2026/06/30;过去 12 个月发布了 90 个版本。

版本发布日期距今
25.1.0latest2026/11/116 天前
25.0.02026/11/106 天前
24.0.02026/11/088 天前
23.5.02026/11/0710 天前
23.4.02026/11/0511 天前
23.0.02026/11/0313 天前

其他发布通道:ship-preflight → 6.2.0。

关于 @goliapkg/smix 的常见问题

@goliapkg/smix 是什么?

Playwright-shape iOS Simulator / Android emulator UI automation SDK for React Native + Expo + Detox-compatible TypeScript test runners.

如何安装 @goliapkg/smix?

在项目目录运行 npm install @goliapkg/smix,或使用 pnpm add / yarn add / bun add。

@goliapkg/smix 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@goliapkg/smix 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@goliapkg/smix 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@goliapkg/smix 可以商用吗?

@goliapkg/smix 使用 Apache-2.0 OR MIT 许可。可在 Apache-2.0、MIT 中任选其一遵守。选择 Apache-2.0 时,宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@goliapkg/smix 的下载量有多少?

根据 npm 官方下载统计,@goliapkg/smix 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,385 次,日均约 113 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@goliapkg/smix 还在维护吗?

最新版本 25.1.0 发布于 2026/11/11(6 天前);至今共发布 90 个版本,其中过去 12 个月发布了 90 个;首次发布于 2026/06/30。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。