Skip to main content
Version: Latest

Initial State Configuration Guide

Overviewโ€‹

Brobot provides automatic initial state management through the @State(initial = true) annotation. This guide explains how to configure and use initial states in your Brobot applications.

Quick Startโ€‹

1. Mark Your Initial Stateโ€‹

@State(initial = true)
@Getter
@Slf4j
public class HomeState {
private StateImage logo = new StateImage.Builder()
.addPatterns("home-logo")
.build();
}

That's it! The framework will automatically:

  • Detect the initial state annotation
  • Create startup configuration
  • Activate the state when the application starts

Configuration Propertiesโ€‹

All initial state behavior can be configured via application.properties:

# Enable/disable automatic activation (default: true)
brobot.startup.auto-activate=true

# Enable/disable verification (default: true)
brobot.startup.verify=true

# Seconds to wait before verification in real mode (default: 5)
# This allows the GUI to stabilize before searching for states
brobot.startup.initial-delay=5

# Additional startup delay (default: 1)
brobot.startup.delay=1

# Search all states if initial states not found (default: false)
brobot.startup.fallback-search=false

# Only activate the first found state (default: true)
# Set to false to activate all found initial states
brobot.startup.activate-first-only=true

Advanced Featuresโ€‹

Priority-Based Selectionโ€‹

When multiple initial states exist, use priority to influence selection probability:

@State(initial = true, priority = 200)  // Higher priority
public class LoginState { }

@State(initial = true, priority = 100) // Default priority
public class HomeState { }

@State(initial = true, priority = 50) // Lower priority
public class DashboardState { }

In mock mode, states with higher priority are more likely to be selected.

Profile-Specific Initial Statesโ€‹

Different initial states for different environments:

// Only initial in test profile
@State(initial = true, profiles = {"test"})
public class TestLoginState { }

// Initial in production and staging
@State(initial = true, profiles = {"production", "staging"})
public class MainMenuState { }

// Initial in all profiles (default)
@State(initial = true)
public class DefaultState { }

Test Profile Optimizationโ€‹

The framework automatically optimizes settings for the test profile:

// When running with --spring.profiles.active=test
// These settings are applied automatically:
// - No startup delays (immediate activation)
// - Deterministic behavior (activate first only)
// - No fallback search

How It Worksโ€‹

In Mock Modeโ€‹

  1. Initial states are registered with their priorities
  2. A weighted random selection chooses one state set
  3. Selected states are immediately activated
  4. No screen verification needed

In Real Modeโ€‹

  1. Initial states are registered
  2. Application waits for initial-delay seconds (GUI stabilization)
  3. Framework searches for registered initial states on screen
  4. Found states are activated in StateMemory
  5. If no states found and fallback-search=true, searches all states

Monitoring Initial Statesโ€‹

Loggingโ€‹

The framework provides detailed logging of initial state activation:

INFO  Auto-configuring BrobotStartupConfiguration from @State(initial = true) annotations
INFO Found 1 initial states from annotations: [Home]
INFO โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
INFO AUTO-ACTIVATING INITIAL STATES
INFO โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
INFO Waiting 5 seconds before initial state verification (real mode)
INFO Searching for initial states: [Home]
INFO โœ… Successfully activated initial states: [Home]

Programmatic Accessโ€‹

Check initial states programmatically:

@Autowired
private InitialStates initialStates;

@Autowired
private StateMemory stateMemory;

// Get registered initial states
List<String> registered = initialStates.getRegisteredInitialStates();

// Check if any are registered
boolean hasInitial = initialStates.hasRegisteredInitialStates();

// Get currently active states
Set<String> active = stateMemory.getActiveStateNames();

Troubleshootingโ€‹

Initial State Not Activatingโ€‹

  1. Check annotation: Ensure @State(initial = true) is present
  2. Check profile: Verify profile matches if using profiles attribute
  3. Check timing: Increase initial-delay if GUI needs more time
  4. Check logs: Look for "AUTO-ACTIVATING INITIAL STATES" messages
  5. Check property: Ensure brobot.startup.auto-activate=true

Wrong State Activatedโ€‹

  1. Check priorities: Higher priority states are selected more often
  2. Check profiles: Ensure correct profile is active
  3. Use deterministic mode: Set activate-first-only=true

No States Found (Real Mode)โ€‹

  1. Increase delay: Set higher initial-delay value
  2. Enable fallback: Set fallback-search=true
  3. Check images: Verify pattern images exist and are correct
  4. Check similarity: Adjust pattern matching thresholds

Best Practicesโ€‹

  1. One Initial State: Keep it simple with a single initial state when possible
  2. Use Profiles: Different initial states for test vs production
  3. Set Appropriate Delays: Allow enough time for GUI to stabilize
  4. Monitor Logs: Enable INFO logging for troubleshooting
  5. Test Both Modes: Verify behavior in both mock and real modes

Example: Complete Applicationโ€‹

// HomeState.java
@State(initial = true, priority = 100)
@Getter
@Slf4j
public class HomeState {
private StateImage logo = new StateImage.Builder()
.addPatterns("home-logo")
.setName("HomeLogo")
.build();
}

// Application.java
@SpringBootApplication
@ComponentScan(basePackages = {
"com.myapp",
"io.github.jspinak.brobot"
})
public class MyApp {
public static void main(String[] args) {
SpringApplication.run(MyApp.class, args);
}
}
# application.properties
brobot.startup.auto-activate=true
brobot.startup.initial-delay=3
brobot.startup.activate-first-only=true
brobot.core.mock=false

With this configuration, the HomeState will automatically be found and activated 3 seconds after application startup.