Version: Latest

Test Utilities

Brobot provides comprehensive test utilities to help you write robust and maintainable tests. The framework includes base classes, utility methods, and centralized mock mode management.

BrobotTestBase - Base Test Class

All Brobot tests should extend BrobotTestBase to ensure proper test configuration:

import io.github.jspinak.brobot.test.BrobotTestBase;
import org.junit.jupiter.api.Test;

public class MyBrobotTest extends BrobotTestBase {
    
    @Test
    public void testMyFeature() {
        // Mock mode is automatically enabled
        // Test will work in headless environments
    }
    
    @Test
    public void testWithRealMode() {
        // Temporarily disable mock mode
        disableMockMode();
        try {
            // Test with real screen capture
        } finally {
            // Re-enable mock mode
            MockModeManager.setMockMode(true);
        }
    }
}

What BrobotTestBase Provides:

Automatic mock mode activation via MockModeManager
Headless environment compatibility
Fast mock timings (0.01-0.04 seconds for operations)
CI/CD pipeline support
Prevention of AWTException and HeadlessException errors

Test Utility Classes

BrobotTestUtils - Common Test Helpers

Provides factory methods for creating test data:

import io.github.jspinak.brobot.test.utils.BrobotTestUtils;

// Create test objects
State testState = BrobotTestUtils.createTestState("MyState");
StateImage testImage = BrobotTestUtils.createTestStateImage("TestImage");
Match testMatch = BrobotTestUtils.createTestMatch(100, 100, 50, 50, 0.95);

// Create multiple test matches
List<Match> matches = BrobotTestUtils.createTestMatches(5);

// Create action results
ActionResult success = BrobotTestUtils.createSuccessfulResult(3);
ActionResult failure = BrobotTestUtils.createFailedResult();

MatTestUtils - OpenCV Mat Testing Utilities

Comprehensive utilities for safe OpenCV Mat operations in tests:

import io.github.jspinak.brobot.test.utils.MatTestUtils;

// Create safe, validated Mats
Mat colorMat = MatTestUtils.createColorMat(100, 100, 255, 0, 0); // Red
Mat grayMat = MatTestUtils.createGrayMat(100, 100, 128);

// Create test patterns
Mat checkerboard = MatTestUtils.createCheckerboardMat(200, 200, 25);
Mat gradient = MatTestUtils.createGradientMat(100, 100, true);
Mat circle = MatTestUtils.createShapeMat(100, 100, 1);

// Validate Mats before operations
MatTestUtils.validateMat(mat, "before processing");

// Safe cleanup
MatTestUtils.safeReleaseAll(mat1, mat2, mat3);

Key Features:

Prevents JVM crashes from invalid Mat operations
Provides validation and safe cleanup
Includes pattern generation for testing
Motion detection test helpers

See Mat Testing Utilities for complete documentation.

MockModeManager - Centralized Mock Control

The MockModeManager provides a single source of truth for mock mode configuration:

import io.github.jspinak.brobot.config.MockModeManager;

// Enable mock mode globally
MockModeManager.setMockMode(true);

// Check current mock mode
boolean isMock = MockModeManager.isMockMode();

// Debug mock mode state across all components
MockModeManager.logMockModeState();

BrobotTestUtils - Test Data Creation

The BrobotTestUtils class provides utilities for creating test data:

Overview

Located at io.github.jspinak.brobot.test.utils.BrobotTestUtils, this utility class provides:

Factory methods for creating test objects
Random data generators for realistic test scenarios
Assertion helpers for approximate comparisons
Environment detection utilities
Timing and synchronization helpers

Factory Methods

Creating Test States

// Create a simple test state
State testState = BrobotTestUtils.createTestState("LoginPage");

// Create with custom properties
State.Builder builder = new State.Builder("HomePage");
builder.setBlocking(true);
State customState = builder.build();

Creating Test StateImages

// Create a test StateImage
StateImage testImage = BrobotTestUtils.createTestStateImage("submitButton");

// The created StateImage has default similarity settings

Creating Test Matches

// Create a match at specific location
Match match = BrobotTestUtils.createTestMatch(
    100,  // x
    200,  // y
    50,   // width
    50,   // height
    0.95  // score
);

// Create a random match for testing
Match randomMatch = BrobotTestUtils.createRandomMatch();

// Create multiple matches
List<Match> matches = BrobotTestUtils.createTestMatches(5);

ActionResult Creation

Successful Results

// Create a successful result with 3 matches
ActionResult success = BrobotTestUtils.createSuccessfulResult(3);

// Verify the result
assertTrue(success.isSuccess());
assertEquals(3, success.getMatches().size());

Failed Results

// Create a failed result
ActionResult failed = BrobotTestUtils.createFailedResult();

// Verify the result
assertFalse(failed.isSuccess());
assertTrue(failed.getMatches().isEmpty());

Location and Region Utilities

Working with Locations

// Create a specific location
Location loc = BrobotTestUtils.createTestLocation(100, 200);

// Create a random location within screen bounds
Location randomLoc = BrobotTestUtils.createRandomLocation();

// Compare locations with tolerance
Location loc1 = new Location(100, 100);
Location loc2 = new Location(102, 98);
boolean isClose = BrobotTestUtils.areLocationsApproximatelyEqual(
    loc1, loc2, 5  // tolerance in pixels
);

Working with Regions

// Create a specific region
Region region = BrobotTestUtils.createTestRegion(
    10,   // x
    20,   // y
    100,  // width
    50    // height
);

// Create a random region
Region randomRegion = BrobotTestUtils.createRandomRegion();

// Compare regions with tolerance
boolean isClose = BrobotTestUtils.areRegionsApproximatelyEqual(
    region1, region2, 3  // tolerance in pixels
);

Environment Detection

CI/CD Detection

@Test
void testRequiringDisplay() {
    if (BrobotTestUtils.isRunningInCI()) {
        // Skip or use mock mode in CI environment
        assumeFalse(true, "Skipping in CI environment");
    }
    
    // Test requiring actual display
    // ...
}

Headless Environment Detection

@Test
void testScreenCapture() {
    if (BrobotTestUtils.isHeadless()) {
        // Use mock mode for headless environments
        FrameworkSettings.mock = true;
    }
    
    // Proceed with test
    // ...
}

Timing Utilities

Sleep Functions

// Short sleep (100ms)
BrobotTestUtils.shortSleep();

// Custom sleep duration
BrobotTestUtils.sleep(500);  // 500ms

// Use in test scenarios
@Test
void testWithTiming() {
    action.click(button);
    BrobotTestUtils.shortSleep();  // Wait for UI to update
    assertTrue(isDialogVisible());
}

Test Name Generation

// Generate unique test names
String testName = BrobotTestUtils.generateTestName("TestRun");
// Result: "TestRun_1735000123456_789"

// Useful for creating unique test resources
String imageName = BrobotTestUtils.generateTestName("testImage");
StateImage image = new StateImage.Builder()
    .setName(imageName)
    .build();

Best Practices

1. Use Factory Methods for Consistency

@Test
void testStateTransition() {
    // Good: Use factory methods
    State fromState = BrobotTestUtils.createTestState("LoginPage");
    State toState = BrobotTestUtils.createTestState("HomePage");
    
    // Test transition logic
    // ...
}

2. Leverage Random Data for Robustness

@Test
void testMatchProcessing() {
    // Test with various random matches
    for (int i = 0; i < 10; i++) {
        Match match = BrobotTestUtils.createRandomMatch();
        // Process match
        assertTrue(processMatch(match));
    }
}

3. Use Environment Detection for Conditional Testing

@BeforeEach
void setup() {
    if (BrobotTestUtils.isHeadless() || BrobotTestUtils.isRunningInCI()) {
        // Enable mock mode for headless/CI environments
        FrameworkSettings.mock = true;
    }
}

4. Approximate Comparisons for UI Testing

@Test
void testMouseMovement() {
    Location expected = new Location(100, 100);
    action.move(expected);
    
    Location actual = Mouse.at();
    
    // Allow for small variations in mouse position
    assertTrue(BrobotTestUtils.areLocationsApproximatelyEqual(
        expected, actual, 2
    ));
}

Integration with Test Frameworks

JUnit 5 Integration

@ExtendWith(MockitoExtension.class)
class MyBrobotTest extends BrobotTestBase {
    
    @BeforeEach
    void setup() {
        // Use utilities for test setup
        if (BrobotTestUtils.isHeadless()) {
            FrameworkSettings.mock = true;
        }
    }
    
    @Test
    void testWithUtilities() {
        State state = BrobotTestUtils.createTestState("TestState");
        ActionResult result = BrobotTestUtils.createSuccessfulResult(1);
        
        // Your test logic
        assertNotNull(state);
        assertTrue(result.isSuccess());
    }
}

Parameterized Tests

@ParameterizedTest
@ValueSource(ints = {1, 3, 5, 10})
void testMultipleMatches(int matchCount) {
    ActionResult result = BrobotTestUtils.createSuccessfulResult(matchCount);
    
    assertEquals(matchCount, result.getMatches().size());
    assertTrue(result.isSuccess());
}

Common Testing Patterns

Mock Data Creation

private ActionResult mockFindAction() {
    return BrobotTestUtils.createSuccessfulResult(1);
}

private List<Match> mockMultipleMatches() {
    return BrobotTestUtils.createTestMatches(5);
}

Test Data Builders

class TestDataBuilder {
    
    public State buildLoginState() {
        State state = BrobotTestUtils.createTestState("Login");
        // Add custom configuration
        return state;
    }
    
    public List<StateImage> buildTestImages() {
        return Arrays.asList(
            BrobotTestUtils.createTestStateImage("button1"),
            BrobotTestUtils.createTestStateImage("button2"),
            BrobotTestUtils.createTestStateImage("button3")
        );
    }
}

Notes

All random generators use reasonable bounds (e.g., 1920x1080 screen)
Factory methods create objects with sensible defaults
Utilities are designed to work in both mock and real modes
Thread-safe for use in parallel test execution

BrobotTestBase - Base Test Class​

What BrobotTestBase Provides:​

Test Utility Classes​

BrobotTestUtils - Common Test Helpers​

MatTestUtils - OpenCV Mat Testing Utilities​

MockModeManager - Centralized Mock Control​

BrobotTestUtils - Test Data Creation​

Overview​

Factory Methods​

Creating Test States​

Creating Test StateImages​

Creating Test Matches​

ActionResult Creation​

Successful Results​

Failed Results​

Location and Region Utilities​

Working with Locations​

Working with Regions​

Environment Detection​

CI/CD Detection​

Headless Environment Detection​

Timing Utilities​

Sleep Functions​

Test Name Generation​

Best Practices​

1. Use Factory Methods for Consistency​

2. Leverage Random Data for Robustness​

3. Use Environment Detection for Conditional Testing​

4. Approximate Comparisons for UI Testing​

Integration with Test Frameworks​

JUnit 5 Integration​

Parameterized Tests​

Common Testing Patterns​

Mock Data Creation​

Test Data Builders​

Notes​

See Also​