Dialog Boxes and more

README.md

@@ -41,8 +41,8 @@
 <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/tour_examples/ReadMe.md">🗺️ Tours</a> |
 <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/chart_maker/ReadMe.md">📶 Charts</a> |
 <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/presenter/ReadMe.md">📰 Present</a> |
-<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/visual_testing/ReadMe.md">🖼️ VisualTest</a> |
-<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/master_qa/ReadMe.md">🛂 MasterQA</a>
+<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/dialog_boxes/ReadMe.md">🛂 DialogBox</a> |
+<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/visual_testing/ReadMe.md">🖼️ VisualTest</a>
 </p>
 
 <p align="left">
@@ -268,7 +268,7 @@ nosetests [FILE_NAME.py]:[CLASS_NAME].[METHOD_NAME]
 <img src="https://img.shields.io/badge/Flaky Tests%3F-%20NO%21-11BBDD.svg" alt="NO MORE FLAKY TESTS!" />
 
 ✅ Automated/Manual Hybrid Mode:
-<p>SeleniumBase includes a solution called <b><a href="https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/masterqa/ReadMe.md">MasterQA</a></b>, which speeds up manual testing by having automation perform all the browser actions while the manual tester handles validation.</p>
+<p>SeleniumBase includes a solution called <b><a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/master_qa/ReadMe.md">MasterQA</a></b>, which speeds up manual testing by having automation perform all the browser actions while the manual tester handles validation.</p>
 
 ✅ Feature-Rich:
 <p>For a full list of SeleniumBase features, <a href="https://github.com/seleniumbase/SeleniumBase/blob/master/help_docs/features_list.md">Click Here</a>.</p>

examples/dialog_boxes/ReadMe.md

@@ -0,0 +1,180 @@
+<h3 align="left"><img src="https://seleniumbase.io/cdn/img/sb_logo_b.png" alt="SeleniumBase" width="320" /></h3>
+
+<h2><img src="https://seleniumbase.io/img/logo6.png" title="SeleniumBase" width="32" /> 🛂 Dialog Boxes 🛂</h2>
+
+SeleniumBase Dialog Boxes let your users provide input in the middle of automation scripts.
+
+* This feature utilizes the [jquery-confirm](https://craftpip.github.io/jquery-confirm/) library.
+* A Python API is used to call the JavaScript API.
+
+<img src="https://seleniumbase.io/cdn/img/emoji_sports_dialog.png" alt="SeleniumBase" width="440" />
+
+<h4>↕️ (<a href="https://github.com/seleniumbase/SeleniumBase/blob/master/examples/dialog_boxes/dialog_box_tour.py">Example: dialog_box_tour.py</a>) ↕️</h4>
+
+<img src="https://seleniumbase.io/cdn/gif/sports_dialog.gif" alt="SeleniumBase" width="440" />
+
+<h4>Here's how to run that example:</h4>
+
+```bash
+cd examples/dialog_boxes
+pytest test_dialog_boxes.py
+```
+
+<h4>Here's a code snippet from that:</h4>
+
+```python
+self.open("https://xkcd.com/1920/")
+skip_button = ["SKIP", "red"]  # Can be a [text, color] list or tuple.
+buttons = ["Fencing", "Football", "Metaball", "Go/Chess", skip_button]
+message = "Choose a sport:"
+choice = self.get_jqc_button_input(message, buttons)
+if choice == "Fencing":
+    self.open("https://xkcd.com/1424/")
+```
+
+* You can create forms that include buttons and input fields.
+
+<h4>Here's a simple form with only buttons as input:</h4>
+
+```python
+choice = self.get_jqc_button_input("Ready?", ["YES", "NO"])
+print(choice)  # This prints "YES" or "NO"
+
+# You may want to customize the color of buttons:
+buttons = [("YES", "green"), ("NO", "red")]
+choice = self.get_jqc_button_input("Ready?", buttons)
+```
+
+<h4>Here's a simple form with an input field:</h4>
+
+```python
+text = self.get_jqc_text_input("Enter text:", ["Search"])
+print(text)  # This prints the text entered
+```
+
+<h4>This form has an input field and buttons:</h4>
+
+```python
+message = "Type your name and choose a language:"
+buttons = ["Python", "JavaScript"]
+text, choice = self.get_jqc_form_inputs(message, buttons)
+print("Your name is: %s" % text)
+print("You picked %s!" % choice)
+```
+
+<h4>You can customize options if you want:</h4>
+
+```python
+# Themes: bootstrap, modern, material, supervan, light, dark, seamless
+options = [("theme", "modern"), ("width", "50%")]
+self.get_jqc_text_input("You Won!", ["OK"], options)
+```
+
+<h4>Default options can be set with <code>set_jqc_theme()</code>:</h4>
+
+```python
+self.set_jqc_theme("light", color="green", width="38%")
+
+# To reset jqc theme settings to factory defaults:
+self.reset_jqc_theme()
+```
+
+<h3>All methods for Dialog Boxes:</h3>
+
+```python
+self.get_jqc_button_input(message, buttons, options=None)
+
+self.get_jqc_text_input(message, button=None, options=None)
+
+self.get_jqc_form_inputs(message, buttons, options=None)
+
+self.set_jqc_theme(theme, color=None, width=None)
+
+self.reset_jqc_theme()
+
+self.activate_jquery_confirm()  # Automatic for jqc methods
+```
+
+<h3>Detailed method summaries for Dialog Boxes:</h3>
+
+```python
+self.get_jqc_button_input(message, buttons, options=None)
+"""
+Pop up a jquery-confirm box and return the text of the button clicked.
+If running in headless mode, the last button text is returned.
+@Params
+message: The message to display in the jquery-confirm dialog.
+buttons: A list of tuples for text and color.
+    Example: [("Yes!", "green"), ("No!", "red")]
+    Available colors: blue, green, red, orange, purple, default, dark.
+    A simple text string also works: "My Button". (Uses default color.)
+options: A list of tuples for options to set.
+    Example: [("theme", "bootstrap"), ("width", "450px")]
+    Available theme options: bootstrap, modern, material, supervan,
+                             light, dark, and seamless.
+    Available colors: (For the BORDER color, NOT the button color.)
+        "blue", "default", "green", "red", "purple", "orange", "dark".
+    Example option for changing the border color: ("color", "default")
+    Width can be set using percent or pixels. Eg: "36.0%", "450px".
+"""
+
+self.get_jqc_text_input(message, button=None, options=None)
+"""
+Pop up a jquery-confirm box and return the text submitted by the input.
+If running in headless mode, the text returned is "" by default.
+@Params
+message: The message to display in the jquery-confirm dialog.
+button: A 2-item list or tuple for text and color. Or just the text.
+    Example: ["Submit", "blue"] -> (default button if not specified)
+    Available colors: blue, green, red, orange, purple, default, dark.
+    A simple text string also works: "My Button". (Uses default color.)
+options: A list of tuples for options to set.
+    Example: [("theme", "bootstrap"), ("width", "450px")]
+    Available theme options: bootstrap, modern, material, supervan,
+                             light, dark, and seamless.
+    Available colors: (For the BORDER color, NOT the button color.)
+        "blue", "default", "green", "red", "purple", "orange", "dark".
+    Example option for changing the border color: ("color", "default")
+    Width can be set using percent or pixels. Eg: "36.0%", "450px".
+"""
+
+self.get_jqc_form_inputs(message, buttons, options=None)
+"""
+Pop up a jquery-confirm box and return the input/button texts as tuple.
+If running in headless mode, returns the ("", buttons[-1][0]) tuple.
+@Params
+message: The message to display in the jquery-confirm dialog.
+buttons: A list of tuples for text and color.
+    Example: [("Yes!", "green"), ("No!", "red")]
+    Available colors: blue, green, red, orange, purple, default, dark.
+    A simple text string also works: "My Button". (Uses default color.)
+options: A list of tuples for options to set.
+    Example: [("theme", "bootstrap"), ("width", "450px")]
+    Available theme options: bootstrap, modern, material, supervan,
+                             light, dark, and seamless.
+    Available colors: (For the BORDER color, NOT the button color.)
+        "blue", "default", "green", "red", "purple", "orange", "dark".
+    Example option for changing the border color: ("color", "default")
+    Width can be set using percent or pixels. Eg: "36.0%", "450px".
+"""
+
+self.set_jqc_theme(theme, color=None, width=None)
+""" Sets the default jquery-confirm theme and width (optional).
+Available themes: "bootstrap", "modern", "material", "supervan",
+                  "light", "dark", and "seamless".
+Available colors: (This sets the BORDER color, NOT the button color.)
+    "blue", "default", "green", "red", "purple", "orange", "dark".
+Width can be set using percent or pixels. Eg: "36.0%", "450px".
+"""
+
+self.reset_jqc_theme()
+""" Resets the jqc theme settings to factory defaults. """
+
+self.activate_jquery_confirm()  # Automatic for jqc methods
+""" See https://craftpip.github.io/jquery-confirm/ for usage. """
+```
+
+--------
+
+<h4>✅ 🛂 Automated/Manual Hybrid Mode (MasterQA)</h4>
+<p><b><a href="https://seleniumbase.io/seleniumbase/masterqa/ReadMe/">MasterQA</a></b> uses <b>SeleniumBase Dialog Boxes</b> to speed up manual testing by having automation perform all the browser actions while the manual tester handles validation. See <a href="https://github.com/seleniumbase/SeleniumBase/tree/master/examples/master_qa">the MasterQA GitHub page</a> for examples.</p>

examples/dialog_boxes/dialog_box_tour.py

@@ -0,0 +1,117 @@
+from seleniumbase import BaseCase
+
+
+class DialogBoxTests(BaseCase):
+    def test_dialog_boxes(self):
+        self.open("https://xkcd.com/1920/")
+        self.assert_element('img[alt="Emoji Sports"]')
+        self.highlight("#comic img")
+
+        skip_button = ["SKIP", "red"]  # Can be a [text, color] list or tuple.
+        buttons = ["Fencing", "Football", "Metaball", "Go/Chess", skip_button]
+        message = "Choose a sport:"
+        choice = None
+        while choice != "STOP":
+            choice = self.get_jqc_button_input(message, buttons)
+            if choice == "Fencing":
+                self.open("https://xkcd.com/1424/")
+                buttons.remove("Fencing")
+            elif choice == "Football":
+                self.open("https://xkcd.com/1107/")
+                buttons.remove("Football")
+            elif choice == "Metaball":
+                self.open("https://xkcd.com/1507/")
+                buttons.remove("Metaball")
+            elif choice == "Go/Chess":
+                self.open("https://xkcd.com/1287/")
+                buttons.remove("Go/Chess")
+            else:
+                break
+            self.highlight("#comic img")
+            if len(buttons) == 2:
+                message = "One Sport Remaining:"
+            if len(buttons) == 1:
+                message = "Part One Complete. You saw all 4 sports!"
+                btn_text_1 = "NEXT Tutorial Please!"
+                btn_text_2 = "WAIT, Go/Chess is a sport?"
+                buttons = [(btn_text_1, "green"), (btn_text_2, "purple")]
+                choice_2 = self.get_jqc_button_input(message, buttons)
+                if choice_2 == btn_text_2:
+                    self.open("https://xkcd.com/1287/")
+                    message = "Brain sports count as sports!<br /><br />"
+                    message += "Are you ready for more?"
+                    self.get_jqc_button_input(message, ["Let's Go!"])
+                break
+
+        self.open("https://xkcd.com/1117/")
+        sb_banner_logo = "//seleniumbase.io/cdn/img/sb_logo_cs.png"
+        self.set_attributes("#news img", "src", sb_banner_logo)
+        options = [("theme", "material"), ("width", "52%")]
+        message = 'With one button, you can press "Enter/Return", "Y", or "1".'
+        self.get_jqc_button_input(message, ["OK"], options)
+
+        self.open("https://xkcd.com/556/")
+        self.set_attributes("#news img", "src", sb_banner_logo)
+        options = [("theme", "bootstrap"), ("width", "52%")]
+        message = 'If the lowercase button text is "yes" or "no", '
+        message += '<br><br>you can use the "Y" or "N" keys as shortcuts. '
+        message += '<br><br><br>Other shortcuts include: <br><br>'
+        message += '"1": 1st button, "2": 2nd button, etc. Got it?'
+        buttons = [("YES", "green"), ("NO", "red")]
+        choice = self.get_jqc_button_input(message, buttons, options)
+
+        message = 'You said "%s"! <br><br>' % choice
+        if choice == "YES":
+            message += "Wonderful! Let's continue with the next example..."
+        else:
+            message += "You can learn more from SeleniumBase Docs..."
+        choice = self.get_jqc_button_input(message, ["OK"], options)
+
+        self.open("https://seleniumbase.io")
+        self.set_jqc_theme("light", color="green", width="38%")
+        message = "<b>This is the SeleniumBase Docs website!</b><br /><br />"
+        message += "What would you like to search for?<br />"
+        text = self.get_jqc_text_input(message, ["Search"])
+        self.update_text('input[aria-label="Search"]', text + "\n")
+        self.wait_for_ready_state_complete()
+        self.set_jqc_theme("bootstrap", color="red", width="32%")
+        if self.is_text_visible("No matching documents", ".md-search-result"):
+            self.get_jqc_button_input("Your search had no results!", ["OK"])
+        elif self.is_element_visible("a.md-search-result__link"):
+            self.click("a.md-search-result__link")
+            self.set_jqc_theme("bootstrap", color="green", width="32%")
+            self.get_jqc_button_input("You found search results!", ["OK"])
+        elif self.is_text_visible("Type to start searching", "div.md-search"):
+            self.get_jqc_button_input("You did not do a search!", ["OK"])
+        else:
+            self.get_jqc_button_input("We're not sure what happened.", ["OK"])
+
+        self.open("https://seleniumbase.io/help_docs/ReadMe/")
+        self.highlight("h1")
+        self.highlight_click('a:contains("Running Example Tests")')
+        self.highlight("h1")
+
+        self.set_jqc_theme("bootstrap", color="green", width="52%")
+        message = 'See the "SeleniumBase/examples" section for more info!'
+        self.get_jqc_button_input(message, ["OK"])
+
+        self.set_jqc_theme("bootstrap", color="purple", width="56%")
+        message = "Now let's combine form inputs with multiple button options!"
+        message += "<br /><br />"
+        message += "Pick something to search. Then pick the site to search on."
+        buttons = ["XKCD.com", "Wikipedia.org"]
+        text, choice = self.get_jqc_form_inputs(message, buttons)
+        if choice == "XKCD.com":
+            self.open("https://relevant-xkcd.github.io/")
+        else:
+            self.open("https://en.wikipedia.org/wiki/Main_Page")
+        self.highlight_update_text('input[name="search"]', text + "\n")
+        self.wait_for_ready_state_complete()
+        self.highlight("body")
+        self.reset_jqc_theme()
+        self.get_jqc_button_input("<b>Here are your results.</b>", ["OK"])
+        message = "<h3>You've reached the end of this tutorial!</h3><br />"
+        message += "Thanks for learning about SeleniumBase Dialog Boxes!<br />"
+        message += "<br />Check out the SeleniumBase page on GitHub for more!"
+        self.set_jqc_theme("modern", color="purple", width="56%")
+        self.get_jqc_button_input(message, ["Goodbye!"])

help_docs/ReadMe.md

@@ -5,35 +5,35 @@
 <p align="left">
 <a href="https://seleniumbase.io/#python_installation">🚀 Start</a> |
 <a href="https://seleniumbase.io/help_docs/customizing_test_runs/">🖥️ CLI</a> |
-<a href="https://seleniumbase.io/help_docs/features_list/">🗂️ Features</a>
+<a href="https://seleniumbase.io/help_docs/features_list/">🏰 Features</a>
 <br />
-<a href="https://seleniumbase.io/examples/ReadMe/">📖 Examples</a> |
+<a href="https://seleniumbase.io/examples/ReadMe/">👨‍🏫 Examples</a> |
 <a href="https://seleniumbase.io/help_docs/mobile_testing/">📱 Mobile</a>
 <br />
-<a href="https://seleniumbase.io/help_docs/syntax_formats/">🔡 Syntax Formats</a> |
+<a href="https://seleniumbase.io/help_docs/syntax_formats/">🔠 Syntax Formats</a> |
 <a href="https://seleniumbase.io/integrations/github/workflows/ReadMe/">🤖 CI</a>
 <br />
-<a href="https://seleniumbase.io/help_docs/method_summary/">📗 API</a> |
-<a href="https://seleniumbase.io/examples/example_logs/ReadMe/">📋 Reports</a> |
+<a href="https://seleniumbase.io/help_docs/method_summary/">📚 API</a> |
+<a href="https://seleniumbase.io/examples/example_logs/ReadMe/">📊 Reports</a> |
 <a href="https://seleniumbase.io/examples/tour_examples/ReadMe/">🗺️ Tours</a>
 <br />
-<a href="https://seleniumbase.io/seleniumbase/console_scripts/ReadMe/">💻 Console Scripts</a> |
+<a href="https://seleniumbase.io/seleniumbase/console_scripts/ReadMe/">🧙‍ Console Scripts</a> |
 <a href="https://seleniumbase.io/seleniumbase/utilities/selenium_grid/ReadMe/">🌐 Grid</a>
 <br />
 <a href="https://github.com/seleniumbase/SeleniumBase/tree/master/examples/boilerplates">♻️ Boilerplates</a> |
 <a href="https://seleniumbase.io/help_docs/locale_codes/">🗾 Locales</a>
 <br />
-<a href="https://seleniumbase.io/help_docs/js_package_manager/">🗄️ PkgManager</a> |
+<a href="https://seleniumbase.io/help_docs/js_package_manager/">🕹️ JSManager</a> |
 <a href="https://seleniumbase.io/examples/visual_testing/ReadMe/">🖼️ VisualTest</a>
 <br />
 <a href="https://seleniumbase.io/help_docs/translations/">🌏 Translate</a> |
-<a href="https://seleniumbase.io/examples/master_qa/ReadMe/">🛂 MasterQA</a>
+<a href="https://seleniumbase.io/examples/dialog_boxes/ReadMe/">🛂 DialogBoxes</a>
 <br />
 <a href="https://seleniumbase.io/seleniumbase/utilities/selenium_ide/ReadMe/">⏺️ Recorder</a> |
 <a href="https://github.com/seleniumbase/SeleniumBase/tree/master/integrations/node_js">🏃 NodeRunner</a>
 <br />
-<a href="https://seleniumbase.io/examples/presenter/ReadMe/">📑 Presenter</a> |
-<a href="https://seleniumbase.io/examples/chart_maker/ReadMe/">📊 ChartMaker</a>
+<a href="https://seleniumbase.io/examples/presenter/ReadMe/">📰 Presenter</a> |
+<a href="https://seleniumbase.io/examples/chart_maker/ReadMe/">📶 ChartMaker</a>
 </p>
 
 --------