Merge pull request #213 from seleniumbase/tours-overhaul

Add ability to create SeleniumBase website tours using IntroJS

Author: mdmintz

.travis.yml

@@ -19,7 +19,7 @@ install:
   - "python setup.py develop"
   - "sudo rm -f /etc/boto.cfg"
 before_script:
-  - "flake8 seleniumbase/*.py && flake8 seleniumbase/*/*.py && flake8 seleniumbase/*/*/*.py && flake8 seleniumbase/*/*/*/*.py"
+  - "flake8 --ignore FutureWarning seleniumbase/*.py && flake8 --ignore FutureWarning seleniumbase/*/*.py && flake8 --ignore FutureWarning seleniumbase/*/*/*.py && flake8 --ignore FutureWarning seleniumbase/*/*/*/*.py"
   # - "wget https://chromedriver.storage.googleapis.com/2.40/chromedriver_linux64.zip && unzip chromedriver_linux64.zip && sudo cp chromedriver /usr/local/bin/ && sudo chmod +x /usr/local/bin/chromedriver"
   # - "wget https://github.com/mozilla/geckodriver/releases/download/v0.21.0/geckodriver-v0.21.0-linux64.tar.gz -O /tmp/geckodriver.tar.gz && tar -C /opt -xzf /tmp/geckodriver.tar.gz && sudo chmod 755 /opt/geckodriver && sudo ln -fs /opt/geckodriver /usr/bin/geckodriver && sudo ln -fs /opt/geckodriver /usr/local/bin/geckodriver"
   # - "wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-2.1.1-linux-x86_64.tar.bz2 && tar -xvf ./phantomjs-2.1.1-linux-x86_64.tar.bz2 && export PATH=$PWD/phantomjs-2.1.1-linux-x86_64/bin:$PATH"

README.md

@@ -48,7 +48,7 @@ Try out Demo Mode to see what what's being tested in real time! (Chrome is the d
 pytest my_first_test.py --demo_mode
 ```
 
-![](https://cdn2.hubspot.net/hubfs/100006/images/sb_demo.gif "SeleniumBase")<br />
+<img src="https://cdn2.hubspot.net/hubfs/100006/sb_demo_mode.gif" title="SeleniumBase" height="270"><br>
 (Above: Actual demo of [my_first_test.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/my_first_test.py) running on [xkcd.com](http://xkcd.com/353/))
 
 There are many more examples to try out from the [SeleniumBase/examples](https://github.com/seleniumbase/SeleniumBase/blob/master/examples) directory, which you can run easily if you clone SeleniumBase.
@@ -60,7 +60,7 @@ cd tour_examples
 pytest google_tour.py
 ```
 
-<img src="https://cdn2.hubspot.net/hubfs/100006/images/google_tour.gif" title="SeleniumBase Tours" height="348"><br>
+<img src="https://cdn2.hubspot.net/hubfs/100006/google_tour_3.gif" title="SeleniumBase Tour of Google" height="260"><br>
 (Above: Actual demo of [google_tour.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/tour_examples/google_tour.py) running on [google.com](https://google.com))
 
 For more detailed steps on getting started, see the [**Detailed Instructions**](#seleniumbase_installation) section.

examples/tour_examples/ReadMe.md

@@ -1,40 +1,58 @@
-## Creating SeleniumBase Tours
+## SeleniumBase Website Tours
 
-SeleniumBase Tours utilize the **[Shepherd Javascript Library](https://cdnjs.com/libraries/shepherd/1.8.1)** and the **[Bootstrap Tour Library](https://cdnjs.com/libraries/bootstrap-tour)** for creating and running tours, demos, and walkthroughs on any website.
+SeleniumBase Tours utilize the following three Javascript libraries for creating and running tours, demos, and walkthroughs on any website: **[Shepherd JS](https://cdnjs.com/libraries/shepherd/1.8.1)**, **[Bootstrap Tour JS](https://cdnjs.com/libraries/bootstrap-tour)**, and **[Intro JS](https://cdnjs.com/libraries/intro.js)**.
 
-Example tour utilizing the Shepherd Javascript Library:
+Example tour:
 
-<img src="https://cdn2.hubspot.net/hubfs/100006/images/google_tour.gif" title="Shepherd Tour" height="348"><br>
+<img src="https://cdn2.hubspot.net/hubfs/100006/google_tour_3.gif" title="SeleniumBase Tour of Google" height="260"><br>
 
-Example tour utilizing the Bootstrap Javascript Library:
 
-<img src="https://cdn2.hubspot.net/hubfs/100006/images/google_tour_2b.gif" title="Bootstrap Tour" height="340"><br>
+### Creating a new tour:
 
-By default, the Shepherd Javascript Library is used when creating a tour with:
+By default, Shepherd JS is used when creating a tour with:
 
 ``self.create_tour()``
 
-To create a tour utilizing the Bootstrap Javascript Library, you can use either of the following:
+You can also do:
+
+``self.create_shepherd_tour()``
+
+With the ``create_tour()`` and ``create_shepherd_tour()`` methods, you can pass a default theme to change the look & feel of the tour steps. Valid themes for Shepherd Tours are ``dark``, ``light`` / ``arrows``, ``default``, ``square``, and ``square-dark``.
+
+To create a tour utilizing the Bootstrap Tour Library, you can use either of the following:
 
 ``self.create_bootstrap_tour()``
 
 OR
 
 ``self.create_tour(theme="bootstrap")``
 
+To create a tour utilizing the Intro JS Library, you can use either of the following:
+
+``self.create_introjs_tour()``
+
+OR
+
+``self.create_tour(theme="introjs")``
+
+
+### Adding a step to a tour:
+
 To add a tour step, use the following: (Only ``message`` is required. The other args are optional.)
 
 ``self.add_tour_step(message, css_selector, title, alignment, theme)``
 
-Here's how you play a tour:
+With the ``self.add_tour_step()`` method, you must first pass a message to display. You can then specify a web element to attach to (by using [CSS selectors](https://www.w3schools.com/cssref/css_selectors.asp)). If no element is specified, the tour step will tether to the top of the screen by default. You can also add an optional title above the message to display with the tour step, as well as change the theme for that step (Shepherd tours only), and even specify the alignment (which is the side of the element that you want the tour message to tether to).
 
-``self.play_tour(interval)``
 
-With the ``create_tour()`` method, you can pass a default theme to change the look & feel of the tour steps. Valid themes for Shepherd Tours are ``dark``, ``light`` / ``arrows``, ``default``, ``square``, and ``square-dark``.
+### Playing a tour:
+
+You can play a tour by calling:
+
+``self.play_tour(interval)``
 
-With the ``self.add_tour_step()`` method, you must first pass a message to display. You can then specify a web element to attach to (by using [CSS selectors](https://www.w3schools.com/cssref/css_selectors.asp)). If no element is specified, the tour step will tether to the top of the screen by default. You can also add an optional title above the message to display with the tour step, as well as change the theme for that step, and even specify the alignment (which is the side of the element that you want the tour message to tether to).
+ If you specify an interval (optional), the tour will automatically walk through each step after that many seconds have passed.
 
-Finally, you can play a tour you created by calling the ``self.play_tour()`` method. If you specify an interval, the tour will automatically walk through each step after that many seconds have passed.
 
 All methods have the optional ``name`` argument, which is only needed if you're creating multiple tours at once. Then, when you're adding a step or playing a tour, SeleniumBase knows which tour you're referring too. You can avoid using the ``name`` arg for multiple tours if you play a tour before creating a new one.
 
@@ -63,7 +81,7 @@ class MyTourClass(BaseCase):
         self.add_tour_step(
             "Then click here to search.", 'input[value="Google Search"]')
         self.add_tour_step(
-            "Or press [ENTER] after typing.", '[title="Search"]', theme="dark")
+            "Or press [ENTER] after typing a query here.", '[title="Search"]')
         self.play_tour()
 ```
 
@@ -72,9 +90,3 @@ class MyTourClass(BaseCase):
 ```bash
 pytest google_tour.py
 ```
-
-#### There's also the Bootstrap Google Tour, which you can play with the following command:
-
-```bash
-pytest bootstrap_google_tour.py
-```

examples/tour_examples/bootstrap_google_tour.py

@@ -12,18 +12,26 @@ def test_google_tour(self):
             "Click to begin the Google Tour!", title="SeleniumBase Tours")
         self.add_tour_step(
             "Type in your search query here.", 'input[title="Search"]')
-        self.add_tour_step('Then click "Google Search" or press [ENTER].')
         self.play_tour()
 
-        self.highlight_update_text('input[title="Search"]', "GitHub")
+        self.highlight_update_text('input[title="Search"]', "Google")
         self.wait_for_element('[role="listbox"]')  # Wait for autocomplete
-        self.highlight_click('input[value="Google Search"]')
+
+        self.create_bootstrap_tour()
+        self.add_tour_step(
+            "Then click here to search.", 'input[value="Google Search"]')
+        self.add_tour_step(
+            "Or press [ENTER] after typing a query here.", '[title="Search"]')
+        self.play_tour()
+
+        self.highlight_update_text('input[title="Search"]', "GitHub\n")
+        self.wait_for_element("#search")
 
         self.create_bootstrap_tour()
         self.add_tour_step(
             "Search results appear here!", title="(5-second autoplay on)")
         self.add_tour_step("Let's take another tour:")
-        self.play_tour(interval=5)  # tour automatically continues after 5 sec
+        self.play_tour(interval=5)  # Tour automatically continues after 5 sec
 
         self.open("https://www.google.com/maps/@42.3598616,-71.0912631,15z")
         self.wait_for_element('input#searchboxinput')

examples/tour_examples/google_tour.py

@@ -7,6 +7,8 @@ def test_google_tour(self):
         self.open('https://google.com')
         self.wait_for_element('input[title="Search"]')
 
+        # Create a website tour using the ShepherdJS library with "dark" theme
+        # Same as:  self.create_shepherd_tour(theme="dark")
         self.create_tour(theme="dark")
         self.add_tour_step(
             "Click to begin the Google Tour!", title="SeleniumBase Tours")
@@ -17,25 +19,32 @@ def test_google_tour(self):
         self.highlight_update_text('input[title="Search"]', "Google")
         self.wait_for_element('[role="listbox"]')  # Wait for autocomplete
 
+        # Create a website tour using the ShepherdJS library with "light" theme
+        # Same as:  self.create_shepherd_tour(theme="light")
         self.create_tour(theme="light")
         self.add_tour_step(
             "Then click here to search.", 'input[value="Google Search"]')
         self.add_tour_step(
-            "Or press [ENTER] after typing.", '[title="Search"]', theme="dark")
+            "Or press [ENTER] after typing a query here.", '[title="Search"]')
         self.play_tour()
 
         self.highlight_update_text('input[title="Search"]', "GitHub\n")
+        self.wait_for_element("#search")
 
-        self.create_tour(theme="dark")
+        # Create a website tour using the Bootstrap Tour JS library
+        # Same as:  self.create_bootstrap_tour()
+        self.create_tour(theme="bootstrap")
         self.add_tour_step(
             "Search results appear here!", title="(5-second autoplay on)")
         self.add_tour_step("Let's take another tour:", theme="light")
-        self.play_tour(interval=5)  # tour automatically continues after 5 sec
+        self.play_tour(interval=5)  # Tour automatically continues after 5 sec
 
         self.open("https://www.google.com/maps/@42.3598616,-71.0912631,15z")
         self.wait_for_element('input#searchboxinput')
 
-        self.create_tour(theme="dark")
+        # Create a website tour using the IntroJS library
+        # Same as:  self.create_introjs_tour()
+        self.create_tour(theme="introjs")
         self.add_tour_step(
             "Welcome to Google Maps!")
         self.add_tour_step(
@@ -45,15 +54,14 @@ def test_google_tour(self):
             "#searchbox-searchbutton", alignment="bottom")
         self.add_tour_step(
             "Or click here to get driving directions.",
-            "#searchbox-directions", alignment="bottom", theme="square-dark")
+            "#searchbox-directions", alignment="bottom")
         self.add_tour_step(
             "Use this button to switch to Satellite view.",
             "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", theme="default")
+            "Or click here to zoom out.", "#widget-zoom-out", alignment="left")
         self.add_tour_step(
             "Use the Menu button to see more options.",
             ".searchbox-hamburger-container", alignment="right")
@@ -62,5 +70,5 @@ def test_google_tour(self):
             alignment="left")
         self.add_tour_step(
             "Thanks for trying out SeleniumBase Tours!",
-            title="End of Guided Tour", theme="light")
-        self.play_tour()  # If interval isn't set, tour is fully manual
+            title="End of Guided Tour")
+        self.play_tour()

examples/tour_examples/introjs_google_tour.py

@@ -0,0 +1,65 @@
+from seleniumbase import BaseCase
+
+
+class MyTourClass(BaseCase):
+
+    def test_google_tour(self):
+        self.open('https://google.com')
+        self.wait_for_element('input[title="Search"]')
+
+        self.create_introjs_tour()  # OR self.create_tour(theme="introjs")
+        self.add_tour_step(
+            "Click to begin the Google Tour!", title="SeleniumBase Tours")
+        self.add_tour_step(
+            "Type in your search query here.", 'input[title="Search"]')
+        self.play_tour()
+
+        self.highlight_update_text('input[title="Search"]', "Google")
+        self.wait_for_element('[role="listbox"]')  # Wait for autocomplete
+
+        self.create_introjs_tour()
+        self.add_tour_step(
+            "Then click here to search.", 'input[value="Google Search"]')
+        self.add_tour_step(
+            "Or press [ENTER] after typing a query here.", '[title="Search"]')
+        self.play_tour()
+
+        self.highlight_update_text('input[title="Search"]', "GitHub\n")
+        self.wait_for_element("#search")
+
+        self.create_introjs_tour()
+        self.add_tour_step(
+            "Search results appear here!", title="(5-second autoplay on)")
+        self.add_tour_step("Let's take another tour:")
+        self.play_tour(interval=5)  # Tour automatically continues after 5 sec
+
+        self.open("https://www.google.com/maps/@42.3598616,-71.0912631,15z")
+        self.wait_for_element('input#searchboxinput')
+
+        self.create_introjs_tour()
+        self.add_tour_step("Welcome to Google Maps!")
+        self.add_tour_step(
+            "Type in a location here.", "#searchboxinput", title="Search Box")
+        self.add_tour_step(
+            "Then click here to show 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 switch to Satellite view.",
+            "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 to see 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 trying out SeleniumBase Tours!",
+            title="End of Guided Tour")
+        self.play_tour()

examples/tour_examples/shepherd_google_tour.py

@@ -0,0 +1,67 @@
+from seleniumbase import BaseCase
+
+
+class MyTourClass(BaseCase):
+
+    def test_google_tour(self):
+        self.open('https://google.com')
+        self.wait_for_element('input[title="Search"]')
+
+        self.create_shepherd_tour(theme="dark")
+        self.add_tour_step(
+            "Click to begin the Google Tour!", title="SeleniumBase Tours")
+        self.add_tour_step(
+            "Type in your search query here.", 'input[title="Search"]')
+        self.play_tour()
+
+        self.highlight_update_text('input[title="Search"]', "Google")
+        self.wait_for_element('[role="listbox"]')  # Wait for autocomplete
+
+        self.create_shepherd_tour(theme="light")
+        self.add_tour_step(
+            "Then click here to search.", 'input[value="Google Search"]')
+        self.add_tour_step(
+            "Or press [ENTER] after typing a query here.", '[title="Search"]')
+        self.play_tour()
+
+        self.highlight_update_text('input[title="Search"]', "GitHub\n")
+        self.wait_for_element("#search")
+
+        self.create_shepherd_tour(theme="dark")
+        self.add_tour_step(
+            "Search results appear here!", title="(5-second autoplay on)")
+        self.add_tour_step("Let's take another tour:", theme="light")
+        self.play_tour(interval=5)  # Tour automatically continues after 5 sec
+
+        self.open("https://www.google.com/maps/@42.3598616,-71.0912631,15z")
+        self.wait_for_element('input#searchboxinput')
+
+        self.create_shepherd_tour(theme="dark")
+        self.add_tour_step(
+            "Welcome to Google Maps!")
+        self.add_tour_step(
+            "Type in a location here.", "#searchboxinput", title="Search Box")
+        self.add_tour_step(
+            "Then click here to show it on the map.",
+            "#searchbox-searchbutton", alignment="bottom")
+        self.add_tour_step(
+            "Or click here to get driving directions.",
+            "#searchbox-directions", alignment="bottom", theme="dark")
+        self.add_tour_step(
+            "Use this button to switch to Satellite view.",
+            "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", theme="light")
+        self.add_tour_step(
+            "Use the Menu button to see 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 trying out SeleniumBase Tours!",
+            title="End of Guided Tour", theme="light")
+        self.play_tour()

requirements.txt

@@ -2,20 +2,20 @@ pip
 ipython
 setuptools
 selenium==3.14.1
-pytest>=3.8.1
+pytest>=3.8.2
 pytest-cov>=2.6.0
 pytest-html>=1.19.0
 pytest-rerunfailures>=4.1
-pytest-xdist>=1.23.0
+pytest-xdist>=1.23.2
 parameterized==0.6.1
 six>=1.11.0
 pyotp>=2.2.6
 requests>=2.19.1
-beautifulsoup4==4.6.3
-unittest2==1.1.0
+beautifulsoup4>=4.6.3
+unittest2>=1.1.0
 chardet>=3.0.4
-urllib3==1.23
-boto==2.48.0
+urllib3>=1.23
+boto>=2.49.0
 nose==1.3.7
 ipdb==0.11
 flake8==3.5.0