Quick Start

Define an automation in JSON and run it with the Python API

What You'll Build

Qontinui drives GUI automation from a declarative model: you describe states (screens, identified visually) and workflows (sequences of actions), then let the library execute them. The fastest way to start is a JSON configuration loaded and run through JSONRunner.

Before you begin: make sure Qontinui is installed. See the Installation guide if you haven't set it up yet.

Describe Your Automation in JSON

Create a file named automation_config.json. It declares the states Qontinui should recognize and the workflow of actions to perform:

{
  "version": "1.0",
  "states": [
    {
      "name": "LoginScreen",
      "stateImages": [
        { "imageId": "login_button", "threshold": 0.9 }
      ]
    }
  ],
  "processes": [
    {
      "name": "Login",
      "actions": [
        {
          "type": "CLICK",
          "target": { "type": "image", "imageId": "login_button" }
        },
        { "type": "TYPE", "text": "username@example.com" }
      ]
    }
  ]
}

Visual identification: each stateImage references an image and a similarity threshold. Qontinui finds states by matching these images on screen rather than relying on hardcoded coordinates.

Load and Run It

Use JSONRunner to load the configuration and execute a named workflow. The run() method takes the workflow id (the workflow's name) and an optional monitor index:

from qontinui.json_executor import JSONRunner

# Create the runner
runner = JSONRunner()

# Load and validate the configuration
runner.load_configuration("automation_config.json")

# Execute the "Login" workflow on the primary monitor
success = runner.run("Login", monitor_index=0)

print("Automation succeeded" if success else "Automation failed")

load_configuration() parses and validates the JSON, then initializes the executors and hardware backends. It returns True on success.
run() executes the named workflow and returns a boolean indicating overall success.

Or Build the Model in Code

The same building blocks are exported directly from the qontinui package, so you can construct states and actions in Python instead of JSON:

from qontinui import State, StateImage, Region, Location

# A state is identified by one or more images
login_screen = State(name="LoginScreen")

# A region describes a rectangular search area (x, y, width, height)
form_area = Region(x=100, y=200, width=400, height=300, name="login_form")

# A location is a point target for actions like click/hover
submit_point = Location(x=320, y=480)

print(login_screen.name, form_area.width, submit_point.x)

Note: Qontinui's action methods (find, click) are asynchronous — they are async coroutines that you await inside an async function. See the Examples page for full async patterns.

Quick Start

What You'll Build

Describe Your Automation in JSON

Load and Run It

Or Build the Model in Code

Next Steps

Examples

Installation