Before You Begin
Export Configuration from Qontinui Web
Download your automation configuration as a JSON file from Qontinui Web.
- 1.Open your project in Qontinui Web
- 2.Click the 'Export' button in the top menu
- 3.Save the JSON file to your computer
- 4.Note the file location for loading into Runner
Install Qontinui Runner
Download and install Qontinui Runner for your operating system.
Download Runner →Prepare Target Application
Ensure the application you're automating is running and in the expected initial state.
Loading Your Configuration
Launch Qontinui Runner
Open the Qontinui Runner application on your system.
Load Configuration File
Click 'Load Configuration' and select your exported JSON file.
Verify Configuration Loaded
Check that states, processes, and images appear in the Runner interface.
Configuration Validation: Runner automatically validates your configuration on load. Check for warnings or errors in the console output.
Common issues: missing images, invalid state references, malformed processes
Execution Modes
Run from Initial State
Start automation from states marked as is_initial=true
- •Runner identifies all initial states
- •Verifies initial state is active (checks identifying images)
- •Begins executing outgoing transitions
- •Continues until final state or no transitions available
Best for: Most common mode - full automation workflows
Run Specific Process
Execute a single process by ID without state machine navigation
- •Select a process from the list
- •Process actions execute sequentially
- •No state transitions occur
- •Useful for testing individual workflows
Best for: Testing and debugging individual processes
Run from Custom State
Start automation from a specific state (not necessarily initial)
- •Select target state from state list
- •Runner verifies state is active
- •Execution proceeds from that state
- •Useful for resuming or testing specific sections
Best for: Debugging or running partial workflows
Execution Settings
Configure how Qontinui Runner executes your automation. These settings are typically defined in your JSON configuration but can sometimes be overridden in Runner.
default_timeout
Integer (milliseconds)Maximum time to wait for actions and transitions to complete. Increase for slow applications.
Default: 10000
default_retry_count
IntegerNumber of retry attempts for failed actions. Higher values improve reliability but increase execution time.
Default: 3
action_delay
Integer (milliseconds)Delay between consecutive actions. Increase if UI doesn't have time to respond between actions.
Default: 100
failure_strategy
StringHow to handle failures: 'stop' (halt on error), 'continue' (log and proceed), 'retry' (retry then stop).
Default: stop
Monitoring Execution
Real-Time Console Output
Watch execution progress with detailed logging:
- Current state and active transitions
- Actions being executed with parameters
- Image recognition results and similarity scores
- Errors, warnings, and retry attempts
- Execution timing and performance metrics
State Transition Visualization
See the automation flow through your state machine:
- Highlighted current state(s)
- Executed transitions marked
- State history breadcrumb trail
- Parallel state indicators
Screenshot Capture
Automatically capture screenshots during execution:
- Before and after each critical action
- On errors or failed image recognition
- At state transitions for verification
- Saved to timestamped execution folder
Troubleshooting Execution Issues
Execution stops immediately: 'Initial state not found'
Solutions:
- •Verify at least one state has is_initial=true in your configuration
- •Check that initial state's identifying images match current screen
- •Lower similarity thresholds if images aren't being recognized
- •Ensure target application is in the expected initial state
Actions timing out or failing repeatedly
Solutions:
- •Increase default_timeout for slow applications (e.g., 15000ms)
- •Increase action_delay to give UI more time between actions
- •Check if application is waiting for user input or has modal dialogs
- •Verify images are still accurate and haven't changed
- •Look for loading animations or spinners blocking interactions
Image recognition failing: 'Image not found on screen'
Solutions:
- •Verify image is actually visible on current screen
- •Lower similarity threshold (try 0.8 instead of 0.9)
- •Recapture image if UI has changed
- •Check if image is outside search region
- •Enable multi-scale search if resolution differs
- •Look for overlapping windows or notifications covering element
State machine stuck: 'No applicable transitions found'
Solutions:
- •Check that current state has outgoing transitions defined
- •Verify transition conditions are met
- •Ensure to_state exists and is reachable
- •Review state history to see how automation arrived at stuck state
- •Add transitions to connect isolated states
Execution too slow or hanging
Solutions:
- •Reduce default_retry_count if not needed (try 1 or 2)
- •Decrease action_delay for faster execution (try 50ms)
- •Use search regions to limit image search areas
- •Disable multi-scale search if not needed
- •Check for infinite loops in state transitions
- •Review process complexity - break into smaller steps
Best Practices
Test with mock execution first
Always test your automation with mock execution in Qontinui Web before running with Runner. This validates logic without requiring a real GUI environment.
Start with slower, more reliable settings
Use higher timeouts, more retries, and longer delays initially. Optimize for speed only after confirming reliability.
Monitor the first few executions
Watch execution closely the first few times. Check console output for warnings, verify image recognition scores, note timing issues.
Add wait actions for slow operations
After actions that trigger page loads, animations, or API calls, add explicit WAIT actions or use VANISH to wait for loading spinners.
Use FIND before CLICK for reliability
Always use FIND action before CLICK to verify element exists and update 'Last Find Result'. This catches missing elements early.
Capture execution screenshots
Enable automatic screenshot capture during execution. Screenshots are invaluable for debugging failures and verifying behavior.
Handle errors gracefully
Use continue_on_error for optional actions. Add error handling transitions to recover from common failure scenarios.