Skip to content
Astur Astur Astur

Architecture

Astur keeps the test authoring experience small while moving the expensive mobile work into native platform agents.

User test@astur-mobile/test
Core runtimelocators, waits, assertions
Protocolselectors and commands
Android
Android driverADB lifecycle
UIAutomator agentnative lookup and actions
Android appapp under test
iOS
iOS driversimctl and xcodebuild lifecycle
XCUITest agentnative lookup and actions
iOS appapp under test

The public API remains Playwright-style:

await device.getByRole('button', { name: 'Sign in' }).tap();
await expect(device.getByText('Welcome')).toBeVisible();

The runtime below that API handles device selection, app lifecycle, native locator lookup, actionability checks, gestures, screenshots, video, traces, and inspector/codegen support.

The source docs/architecture.md keeps Mermaid diagrams for repository readers. The public Astro docs use an MDX/CSS version of the same graph because Starlight does not render Mermaid fences automatically without adding a Mermaid integration.

Why This Is Fast

Section titled “Why This Is Fast”

Traditional Appium-style stacks usually add a WebDriver server between the test and the native automation framework. Astur avoids that extra protocol translation layer.

1Test calls getByLabel("Login").tap()
2Astur sends one native command: find, wait, tap
3The platform agent resolves and acts locally
4Astur receives compact result, timing, and diagnostics

For common actions, Astur sends the intent once. The platform agent resolves and acts locally, so the host does not repeatedly pull large UI trees just to retry a locator.

Lifecycle Vs Interaction

Section titled “Lifecycle Vs Interaction”

Astur still uses platform tools where they are the right tool:

  • Android lifecycle: adb installs apps, launches packages, captures screenshots, records video, and gathers logs.
  • iOS lifecycle: simctl, devicectl, and xcodebuild manage simulators, app install/launch, screenshots, and the XCUITest runner.
  • Element interaction: native Android and iOS agents perform lookup, waits, taps, fills, drags, swipes, and keyboard commands.
  • Flutter (Android): when a Flutter APK is detected, Astur reads the live widget tree through the Dart VM service instead of UIAutomator, while ADB still handles lifecycle and gestures. See Frameworks: Flutter & React Native.

Lifecycle tools

Manage devices, apps, screenshots, video, and logs through ADB, simctl, devicectl, and xcodebuild.

Persistent native agents

Run locator polling, actionability checks, and gestures close to the platform UI framework.

This split keeps lifecycle reliable without putting slow shell commands in the normal element-interaction path.

Inspector And Codegen

Section titled “Inspector And Codegen”

Astur Inspector uses the same runtime and selector model as tests.

Live screen
+
Semantic tree
→
Locator ranking
→
@astur-mobile/test code

The inspector does not invent a second locator system. When it suggests a locator, records a tap, or exports code, it uses the same platform-neutral locator contracts that execute during test runs.

Reliability Rules

Section titled “Reliability Rules”
  • Prefer semantic locators over coordinates.
  • Keep native polling inside the platform agent.
  • Use screenshots and UI snapshots for diagnostics, not as the default control path.
  • Keep one platform agent alive per Playwright worker when possible.
  • Reserve one physical device per Playwright worker; true parallelism requires multiple devices.
  • When a config uses a loose device selector, let Astur choose an available matching device from the local pool instead of sending all workers to the same first device.
  • Restart or reset the app between specs only when isolation requires it.
  • Keep iOS XCTest requirements explicit instead of hiding them behind WebDriver.

Package Shape

Section titled “Package Shape”

Most users install:

Terminal window
npm install -D @astur-mobile/test astur-mobile

@astur-mobile/test gives the Playwright fixture and assertions. astur-mobile gives the CLI, including doctor, devices, init, test, and codegen. Internal packages such as @astur-mobile/core, @astur-mobile/android, and @astur-mobile/ios stay published as normal npm packages so the project remains modular, but end users should not need to wire them manually.

Support Astur