What are the available methods for mouse and keyboard interactions in Symfony Panther?

Symfony Panther provides a comprehensive set of methods for simulating mouse and keyboard interactions when automating web browsers. Built on top of Chrome DevTools and WebDriver protocols, Panther enables developers to create sophisticated web scraping and testing scenarios that require user interaction simulation.

Mouse Interaction Methods

Basic Click Operations

Symfony Panther offers several methods for performing click operations on web elements:

<?php
use Symfony\Component\Panther\Client;

$client = Client::createChromeClient();
$crawler = $client->request('GET', 'https://example.com');

// Simple left click
$button = $crawler->filter('button#submit');
$button->click();

// Click with specific coordinates
$client->getMouse()->click(100, 200);

// Right click (context menu)
$element = $crawler->filter('.context-menu-trigger');
$client->getMouse()->rightClick($element->getElement(0));

// Double click
$client->getMouse()->doubleClick($element->getElement(0));

Advanced Mouse Operations

For more complex interactions, Panther provides methods for hover effects, drag-and-drop, and precise mouse movements:

// Hover over an element
$menuItem = $crawler->filter('.dropdown-trigger');
$client->getMouse()->mouseMoveTo($menuItem->getElement(0));

// Drag and drop operation
$source = $crawler->filter('#draggable-item');
$target = $crawler->filter('#drop-zone');

$client->getMouse()
    ->mouseDownOn($source->getElement(0))
    ->mouseMoveTo($target->getElement(0))
    ->mouseUp();

// Mouse move with offset
$element = $crawler->filter('.interactive-area');
$client->getMouse()->mouseMoveTo($element->getElement(0), 10, 20);

// Scroll using mouse wheel
$client->getMouse()->scrollTo(0, 500);

Mouse Button States

You can control individual mouse button states for complex interactions:

// Mouse down (press and hold)
$element = $crawler->filter('.pressable-button');
$client->getMouse()->mouseDownOn($element->getElement(0));

// Perform other actions while mouse is held down
sleep(2);

// Mouse up (release)
$client->getMouse()->mouseUp();

// Check if element is being hovered
$isHovered = $client->executeScript('
    return document.querySelector(".my-element"):hover !== null;
');

Keyboard Interaction Methods

Text Input and Form Filling

Symfony Panther provides multiple approaches for entering text and interacting with form elements:

// Basic text input
$inputField = $crawler->filter('input[name="username"]');
$inputField->sendKeys('john.doe@example.com');

// Clear existing text before typing
$inputField->clear();
$inputField->sendKeys('new.email@example.com');

// Type with delay between characters
$client->getKeyboard()->typeText('slow typing', 100); // 100ms delay

// Fill multiple form fields
$form = $crawler->selectButton('Submit')->form([
    'username' => 'testuser',
    'password' => 'secretpassword',
    'email' => 'test@example.com'
]);
$client->submit($form);

Special Keys and Key Combinations

Handle special keys, function keys, and keyboard shortcuts:

use Facebook\WebDriver\WebDriverKeys;

// Press Enter key
$client->getKeyboard()->pressKey(WebDriverKeys::ENTER);

// Press Tab to navigate between fields
$client->getKeyboard()->pressKey(WebDriverKeys::TAB);

// Press Escape key
$client->getKeyboard()->pressKey(WebDriverKeys::ESCAPE);

// Arrow keys for navigation
$client->getKeyboard()->pressKey(WebDriverKeys::ARROW_DOWN);
$client->getKeyboard()->pressKey(WebDriverKeys::ARROW_UP);

// Function keys
$client->getKeyboard()->pressKey(WebDriverKeys::F5); // Refresh page

// Modifier keys
$client->getKeyboard()->pressKey(WebDriverKeys::SHIFT);
$client->getKeyboard()->pressKey(WebDriverKeys::CONTROL);
$client->getKeyboard()->pressKey(WebDriverKeys::ALT);

Keyboard Shortcuts and Key Combinations

Simulate complex keyboard shortcuts commonly used in web applications:

// Ctrl+A (Select All)
$client->getKeyboard()->sendKeys(WebDriverKeys::CONTROL . 'a');

// Ctrl+C (Copy)
$client->getKeyboard()->sendKeys(WebDriverKeys::CONTROL . 'c');

// Ctrl+V (Paste)
$client->getKeyboard()->sendKeys(WebDriverKeys::CONTROL . 'v');

// Ctrl+Z (Undo)
$client->getKeyboard()->sendKeys(WebDriverKeys::CONTROL . 'z');

// Alt+Tab (Switch applications)
$client->getKeyboard()->sendKeys(WebDriverKeys::ALT . WebDriverKeys::TAB);

// Shift+Click for multiple selections
$client->getKeyboard()->keyDown(WebDriverKeys::SHIFT);
$element->click();
$client->getKeyboard()->keyUp(WebDriverKeys::SHIFT);

Advanced Interaction Patterns

Combining Mouse and Keyboard Actions

Create sophisticated interaction sequences by combining mouse and keyboard operations:

// Select text with mouse and replace with keyboard
$textElement = $crawler->filter('.editable-text');

// Triple-click to select all text in element
$client->getMouse()->tripleClick($textElement->getElement(0));

// Type replacement text
$client->getKeyboard()->typeText('New content here');

// Drag to select specific text range
$client->getMouse()
    ->mouseMoveTo($textElement->getElement(0), 10, 5)
    ->mouseDown()
    ->mouseMoveTo($textElement->getElement(0), 100, 5)
    ->mouseUp();

Handling Dynamic Elements

Work with elements that appear or change based on user interactions, similar to handling dynamic content in other browser automation tools:

// Wait for element to become clickable after hover
$menuTrigger = $crawler->filter('.menu-trigger');
$client->getMouse()->mouseMoveTo($menuTrigger->getElement(0));

// Wait for dropdown to appear
$client->waitFor('.dropdown-menu');

// Click on dynamically loaded menu item
$menuItem = $crawler->filter('.dropdown-menu .item-1');
$menuItem->click();

// Handle elements that require focus before interaction
$inputField = $crawler->filter('input[type="search"]');
$inputField->click(); // Focus the element
$client->waitFor('.search-suggestions'); // Wait for suggestions to load
$inputField->sendKeys('search query');

Form Interaction Patterns

Implement common form interaction patterns:

// File upload simulation
$fileInput = $crawler->filter('input[type="file"]');
$fileInput->attachFile('/path/to/local/file.pdf');

// Checkbox and radio button interactions
$checkbox = $crawler->filter('input[type="checkbox"]');
if (!$checkbox->isSelected()) {
    $checkbox->click();
}

$radioButton = $crawler->filter('input[value="option2"]');
$radioButton->click();

// Dropdown/select element handling
$selectElement = $crawler->filter('select[name="country"]');
$selectElement->selectOption('United States');

// Multi-select handling
$multiSelect = $crawler->filter('select[multiple]');
$client->getKeyboard()->keyDown(WebDriverKeys::CONTROL);
$multiSelect->selectOption('Option 1');
$multiSelect->selectOption('Option 2');
$client->getKeyboard()->keyUp(WebDriverKeys::CONTROL);

Error Handling and Best Practices

Robust Interaction Handling

Implement proper error handling and wait strategies for reliable interactions:

try {
    // Wait for element to be clickable
    $client->waitFor('.interactive-button', 10);

    $button = $crawler->filter('.interactive-button');

    // Ensure element is visible and enabled
    if ($button->isDisplayed() && $button->isEnabled()) {
        $button->click();
    } else {
        throw new \Exception('Element not ready for interaction');
    }

    // Wait for action to complete
    $client->waitFor('.success-message');

} catch (\Exception $e) {
    // Log error and handle gracefully
    error_log('Interaction failed: ' . $e->getMessage());

    // Take screenshot for debugging
    $client->takeScreenshot('interaction_error.png');
}

Performance Optimization

Optimize interaction performance for large-scale automation:

// Use implicit waits for better performance
$client->manage()->timeouts()->implicitlyWait(5);

// Disable images and CSS for faster loading (if visual accuracy not needed)
$options = [
    '--disable-images',
    '--disable-css',
    '--disable-javascript' // Only if JS interactions not needed
];

$client = Client::createChromeClient(null, null, $options);

// Batch similar operations
$elements = $crawler->filter('.clickable-items');
foreach ($elements as $element) {
    $client->getMouse()->click($element);
    usleep(100000); // Small delay to prevent overwhelming the page
}

Integration with Testing Frameworks

PHPUnit Integration

Integrate mouse and keyboard interactions in your test suites:

use PHPUnit\Framework\TestCase;
use Symfony\Component\Panther\PantherTestCase;

class InteractionTest extends PantherTestCase
{
    public function testComplexUserFlow(): void
    {
        $client = static::createPantherClient();
        $crawler = $client->request('GET', '/login');

        // Login flow with keyboard interactions
        $crawler->filter('#username')->sendKeys('testuser');
        $client->getKeyboard()->pressKey(WebDriverKeys::TAB);
        $crawler->filter('#password')->sendKeys('password123');
        $crawler->filter('#login-btn')->click();

        // Verify successful login
        $this->assertSelectorExists('.dashboard');

        // Test mouse interactions on dashboard
        $menuItem = $crawler->filter('.nav-menu .reports');
        $client->getMouse()->mouseMoveTo($menuItem->getElement(0));

        $this->assertSelectorExists('.dropdown-submenu');
    }
}

JavaScript Integration

Executing Custom JavaScript

Combine JavaScript execution with mouse and keyboard interactions for advanced automation:

// Execute JavaScript to prepare the page
$client->executeScript('
    window.myCustomVariable = "test";
    document.getElementById("hidden-element").style.display = "block";
');

// Interact with elements modified by JavaScript
$element = $crawler->filter('#hidden-element');
$element->click();

// Get return values from JavaScript
$result = $client->executeScript('return window.innerWidth;');
echo "Browser width: " . $result;

// Trigger JavaScript events
$client->executeScript('
    var event = new MouseEvent("mouseover", {
        view: window,
        bubbles: true,
        cancelable: true
    });
    document.getElementById("target").dispatchEvent(event);
');

Synchronizing with AJAX Requests

Handle asynchronous operations that depend on user interactions:

// Click button that triggers AJAX request
$submitButton = $crawler->filter('#ajax-submit');
$submitButton->click();

// Wait for AJAX to complete using JavaScript
$client->waitFor(function() use ($client) {
    return $client->executeScript('return jQuery.active === 0;');
}, 10); // 10 second timeout

// Or wait for specific element to appear
$client->waitFor('.ajax-success-message');

// Handle loading states
$loadingSpinner = $crawler->filter('.loading-spinner');
if ($loadingSpinner->count() > 0) {
    // Wait for loading to finish
    $client->waitForInvisibility('.loading-spinner');
}

Mobile and Touch Interactions

Simulating Touch Events

Symfony Panther can simulate mobile touch interactions for responsive testing:

// Set mobile viewport
$client = Client::createChromeClient(null, null, [
    '--window-size=375,667', // iPhone dimensions
    '--user-agent=Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)'
]);

// Touch interactions
$element = $crawler->filter('.touch-target');

// Single tap
$client->getTouchScreen()->singleTap($element->getElement(0));

// Double tap
$client->getTouchScreen()->doubleTap($element->getElement(0));

// Long press
$client->getTouchScreen()->longPress($element->getElement(0));

// Swipe gestures
$startElement = $crawler->filter('.swipe-start');
$endElement = $crawler->filter('.swipe-end');
$client->getTouchScreen()->flick($startElement->getElement(0), 0, -100, 500);

For more complex browser automation scenarios, you might also want to explore handling authentication flows and managing browser sessions to create comprehensive testing and scraping solutions.

Conclusion

Symfony Panther provides a rich set of mouse and keyboard interaction methods that enable developers to create sophisticated web automation scripts. From basic clicks and text input to complex drag-and-drop operations and keyboard shortcuts, these tools allow you to simulate virtually any user interaction pattern.

The framework's integration with WebDriver protocols ensures compatibility across different browsers while maintaining the familiar Symfony ecosystem conventions. By combining these methods with proper error handling, performance optimization techniques, and JavaScript integration, you can build robust and reliable web scraping and testing solutions.

Remember to always implement appropriate waits and error handling to ensure your automation scripts work reliably across different environments and network conditions. The key to successful web automation lies in understanding both the technical capabilities of the tools and the user experience patterns you're trying to replicate.