Midscene.js

repository·main·Indexed 12 days ago

https://github.com/web-infra-dev/midscene

A vision-driven UI automation and testing framework that uses multimodal AI models to interact with web browsers, mobile apps (Android, iOS, HarmonyOS), and desktop applications via screenshots and natural language. It provides a JavaScript SDK, a Chrome Extension, and YAML scripting to perform actions, extract data, and execute assertions without relying on fragile DOM selectors. Integrates with Playwright and Puppeteer.

Tokens
171.8K
Snippets
537
Records
778
Agent score
97%

What's inside Midscene

  1. Overview of Midscene capabilities

    main

    Midscene is an AI-driven automation tool that allows you to automate browser actions, extract data, and perform assertions using multimodal models. It provides multiple ways to interact with web interfaces:

    • JavaScript SDK: For programmatic automation within your code.
    • Chrome Extension: For interactive, browser-based automation.
    • YAML Scripting: For defining automation workflows in a declarative format.

    For more detailed information, visit the official website at https://midscenejs.com/.

  2. What is Midscene.js

    main

    Midscene.js is an open-source, vision-driven UI automation and testing framework. Unlike traditional automation tools that rely on fragile DOM selectors or accessibility trees, Midscene uses multimodal models to interact with interfaces based on screenshots and natural language descriptions.

    Key Benefits

    • Low Maintenance: No selectors to update when the UI changes.
    • Universal Reach: Can target any element a human can see, including <canvas>, native apps, and cross-origin iframes.
    • Visual Assertions: Verify layout, colors, and rendered state rather than just DOM existence.
    • Flexible Integration: Use it as a plugin for Playwright / Vitest, or use Midscene Skills to let AI agents act autonomously.
  3. Overview of Midscene.js vision-driven automation

    main

    Midscene is an open-source SDK designed for vision-driven UI testing and automation. Unlike traditional tools that rely on the DOM or accessibility trees, Midscene operates using screenshots and multimodal models. This allows it to automate interfaces that are often invisible to structure-based tools, such as <canvas> surfaces, native mobile apps (Android, iOS, HarmonyOS), desktop applications, and cross-origin iframes.

    Key capabilities include:

    • Resilience to refactors: Since it uses visual recognition rather than CSS/XPath selectors, tests don't break when markup or styles change.
    • Visual assertions: You can verify colors, layouts, and rendered states directly.
    • Broad platform support: One API covers web, mobile, and desktop.
    • Visual reporting: Every run generates a visual report for step-by-step replay.
  4. Overview of Midscene AI-powered automation

    main
    Midscene is an AI-powered automation SDK that allows developers to control web pages, perform assertions, and extract data in JSON format using natural language instructions. Instead of writing brittle selectors, you can use high-level descriptions of the actions you want to perform.
  5. Overview of Midscene API Reference

    main

    The Midscene API reference provides documentation for shared Agent APIs and platform-specific implementations.

    • Shared Agent APIs: Covers agent options, interaction, extraction, observation, workflows, reporting, shared types, and report utilities. These are inherited by platform-specific agents unless otherwise noted.
    • Platform-Specific APIs: Includes specialized constructors, options, actions, and helper methods for:
      • Web: Puppeteer, Playwright, and Chrome Bridge.
      • Android: Android device, Agent, factory, and utility APIs.
      • iOS: iOS device, Agent, factory, and utility APIs.
      • HarmonyOS: HarmonyOS device, Agent, factory, and utility APIs.
      • Desktop: Local desktop and RDP APIs.
    • Runtime Configuration: Global environment variables for run artifacts, language, Playground networking, and Debug logs.

    Note: This reference focuses on API contracts. For installation, end-to-end workflows, and troubleshooting, refer to the specific platform guides.

  6. Explore community extensions for iOS, PC, Python, and Java

    main

    Midscene can be extended to various platforms and programming languages through community-driven projects. Use these to expand your automation capabilities beyond the core JavaScript/TypeScript environment:

    iOS Automation

    • midscene-ios: Provides iOS Mirror automation support, enabling automated testing and interaction with iOS applications.

    PC Automation

    • midscene-pc: A device for operating Windows, macOS, and Linux desktop applications. Supports both local and remote operations.
    • midscene-pc-docker: A Docker container (Ubuntu 20 with GNOME) with the Midscene-PC server pre-installed. Includes a built-in VNC service for browser-based desktop monitoring, allowing you to deploy automation clients on standard servers.

    Python SDK

    • Midscene-Python: A Python SDK that allows integration of Midscene's AI-powered automation into existing Python testing and automation workflows.

    Java SDK

    • midscene-java: A JVM-friendly SDK for scripting Midscene experiences.
    • midscene-java: A JVM-native interface designed to integrate with established Java testing frameworks.
  7. MobileWorld Benchmark Report Overview

    main

    The MobileWorld benchmark evaluates Midscene's performance on Android Agent tasks. The benchmark consists of 117 tasks covering cross-app workflows, long-horizon tasks, user interaction, and tool-augmented tasks in realistic mobile scenarios.

    Key metrics for the reported version include:

    • Pass@1 score: 78.63% (92/117 tasks passed).
    • Benchmark Environment: Uses MobileWorld with a Midscene benchmark adapter that delegates execution via Midscene RPC.
  8. Use @midscene/web for AI-driven web automation

    main

    @midscene/web allows you to automate UI actions, extract data, and perform assertions in web browsers using AI. It is designed to work with existing browser automation frameworks rather than replacing them.

    To use Midscene for web automation, you can integrate it with one of the following frameworks:

    • Playwright: For deep integration within Playwright tests.
    • Puppeteer: For automation using the Puppeteer API.
    • Bridge mode: For scenarios where you need to connect Midscene to a running browser instance or a different environment.
  9. Use @midscene/ios for iOS automation

    main
    @midscene/ios is an automation library for Midscene that provides AI-powered testing and automation capabilities specifically for iOS simulators and physical devices. It allows you to leverage multimodal models to interact with iOS applications using natural language instructions.
  10. Understand the Midscene AndroidWorld Benchmark results

    main

    Midscene is evaluated using the AndroidWorld benchmark from Google Research. This benchmark runs on a live Android emulator and evaluates agents on 116 programmatic tasks across 20 real-world Android apps.

    In the reported run, Midscene achieved the following success rates:

    • Pass@1: 93.10%
    • Pass@2: 95.69%
    • Pass@3: 97.41%

    Run Configuration Details

    • Model Name: Gemini-3.5-Flash
    • Midscene version: 1.9.5
    • DeepThink: on
    • MIDSCENE_REPLANNING_CYCLE_LIMIT: 120