Merge pull request #591 from seleniumbase/driverjs-tours

Add the ability to create DriverJS website tours

Author: mdmintz

docs/prepare.py

@@ -106,7 +106,7 @@ def main(*args, **kwargs):
             changed = True
             line = (
                 '<section align="center"><div align="center">'
-                '<h2>Reliable Browser Testing</h2>'
+                '<h2>✅ Reliable Browser Testing</h2>'
                 '</div></section>')
         if "<!-- SeleniumBase Header2 -->" in line:
             changed = True

examples/tour_examples/ReadMe.md

@@ -2,7 +2,7 @@
 
 ## Website Tours
 
-SeleniumBase Tours utilize 4 JavaScript libraries for creating interactive walkthroughs on any website:<br>**[Shepherd](https://shepherdjs.dev/)**, **[Bootstrap Tour](http://bootstraptour.com/)**, **[IntroJS](https://introjs.com/)**, and **[Hopscotch](https://linkedinattic.github.io/hopscotch/)**.
+SeleniumBase Tours utilize 5 JavaScript libraries for creating interactive walkthroughs on any website:<br>**[Shepherd](https://shepherdjs.dev/)**, **[Bootstrap Tour](http://bootstraptour.com/)**, **[IntroJS](https://introjs.com/)**, **[DriverJS](https://kamranahmed.info/driver.js/)**, and **[Hopscotch](https://linkedinattic.github.io/hopscotch/)**.
 
 **Example tour:**
 
@@ -15,7 +15,7 @@ pytest google_tour.py
 
 ### Creating a new tour:
 
-#### To create a tour utilizing the Shepherd JS Library, use one of the following:
+#### To create a tour utilizing the Shepherd Library, use one of the following:
 
 ``self.create_shepherd_tour()``
 
@@ -33,15 +33,23 @@ OR
 
 ``self.create_tour(theme="bootstrap")``
 
-#### To create a tour utilizing the Intro JS Library, use one of the following:
+#### To create a tour utilizing the IntroJS Library, use one of the following:
 
 ``self.create_introjs_tour()``
 
 OR
 
 ``self.create_tour(theme="introjs")``
 
-#### To create a tour utilizing the Hopscotch JS Library, use one of the following:
+#### To create a tour utilizing the DriverJS Library, use one of the following:
+
+``self.create_driverjs_tour()``
+
+OR
+
+``self.create_tour(theme="driverjs")``
+
+#### To create a tour utilizing the Hopscotch Library, use one of the following:
 
 ``self.create_hopscotch_tour()``
 

examples/tour_examples/driverjs_maps_tour.py

@@ -0,0 +1,36 @@
+from seleniumbase import BaseCase
+
+
+class MyTestClass(BaseCase):
+
+    def test_basic(self):
+        self.open("https://www.google.com/maps/@42.3598616,-71.0912631,15z")
+        self.wait_for_element("#searchboxinput")
+        self.wait_for_element("#minimap")
+        self.wait_for_element("#zoom")
+
+        # Create a website tour using the DriverJS library
+        # Same as:  self.create_driverjs_tour()
+        self.create_tour(theme="driverjs")
+        self.add_tour_step("🗺️ Welcome to Google Maps 🗺️", "html",
+                           title="✅ SeleniumBase Tours 🌎")
+        self.add_tour_step("You can type a location into this Search box.",
+                           "#searchboxinput")
+        self.add_tour_step("Then click here to view it on the map.",
+                           "#searchbox-searchbutton", alignment="bottom")
+        self.add_tour_step("Or click here to get driving directions.",
+                           "#searchbox-directions", alignment="bottom")
+        self.add_tour_step("Use this button to get a Satellite view.",
+                           "#minimap div.widget-minimap", alignment="right")
+        self.add_tour_step("Click here to zoom in.",
+                           "#widget-zoom-in", alignment="left")
+        self.add_tour_step("Or click here to zoom out.",
+                           "#widget-zoom-out", alignment="left")
+        self.add_tour_step("Use the Menu button for more options.",
+                           ".searchbox-hamburger-container", alignment="right")
+        self.add_tour_step("Or click here to see more Google apps.",
+                           '[title="Google apps"]', alignment="left")
+        self.add_tour_step("Thanks for using SeleniumBase Tours", "html",
+                           title="🚃 End of Guided Tour 🚃")
+        self.export_tour()  # The default name for exports is "my_tour.js"
+        self.play_tour(interval=0)  # If interval > 0, autoplay after N seconds

requirements.txt

@@ -2,7 +2,7 @@ pip>=20.1.1
 packaging>=20.4
 setuptools>=44.1.0;python_version<"3.5"
 setuptools>=47.1.1;python_version>="3.5"
-setuptools-scm>=4.1.1
+setuptools-scm>=4.1.2
 wheel>=0.34.2
 six==1.15.0
 nose==1.3.7
@@ -15,7 +15,7 @@ selenium==3.141.0
 pluggy==0.13.1
 attrs>=19.3.0
 pytest==4.6.10;python_version<"3.5"
-pytest==5.4.2;python_version>="3.5"
+pytest==5.4.3;python_version>="3.5"
 pytest-cov==2.9.0
 pytest-forked==1.1.3
 pytest-html==1.22.1;python_version<"3.6"
@@ -41,7 +41,7 @@ coverage==5.1
 pyotp==2.3.0
 boto==2.49.0
 cffi==1.14.0
-rich==1.2.3;python_version>="3.6" and python_version<"4.0"
+rich==1.3.1;python_version>="3.6" and python_version<"4.0"
 flake8==3.7.9;python_version<"3.5"
 flake8==3.8.2;python_version>="3.5"
 pyflakes==2.1.1;python_version<"3.5"

seleniumbase/core/style_sheet.py

@@ -116,6 +116,17 @@
     }
     ''')
 
+# DriverJS Tour Backdrop Style
+dt_backdrop_style = (
+    '''
+    .driver-fix-stacking {
+        pointer-events: none !important;
+    }
+    #driver-popover-item, .popover-class {
+        pointer-events: auto !important;
+    }
+    ''')
+
 messenger_style = (
     '''
     .messenger-message-inner {

seleniumbase/core/tour_helper.py

@@ -56,6 +56,51 @@ def is_bootstrap_activated(driver):
         return False
 
 
+def activate_driverjs(driver):
+    """ Allows you to use DriverJS Tours with SeleniumBase
+        https://kamranahmed.info/driver.js/
+    """
+    backdrop_style = style_sheet.dt_backdrop_style
+    driverjs_css = constants.DriverJS.MIN_CSS
+    driverjs_js = constants.DriverJS.MIN_JS
+
+    verify_script = ("""// Verify DriverJS activated
+                     var driverjs2 = Driver.name;
+                     """)
+
+    activate_bootstrap(driver)
+    js_utils.wait_for_ready_state_complete(driver)
+    js_utils.wait_for_angularjs(driver)
+    js_utils.add_css_style(driver, backdrop_style)
+    for x in range(4):
+        js_utils.activate_jquery(driver)
+        js_utils.add_css_link(driver, driverjs_css)
+        js_utils.add_js_link(driver, driverjs_js)
+        time.sleep(0.1)
+        for x in range(int(settings.MINI_TIMEOUT * 2.0)):
+            # DriverJS needs a small amount of time to load & activate.
+            try:
+                driver.execute_script(verify_script)
+                js_utils.wait_for_ready_state_complete(driver)
+                js_utils.wait_for_angularjs(driver)
+                time.sleep(0.05)
+                return
+            except Exception:
+                time.sleep(0.15)
+    js_utils.raise_unable_to_load_jquery_exception(driver)
+
+
+def is_driverjs_activated(driver):
+    verify_script = ("""// Verify DriverJS activated
+                     var driverjs2 = Driver.name;
+                     """)
+    try:
+        driver.execute_script(verify_script)
+        return True
+    except Exception:
+        return False
+
+
 def activate_hopscotch(driver):
     """ Allows you to use Hopscotch Tours with SeleniumBase
         http://linkedin.github.io/hopscotch/
@@ -399,6 +444,118 @@ def play_bootstrap_tour(
                 time.sleep(0.1)
 
 
+def play_driverjs_tour(
+        driver, tour_steps, browser, msg_dur, name=None, interval=0):
+    """ Plays a DriverJS tour on the current website. """
+    instructions = ""
+    for tour_step in tour_steps[name]:
+        instructions += tour_step
+    instructions += (
+        """]
+        );
+        // Start the tour!
+        tour.start();
+        $tour = tour;""")
+    autoplay = False
+    if interval and interval > 0:
+        autoplay = True
+        interval = float(interval)
+        if interval < 0.5:
+            interval = 0.5
+
+    if not is_driverjs_activated(driver):
+        activate_driverjs(driver)
+
+    if len(tour_steps[name]) > 1:
+        try:
+            if "element: " in tour_steps[name][1]:
+                selector = re.search(
+                    r"[\S\s]+element: '([\S\s]+)',[\S\s]+popover: {",
+                    tour_steps[name][1]).group(1)
+                selector = selector.replace('\\', '').replace(':first', '')
+                page_actions.wait_for_element_present(
+                    driver, selector, by=By.CSS_SELECTOR,
+                    timeout=settings.SMALL_TIMEOUT)
+            else:
+                selector = "html"
+        except Exception:
+            js_utils.post_messenger_error_message(
+                driver, "Tour Error: {'%s'} was not found!" % selector,
+                msg_dur)
+            raise Exception(
+                "Tour Error: {'%s'} was not found! "
+                "Exiting due to failure on first tour step!"
+                "" % selector)
+
+    driver.execute_script(instructions)
+    driver.execute_script(
+        'document.querySelector(".driver-next-btn").focus();')
+    tour_on = True
+    if autoplay:
+        start_ms = time.time() * 1000.0
+        stop_ms = start_ms + (interval * 1000.0)
+        latest_step = 0
+    while tour_on:
+        try:
+            time.sleep(0.01)
+            if browser != "firefox":
+                result = not driver.execute_script(
+                    "return $tour.isActivated")
+            else:
+                page_actions.wait_for_element_present(
+                    driver, "#driver-popover-item",
+                    by=By.CSS_SELECTOR, timeout=0.4)
+                result = False
+        except Exception:
+            tour_on = False
+            result = None
+        if result is False:
+            tour_on = True
+            driver.execute_script(
+                'document.querySelector(".driver-next-btn").focus();')
+            if autoplay:
+                try:
+                    current_step = driver.execute_script(
+                        "return $tour.currentStep")
+                except Exception:
+                    continue
+                if current_step != latest_step:
+                    latest_step = current_step
+                    start_ms = time.time() * 1000.0
+                    stop_ms = start_ms + (interval * 1000.0)
+                now_ms = time.time() * 1000.0
+                if now_ms >= stop_ms:
+                    if current_step == latest_step:
+                        driver.execute_script("$tour.moveNext()")
+                        try:
+                            latest_step = driver.execute_script(
+                                "return $tour.currentStep")
+                            start_ms = time.time() * 1000.0
+                            stop_ms = start_ms + (interval * 1000.0)
+                        except Exception:
+                            pass
+                        continue
+        else:
+            try:
+                time.sleep(0.01)
+                if browser != "firefox":
+                    result = not driver.execute_script(
+                        "return $tour.isActivated")
+                else:
+                    page_actions.wait_for_element_present(
+                        driver, "#driver-popover-item",
+                        by=By.CSS_SELECTOR, timeout=0.4)
+                    result = False
+                if result is False:
+                    time.sleep(0.1)
+                    continue
+                else:
+                    return
+            except Exception:
+                tour_on = False
+                time.sleep(0.1)
+
+
 def play_hopscotch_tour(
         driver, tour_steps, browser, msg_dur, name=None, interval=0):
     """ Plays a Hopscotch tour on the current website. """
@@ -645,6 +802,8 @@ def export_tour(tour_steps, name=None, filename="my_tour.js", url=None):
     tour_type = None
     if "Bootstrap" in tour_steps[name][0]:
         tour_type = "bootstrap"
+    elif "DriverJS" in tour_steps[name][0]:
+        tour_type = "driverjs"
     elif "Hopscotch" in tour_steps[name][0]:
         tour_type = "hopscotch"
     elif "IntroJS" in tour_steps[name][0]:
@@ -705,6 +864,16 @@ def export_tour(tour_steps, name=None, filename="my_tour.js", url=None):
         instructions += '} }\n'
         instructions += 'loadResources()'
 
+    elif tour_type == "driverjs":
+        driverjs_css = constants.DriverJS.MIN_CSS
+        driverjs_js = constants.DriverJS.MIN_JS
+        backdrop_style = style_sheet.dt_backdrop_style
+        backdrop_style = backdrop_style.replace('\n', '')
+        backdrop_style = js_utils.escape_quotes_if_needed(backdrop_style)
+        instructions += 'injectCSS("%s");\n' % driverjs_css
+        instructions += 'injectStyle("%s");\n' % backdrop_style
+        instructions += 'injectJS("%s");' % driverjs_js
+
     elif tour_type == "hopscotch":
         hopscotch_css = constants.Hopscotch.MIN_CSS
         hopscotch_js = constants.Hopscotch.MIN_JS
@@ -757,6 +926,9 @@ def export_tour(tour_steps, name=None, filename="my_tour.js", url=None):
     if tour_type == "bootstrap":
         instructions += 'function loadTour() { '
         instructions += 'if ( typeof Tour !== "undefined" ) {\n'
+    elif tour_type == "driverjs":
+        instructions += 'function loadTour() { '
+        instructions += 'if ( typeof Driver !== "undefined" ) {\n'
     elif tour_type == "hopscotch":
         instructions += 'function loadTour() { '
         instructions += 'if ( typeof hopscotch !== "undefined" ) {\n'
@@ -779,6 +951,13 @@ def export_tour(tour_steps, name=None, filename="my_tour.js", url=None):
             tour.start();
             $tour = tour;
             $tour.restart();\n""")
+    elif tour_type == "driverjs":
+        instructions += (
+            """]
+            );
+            // Start the tour!
+            tour.start();
+            $tour = tour;\n""")
     elif tour_type == "hopscotch":
         instructions += (
             """]