How astur-mobile/astur works
1. Repository shape
- This is a TypeScript monorepo plus native Android/iOS agent code.
- The main product is a mobile automation toolkit that exposes a Playwright-style test API, but executes against native platform control paths rather than WebDriver/Appium.
2. Top-level execution flow
- A test imports @astur-mobile/test, configures test.use({ astur: ... }), and interacts with a device fixture.
- The fixture flows into packages/core, which owns sessions, locators, waiting, keyboard behavior, and inspector-facing runtime state.
- From there, core delegates to the platform package (packages/android or packages/ios), which talks to the device through native platform tools and optional agent processes.
3. Shared contract layer
- packages/protocol is the boundary for shared data types and protocol messages.
- It is the common language between core, platform drivers, and native agents, so selector semantics and response shapes stay aligned across Android and iOS.
4. Core runtime
- packages/core is the central orchestration layer.
- It implements sessions, locator resolution, auto-waiting, keyboard actions, config parsing, and error shaping.
- This is the layer that turns Playwright-like calls such as getByRole, tap, expect(...).toBeVisible(), and scrollIntoView() into platform-specific operations.
5. Android architecture
- packages/android is the host-side Android driver.
- It uses ADB for lifecycle tasks, artifacts, and legacy fallback paths, but the default interaction path is a native Kotlin UIAutomator agent.
- The internal agent code lives in packages/android-agent, built as APK artifacts and shipped under packages/android/assets/agent.
- Android responsibilities include device discovery, emulator boot, app install/launch, screenshots, video, web URL opening, file transfer, and selector execution.
6. Android interaction boundary
- The Android flow is split between host orchestration and on-device execution.
- Host code chooses whether to operate through the Kotlin agent or the explicit ADB/XML fallback.
- This keeps long-running device control on the native side while reserving ADB for setup, diagnostics, and compatibility.
7. iOS architecture
- packages/ios is the host-side iOS driver.
- It uses simctl and devicectl for diagnostics, simulator/real-device management, install/launch/terminate, and screenshots.
- Native element lookup and gestures require the bundled Swift XCUITest agent under packages/ios/assets/ios-xctest-agent.
- The iOS agent boundary includes a host app, a bridge client/server, and XCTest-based UI test code.
8. iOS platform constraint
- The iOS design makes the XCTest boundary explicit: native element control is not done through a generic cross-platform protocol alone.
- Real devices require signing and an Apple team for the XCUITest runner, which is an architectural dependency rather than just a build detail.
9. Test integration and public API
- packages/test is the Playwright Test integration layer that exports the test and expect APIs.
- packages/astur-mobile is the public npm-facing package that exposes the astur-mobile CLI entrypoint.
- The combination gives consumers a familiar Playwright-like surface while hiding device-specific runtime wiring underneath.
10. CLI and inspector
- packages/cli contains operational tooling: doctor, devices, init, codegen, inspect, and test.
- It also hosts the inspector server and UI, which are separate from the test runtime and used for discovery/codegen/debug workflows.
- npx astur-mobile inspect is an alias for code generation, reinforcing the CLI as both setup and introspection tooling.
11. Scaffolding, examples, and documentation
- packages/create-astur is the project scaffolder for npm create astur.
- examples/ contains runnable Android and iOS suites that demonstrate the expected test architecture and fixture usage.
- docs/ holds the canonical source docs, and docs-site/ is the Astro-based static site that publishes them.
12. Native assets and distribution
- Native binaries and demo apps are checked into assets/ and package-local assets/ folders so the repo can build and smoke-test without external bootstrapping.
- The Android agent APKs and the iOS XCTest agent sources are distributed as package assets, which is why the repo has both source trees and packaged copies.
13. Verification and release pipeline
- tests/ contains unit and integration coverage for parsers, runtime behavior, locator semantics, agent modes, and platform-specific flows.
- GitHub workflows cover CI, docs publishing, native smoke tests, promotion, and release.
- That means the repo’s architecture is validated at three levels: pure TypeScript logic, host-to-device driver behavior, and native agent packaging.
14. How to diagram it
- Draw the center as @astur-mobile/test and packages/core.
- Branch left/right into Android and iOS drivers.
- Under each driver, separate host orchestration from on-device agent execution.
- Keep packages/protocol as a shared boundary feeding both platform stacks.
- Place CLI, inspector, docs, examples, and scaffolding as adjacent support systems rather than part of the runtime data path.
Main entry points: src/index.ts Core runtime · src/index.ts Android host · core-runtime.test.ts Verification · src/index.ts CLI
Components 19
Runtime
Test-facing API and orchestration layers that drive devices.
- Test API · Public test surface exporting test and expect.
packages/test/src/index.ts - Core runtime · Sessions, locators, waiting, keyboard actions, config, and errors.
packages/core/src/index.ts - Protocol · Cross-package message and selector types shared by core and drivers.
packages/protocol/src/index.ts - Sessions · Device/session lifecycle and runtime state management.
packages/core/src/session.ts - Locators · Playwright-style selector resolution and action targeting.
packages/core/src/locator.ts - Waiting · Expectation and retry behavior for visible, stable, and ready states.
packages/core/src/wait.ts - Keyboard · Text entry and key handling inside the runtime.
packages/core/src/keyboard.ts
Android
Host driver, native agent, and packaged assets for Android execution.
- Android host · Host-side Android control path using ADB plus native agent fallback.
packages/android/src/index.ts - ADB control · Lifecycle, artifacts, install, launch, screenshots, and compatibility paths.
packages/android/src/command.ts - XML fallback · Legacy selector and device interaction path when agent execution is not used.
packages/android/src/uiautomatorXml.ts - Android agent · Kotlin UIAutomator agent bundled as APK artifacts and run on-device.
packages/android-agent/src/androidTest/kotlin/dev/astur/agent/AsturAgentServer.kt
iOS
Host driver, native agent, and packaged assets for iOS execution.
Support
CLI, scaffolding, docs, examples, and shared contracts.
- Mobile pkg · Public package and CLI entrypoint for astur-mobile.
packages/astur-mobile/src/index.ts - CLI · doctor, devices, init, codegen, inspect, test, and inspector server/UI.
packages/cli/src/index.ts - Scaffolder · npm create astur project bootstrapper.
packages/create-astur/src/index.ts - Examples · Android and iOS example test suites demonstrating fixture usage.
examples/android-native/playwright.config.ts - Docs · Canonical docs content and the Astro-based docs site.
docs/architecture.md
Quality
Tests and CI workflows that validate the stack.
- Verification · Unit and integration coverage for core, drivers, parsers, and agent modes.
tests/core-runtime.test.ts
Connections 22
- Test API → Core runtime: uses · The test API delegates device behavior into core orchestration.
- Mobile pkg → Test API: exports · The public package exposes the test-facing entrypoint.
- Core runtime → Protocol: shares types · Core and drivers communicate through the protocol contract.
- Core runtime → Sessions: manages · Sessions hold runtime state and device attachment.
- Core runtime → Locators: resolves · Selectors are turned into platform actions through locator resolution.
- Core runtime → Waiting: waits · Core applies auto-wait and expectation retry logic.
- Core runtime → Keyboard: types · Keyboard behavior is part of the central runtime.
- Core runtime → Android host: targets · Core dispatches Android operations through the platform driver.
- Core runtime → iOS host: targets · Core dispatches iOS operations through the platform driver.
- Android host → ADB control: orchestrates · Host-side Android setup and diagnostics are handled via ADB tooling.
- Android host → XML fallback: falls back · The driver can switch to XML/legacy paths when needed.
- Android host → Android agent: executes via · Default Android interaction uses the native Kotlin agent.
- Android agent → Protocol: implements · Android agent messages and selectors align with the shared protocol.
- iOS host → iOS agent: executes via · iOS native element control uses the bundled XCTest agent.
- iOS agent → Protocol: implements · iOS agent behavior follows the shared protocol contract.
- CLI → Core runtime: inspects · CLI inspection and codegen interact with runtime concepts.
- CLI → Examples: supports · CLI tooling helps bootstrap and exercise example suites.
- Scaffolder → CLI: integrates · Project creation is part of the operational toolchain.
- Docs → Core runtime: documents · Docs explain runtime behavior, platform limits, and setup.
- Verification → Core runtime: verifies · Tests cover core runtime behavior and locator semantics.
- Verification → Android host: verifies · Tests cover Android parser and agent-mode flows.
- Verification → iOS host: verifies · Tests cover iOS parser and agent-mode flows.