Cursor rule

1---
2description: Page Object Model patterns for Selenium — BasePage, component objects, and fluent interfaces
3globs: **/pages/**/*.py,**/page_objects/**/*.py
4alwaysApply: false
5---
6# Page Object Model Excellence
7 
8## Advanced POM Architecture
9- **Inheritance Hierarchy**: BasePage class with common functionality
10- **Component Pattern**: Reusable UI components across pages
11- **Fluent Interface**: Method chaining for readable test code
12- **Smart Locators**: Dynamic locator strategies with fallbacks
13 
14## Base Page Implementation
15```python
16from typing import Optional, List, Union, Tuple
17from selenium.webdriver.remote.webelement import WebElement
18from selenium.webdriver.support.ui import WebDriverWait
19from selenium.webdriver.support import expected_conditions as EC
20from selenium.webdriver.common.by import By
21from selenium.webdriver.common.action_chains import ActionChains
22from selenium.common.exceptions import TimeoutException, StaleElementReferenceException
23import logging
24 
25logger = logging.getLogger(__name__)
26 
27class BasePage:
28    """Enhanced base page with advanced interaction methods."""
29    
30    def __init__(self, driver, timeout: int = 10):
31        self.driver = driver
32        self.wait = WebDriverWait(driver, timeout)
33        self.timeout = timeout
34        self.actions = ActionChains(driver)
35    
36    def find_element_safely(self, locator: Tuple[str, str], timeout: Optional[int] = None) -> Optional[WebElement]:
37        """Find element with comprehensive error handling and retry logic."""
38        timeout = timeout or self.timeout
39        wait = WebDriverWait(self.driver, timeout)
40        
41        try:
42            element = wait.until(EC.presence_of_element_located(locator))
43            logger.debug(f"Element found successfully: {locator}")
44            return element
45        except TimeoutException:
46            logger.warning(f"Element not found within {timeout}s: {locator}")
47            return None
48        except StaleElementReferenceException:
49            logger.warning(f"Stale element detected, retrying: {locator}")
50            return self.find_element_safely(locator, timeout)
51    
52    def click_when_clickable(self, locator: Tuple[str, str], timeout: Optional[int] = None) -> bool:
53        """Click element only when it's clickable with retry logic."""
54        timeout = timeout or self.timeout
55        wait = WebDriverWait(self.driver, timeout)
56        
57        try:
58            element = wait.until(EC.element_to_be_clickable(locator))
59            
60            # Scroll element into view before clicking
61            self.driver.execute_script("arguments[0].scrollIntoView(true);", element)
62            
63            # Use Actions for more reliable clicking
64            self.actions.move_to_element(element).click().perform()
65            logger.info(f"Successfully clicked element: {locator}")
66            return True
67        except TimeoutException:
68            logger.error(f"Element not clickable: {locator}")
69            return False
70        except Exception as e:
71            logger.error(f"Click failed for {locator}: {str(e)}")
72            return False
73    
74    def enter_text_safely(self, locator: Tuple[str, str], text: str, 
75                         clear_first: bool = True, validate: bool = True) -> bool:
76        """Enter text with validation and error handling."""
77        element = self.find_element_safely(locator)
78        if not element:
79            return False
80        
81        try:
82            # Scroll to element and focus
83            self.driver.execute_script("arguments[0].scrollIntoView(true);", element)
84            element.click()  # Focus the element
85            
86            if clear_first:
87                element.clear()
88            
89            element.send_keys(text)
90            
91            # Verify text was entered correctly if validation is enabled
92            if validate:
93                entered_value = element.get_attribute('value')
94                if entered_value == text:
95                    logger.info(f"Text entered successfully: '{text}' in {locator}")
96                    return True
97                else:
98                    logger.warning(f"Text entry verification failed. Expected: '{text}', Got: '{entered_value}'")
99                    return False
100            
101            logger.info(f"Text entered (no validation): '{text}' in {locator}")
102            return True
103                
104        except Exception as e:
105            logger.error(f"Failed to enter text in {locator}: {str(e)}")
106            return False
107```
108 
109## Example Page Implementation
110```python
111class LoginPage(BasePage):
112    """Login page with comprehensive functionality."""
113    
114    def __init__(self, driver):
115        super().__init__(driver)
116        self.url = "/login"
117        
118        # Locators
119        self.email_input = (By.ID, "email")
120        self.password_input = (By.ID, "password")
121        self.login_button = (By.CSS_SELECTOR, "[data-cy=login-button]")
122        self.error_message = (By.CSS_SELECTOR, "[data-cy=error-message]")
123        self.forgot_password_link = (By.CSS_SELECTOR, "[data-cy=forgot-password]")
124        self.remember_me_checkbox = (By.CSS_SELECTOR, "[data-cy=remember-me]")
125    
126    def navigate(self) -> 'LoginPage':
127        """Navigate to login page with fluent interface."""
128        self.driver.get(self.url)
129        self.wait_for_page_load()
130        return self
131    
132    def wait_for_page_load(self) -> bool:
133        """Wait for login page to be fully loaded."""
134        return (self.wait_for_element_visible(self.email_input) and
135                self.wait_for_element_visible(self.password_input))
136    
137    def enter_email(self, email: str) -> 'LoginPage':
138        """Enter email with fluent interface."""
139        self.enter_text_safely(self.email_input, email)
140        return self
141    
142    def enter_password(self, password: str) -> 'LoginPage':
143        """Enter password with fluent interface."""
144        self.enter_text_safely(self.password_input, password)
145        return self
146    
147    def check_remember_me(self) -> 'LoginPage':
148        """Check remember me checkbox."""
149        self.click_when_clickable(self.remember_me_checkbox)
150        return self
151    
152    def click_login(self) -> Union['DashboardPage', 'LoginPage']:
153        """Click login button and return appropriate page object."""
154        if self.click_when_clickable(self.login_button):
155            # Wait for navigation or error
156            if self.wait_for_element_invisible(self.login_button, timeout=5):
157                from pages.dashboard_page import DashboardPage
158                return DashboardPage(self.driver)
159            elif self.is_element_present(self.error_message):
160                return self  # Stay on login page if error
161        return self
162    
163    def login(self, email: str, password: str, remember_me: bool = False) -> Union['DashboardPage', 'LoginPage']:
164        """Complete login flow with method chaining."""
165        login_chain = self.enter_email(email).enter_password(password)
166        
167        if remember_me:
168            login_chain = login_chain.check_remember_me()
169        
170        return login_chain.click_login()
171```
172 
173## Component-Based Architecture
174```python
175class BaseComponent:
176    """Base class for reusable UI components."""
177    
178    def __init__(self, driver, root_locator: Tuple[str, str]):
179        self.driver = driver
180        self.root_locator = root_locator
181        self.base_page = BasePage(driver)
182    
183    def is_displayed(self) -> bool:
184        """Check if component is displayed."""
185        return self.base_page.wait_for_element_visible(self.root_locator, timeout=5)
186    
187    def wait_for_component(self, timeout: int = 10) -> bool:
188        """Wait for component to be visible."""
189        return self.base_page.wait_for_element_visible(self.root_locator, timeout)
190 
191class NavigationComponent(BaseComponent):
192    """Reusable navigation component."""
193    
194    def __init__(self, driver):
195        super().__init__(driver, (By.CSS_SELECTOR, "[data-cy=main-navigation]"))
196        self.menu_items = (By.CSS_SELECTOR, "[data-cy=nav-item]")
197        self.user_menu = (By.CSS_SELECTOR, "[data-cy=user-menu]")
198        self.logout_button = (By.CSS_SELECTOR, "[data-cy=logout]")
199    
200    def navigate_to(self, menu_name: str) -> bool:
201        """Navigate to specific menu item."""
202        if not self.is_displayed():
203            logger.error("Navigation component not displayed")
204            return False
205        
206        menu_locator = (By.CSS_SELECTOR, f"[data-cy=nav-{menu_name.lower()}]")
207        return self.base_page.click_when_clickable(menu_locator)
208    
209    def logout(self) -> bool:
210        """Perform logout action."""
211        if self.base_page.click_when_clickable(self.user_menu):
212            return self.base_page.click_when_clickable(self.logout_button)
213        return False
214```
215