How to Use ActionChains in Selenium for Complex User Actions

Use ActionChains in Selenium to perform complex user interactions like mouse movements, clicks, drag-and-drop, and keyboard actions. Create an ActionChains object with your WebDriver, chain the desired actions, and call .perform() to execute them.

Syntax

The ActionChains class lets you chain multiple user actions together. You start by creating an ActionChains object with your WebDriver instance. Then you add actions like move_to_element(), click(), or send_keys(). Finally, call perform() to run all actions in order.

• ActionChains(driver): Creates the action chain object.
• move_to_element(element): Moves mouse to the element.
• click(element=None): Clicks on the element or current mouse position if no element is given.
• click_and_hold(element=None): Clicks and holds mouse button.
• release(element=None): Releases mouse button.
• send_keys(keys): Sends keyboard keys.
• perform(): Executes all chained actions.

python

from selenium.webdriver import ActionChains

# Create ActionChains object
actions = ActionChains(driver)

# Chain actions
actions.move_to_element(element).click().send_keys('text').perform()

Example

This example shows how to hover over a menu item and then click a submenu item using ActionChains. It demonstrates chaining mouse movements and clicks.

python

from selenium import webdriver
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.by import By

# Setup WebDriver
driver = webdriver.Chrome()
driver.get('https://www.w3schools.com/howto/howto_css_dropdown.asp')

# Locate elements
menu = driver.find_element(By.CSS_SELECTOR, '.dropdown')
submenu = driver.find_element(By.CSS_SELECTOR, '.dropdown-content a')

# Create ActionChains object
actions = ActionChains(driver)

# Hover over menu and click submenu
actions.move_to_element(menu).click(submenu).perform()

# Close browser
driver.quit()

Output

Test runs without errors, submenu item is clicked after hover.

Common Pitfalls

• Not calling perform() after chaining actions means nothing happens.
• Trying to click an element before hovering over it can fail if the element is hidden.
• Using stale or incorrect element locators causes exceptions.
• Not waiting for elements to be visible before actions can cause errors.

Always ensure elements are interactable and call perform() to execute actions.

python

from selenium.webdriver.common.action_chains import ActionChains

# Wrong: Missing perform()
actions = ActionChains(driver)
actions.move_to_element(element).click()

# Correct: Call perform()
actions.perform()

Quick Reference

ActionChains Method	Description
move_to_element(element)	Moves mouse pointer to the specified element
click(element=None)	Clicks on the element or current mouse position if no element given
click_and_hold(element=None)	Clicks and holds mouse button down
release(element=None)	Releases mouse button
double_click(element=None)	Double clicks on element or current mouse position
context_click(element=None)	Right-clicks on element or current mouse position
drag_and_drop(source, target)	Drags source element and drops on target element
send_keys(*keys)	Sends keyboard keys to the active element
perform()	Executes all the actions in the chain

Key Takeaways

Always create an ActionChains object with your WebDriver before chaining actions.

Chain multiple user interactions like mouse moves and clicks, then call perform() to execute.

Ensure elements are visible and interactable before performing actions to avoid errors.

Missing perform() is a common mistake that prevents actions from running.

Use ActionChains for complex interactions like drag-and-drop, hover menus, and keyboard input.