Working with States
Define and identify application states using visual elements
What is a State?
A State represents a distinct screen, dialog, or condition in your application. In model-based automation, states form the nodes of a state machine graph that defines your automation workflow.
Key Concept: Visual Identification
Unlike traditional automation that relies on hardcoded positions or element IDs, Qontinui identifies states visually by looking for identifying images on screen. This makes automation resilient to UI changes and resolution differences.
Examples of States:
- Login Screen - Identified by login form and submit button
- Dashboard - Identified by navigation menu and welcome message
- Error Dialog - Identified by error icon and close button
Creating a State
Add a New State
Click the 'Add State' button in the state diagram panel
Name Your State
Give it a descriptive name like 'Login Screen' or 'Dashboard'. The name should clearly indicate what this state represents.
Add a Description
Write a detailed description of when this state is active and what it represents in your application.
Upload Identifying Images
Add screenshots of unique UI elements that identify this state. See the Identifying Images section below for details.
Identifying Images
Identifying images are visual elements that Qontinui uses to recognize when a state is active. When automation runs, Qontinui checks if all required identifying images are visible on screen to determine the current state.
Best Practices
- Choose Unique Elements
Select UI elements that only appear in this state (e.g., specific titles, icons, or buttons)
- Use Multiple Images
2-3 identifying images per state increases reliability and reduces false matches
- Capture Clear Screenshots
Avoid blurry or low-contrast images. Higher quality = better recognition
- Keep Images Small
Crop to just the identifying element (e.g., a button, not the entire screen)
Image Properties
Similarity Threshold
Controls how closely the screen image must match your uploaded image (0.7-0.95 typical). Lower = more fuzzy matching, higher = exact matching required.
Default: 0.85
Required
If checked, this image MUST be visible for the state to be considered active. Uncheck for optional images that only appear sometimes.
Default: Checked
Shared
Check this if the image appears in multiple states (e.g., a common toolbar). Shared images alone don't uniquely identify a state.
Default: Unchecked
State Properties
Initial State
Mark one or more states as initial where automation begins. Multiple initial states are allowed for parallel starting conditions.
Type: Boolean (checkbox)
Final State
Mark states where automation should stop. Multiple final states are allowed for different end conditions.
Type: Boolean (checkbox)
Advanced: Additional State Elements
Beyond identifying images, states can contain additional elements for more complex automation:
State Regions
Define rectangular areas within the state for searching or interaction
Examples:
- • Sidebar region
- • Content area
- • Button panel
State Locations
Define specific point coordinates for precise clicking or positioning
Examples:
- • Submit button center
- • Logo position
- • Drag anchor point
State Strings
Define text values for identification, input, or verification
Examples:
- • Username field value
- • Welcome message
- • Error text pattern
Note: Most automations only need identifying images. State regions, locations, and strings are advanced features for complex scenarios.
State Machine Concepts
Parallel States
Multiple states can be active simultaneously. This is useful for:
- Dialog boxes that appear over other screens
- Multi-panel UIs where different sections have independent states
- Persistent elements like navigation bars
State Verification
Qontinui verifies states by template matching: it searches the screen for your identifying images and checks if all required images are found. This happens automatically before executing actions and during state transitions.