Merge pull request #289 from seleniumbase/update-methods

 Add limit argument to methods that return or click multiple elements

help_docs/method_summary.md

@@ -71,11 +71,11 @@ self.is_partial_link_text_visible(partial_link_text)
 
 self.is_text_visible(text, selector="html", by=By.CSS_SELECTOR)
 
-self.find_elements(selector, by=By.CSS_SELECTOR)
+self.find_elements(selector, by=By.CSS_SELECTOR, limit=0)
 
-self.find_visible_elements(selector, by=By.CSS_SELECTOR)
+self.find_visible_elements(selector, by=By.CSS_SELECTOR, limit=0)
 
-self.click_visible_elements(selector, by=By.CSS_SELECTOR)
+self.click_visible_elements(selector, by=By.CSS_SELECTOR, limit=0)
 
 self.is_element_in_an_iframe(selector, by=By.CSS_SELECTOR)
 

seleniumbase/fixtures/base_case.py

@@ -640,53 +640,67 @@ def is_text_visible(self, text, selector="html", by=By.CSS_SELECTOR):
             by = By.LINK_TEXT
         return page_actions.is_text_visible(self.driver, text, selector, by)
 
-    def find_elements(self, selector, by=By.CSS_SELECTOR):
-        """ Returns a list of matching WebElements. """
+    def find_elements(self, selector, by=By.CSS_SELECTOR, limit=0):
+        """ Returns a list of matching WebElements.
+            If "limit" is set and > 0, will only return that many elements. """
         self.wait_for_ready_state_complete()
         if page_utils.is_xpath_selector(selector):
             by = By.XPATH
         if page_utils.is_link_text_selector(selector):
             selector = page_utils.get_link_text_from_selector(selector)
             by = By.LINK_TEXT
-        return self.driver.find_elements(by=by, value=selector)
-
-    def find_visible_elements(self, selector, by=By.CSS_SELECTOR):
-        """ Returns a list of matching WebElements that are visible. """
+        elements = self.driver.find_elements(by=by, value=selector)
+        if limit and limit > 0 and len(elements) > limit:
+            elements = elements[:limit]
+        return elements
+
+    def find_visible_elements(self, selector, by=By.CSS_SELECTOR, limit=0):
+        """ Returns a list of matching WebElements that are visible.
+            If "limit" is set and > 0, will only return that many elements. """
         self.wait_for_ready_state_complete()
         if page_utils.is_xpath_selector(selector):
             by = By.XPATH
         if page_utils.is_link_text_selector(selector):
             selector = page_utils.get_link_text_from_selector(selector)
             by = By.LINK_TEXT
-        return page_actions.find_visible_elements(self.driver, selector, by)
+        v_elems = page_actions.find_visible_elements(self.driver, selector, by)
+        if limit and limit > 0 and len(v_elems) > limit:
+            v_elems = v_elems[:limit]
+        return v_elems
 
-    def click_visible_elements(self, selector, by=By.CSS_SELECTOR):
+    def click_visible_elements(self, selector, by=By.CSS_SELECTOR, limit=0):
         """ Finds all matching page elements and clicks visible ones in order.
             If a click reloads or opens a new page, the clicking will stop.
             Works best for actions such as clicking all checkboxes on a page.
             Example:  self.click_visible_elements('input[type="checkbox"]')
-        """
+            If "limit" is set and > 0, will only click that many elements. """
         elements = self.find_elements(selector, by=by)
         count = 0
+        click_count = 0
         for element in elements:
+            if limit and limit > 0 and click_count >= limit:
+                return
             count += 1
             if count == 1:
                 self.wait_for_ready_state_complete()
                 if self.is_element_visible(selector, by=by):
                     self.click(selector, by=by)
+                    click_count += 1
             else:
                 self.wait_for_ready_state_complete()
                 try:
                     if element.is_displayed():
                         self.__scroll_to_element(element)
                         element.click()
+                        click_count += 1
                 except (StaleElementReferenceException, ENI_Exception):
                     self.wait_for_ready_state_complete()
                     time.sleep(0.05)
                     try:
                         if element.is_displayed():
                             self.__scroll_to_element(element)
                             element.click()
+                            click_count += 1
                     except (StaleElementReferenceException, ENI_Exception):
                         return  # Probably on new page / Elements are all stale
 

setup.py

@@ -17,7 +17,7 @@
 
 setup(
     name='seleniumbase',
-    version='1.21.0',
+    version='1.21.1',
     description='Reliable Browser Automation & Testing Framework',
     long_description=long_description,
     long_description_content_type='text/markdown',