Merge pull request #565 from seleniumbase/add-the-translator

Add the SeleniumBase Universal Translator API

Author: mdmintz

CHANGELOG.md

@@ -0,0 +1,3 @@
+## <img src="https://cdn2.hubspot.net/hubfs/100006/images/super_square_logo_3.png" title="SeleniumBase" height="32"> CHANGELOG
+
+### See: [SeleniumBase/releases](https://github.com/seleniumbase/SeleniumBase/releases)

README.md

@@ -1,12 +1,13 @@
-[<img src="https://cdn2.hubspot.net/hubfs/100006/images/sb_logo_dh.png" title="SeleniumBase" align="center" height="155">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
+<h3 align="center"><a href="https://github.com/seleniumbase/SeleniumBase/blob/master/README.md"><img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_sb.png" alt="SeleniumBase" height="48" /></a></h3>
 
-## Running Example Tests
+## <img src="https://cdn2.hubspot.net/hubfs/100006/images/super_square_logo_3.png" title="SeleniumBase" height="32"> **Running Example Tests:**
 
-SeleniumBase tests can be run with either **``pytest``** or **``nosetests``**, but using pytest is strongly recommended. Chrome is the default browser if not specified.
+SeleniumBase tests are run with **``pytest``** or **``nosetests``**. (<i>Using pytest is recommended.</i>) ``Chrome`` is the default browser if not specified. During test failures, logs and screenshots from the most recent test run are saved to the ``latest_logs/`` folder.
 
-During test failures, logs and screenshots from the most recent test run will get saved to the ``latest_logs/`` folder. Those logs will get moved to ``archived_logs/`` if you have ARCHIVE_EXISTING_LOGS set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py)
+(NOTE: Some example tests in this folder fail on purpose to demonstrate [logging features](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/example_logs/ReadMe.md).)
 
-(NOTE: Many tests in this folder fail on purpose to demonstrate the built-in logging, screenshots, and reporting features.)
+<a href="https://github.com/seleniumbase/SeleniumBase">
+<img src="https://img.shields.io/badge/tested%20with-SeleniumBase-04C38E.svg" alt="Tested with SeleniumBase" /></a>
 
 **Here are some example run commands to help get you started:**
 
@@ -24,13 +25,19 @@ Run an example test in Demo Mode: (highlight assertions)
 ```bash
 pytest my_first_test.py --demo
 ```
-<img src="https://cdn2.hubspot.net/hubfs/100006/images/my_first_test_gif.gif" title="SeleniumBase"><br />
+<img src="https://cdn2.hubspot.net/hubfs/100006/images/my_first_test_gif.gif" title="SeleniumBase Demo Mode" /><br />
 
 Run an example test in Headless Mode: (invisible browser)
 ```bash
 pytest my_first_test.py --headless
 ```
 
+Run an example test using Chrome's mobile device emulator: (default settings)
+```bash
+pytest test_swag_labs.py --mobile
+```
+<img src="https://cdn2.hubspot.net/hubfs/100006/images/swag_mobile.gif" title="SeleniumBase Mobile Mode" /><br />
+
 Run tests with verbose output: (includes more details)
 ```bash
 pytest test_suite.py -v
@@ -56,11 +63,6 @@ Run a failing test: (See the ``latest_logs/`` folder for logs and screenshots)
 pytest test_fail.py
 ```
 
-Run an example test using Chrome's mobile device emulator: (default settings)
-```bash
-pytest test_swag_labs.py --mobile
-```
-
 Run a failing test with Debug-mode enabled: (``pdb`` activates on failures)
 ```bash
 pytest test_fail.py --pdb -s
@@ -105,8 +107,8 @@ To make things easier, here's a simple GUI program that allows you to run a few
 ```bash
 python gui_test_runner.py
 ```
-<img src="https://cdn2.hubspot.net/hubfs/100006/images/gui_test_runner_py.png" title="GUI Test Runner" height="260">
+<img src="https://cdn2.hubspot.net/hubfs/100006/images/gui_test_runner_py.png" title="GUI Test Runner" height="260" />
 
 --------
 
-[<img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_e.png" title="SeleniumBase" height="48">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
+<img src="https://cdn2.hubspot.net/hubfs/100006/images/SeleniumBaseText_F.png" title="SeleniumBase" height="45" />

examples/ReadMe.md

@@ -1,6 +1,6 @@
-#### Logging, Screenshots, and Reports examples
+### <img src="https://cdn2.hubspot.net/hubfs/100006/images/super_square_logo_3a.png" title="SeleniumBase" height="32"> **Logging, Screenshots, and Reports:**
 
-Log files in [example_logs/](https://github.com/seleniumbase/SeleniumBase/tree/master/examples/example_logs) were generated when [test_fail.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_fail.py) ran and failed. By default, logs are saved to ``latest_logs/``. If ARCHIVE_EXISTING_LOGS is set to True in [settings.py](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/config/settings.py), past logs get saved to ``archived_logs/``.
+Log files in [example_logs/](https://github.com/seleniumbase/SeleniumBase/tree/master/examples/example_logs) were generated when [test_fail.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/test_fail.py) ran and failed. During test failures, logs and screenshots get saved to the ``latest_logs/`` folder. If ``--archive-logs`` is set, test logs will get archived to the ``archived_logs/`` folder.
 
 ```bash
 pytest test_fail.py --browser=chrome

examples/example_logs/ReadMe.md

@@ -1,6 +1,6 @@
 ![](http://cdn2.hubspot.net/hubfs/100006/images/masterqa_logo-11.png "MasterQA")
 
-### MasterQA combines SeleniumBase automation with manual verification steps to bridge the gap between manual QA and automated QA.
+### MasterQA combines automation with manual verification steps.
 
 ![](https://cdn2.hubspot.net/hubfs/100006/images/masterqa6.gif "MasterQA")
 
@@ -15,9 +15,9 @@ self.highlight_update_text("input#s", "Dragons\n")
 self.verify('Do you see "dragons" in the search results?')
 ```
 
-After the web browser performs various automated actions, a pop-up window will ask the user questions for each verification command.
+After each automation checkpoint, a pop-up window will ask the user questions for each verification command.
 
-At the end of a full test run, as seen from [this longer example](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/master_qa/masterqa_test.py), you'll see a results page that appears after responding to all the verification questions. (Failed verifications generate links to screenshots and log files.)
+When the test run completes, as seen from [this longer example](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/master_qa/masterqa_test.py), you'll reach the results page that appears after answering all the verification questions. (Failed verifications generate links to screenshots and log files.)
 
 ![](http://cdn2.hubspot.net/hubfs/100006/images/hybrid_screen.png "MasterQA")
 
@@ -38,9 +38,9 @@ At the end of your test run, you'll receive a report with results, screenshots,
 
 ### Check out [masterqa_test.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/master_qa/masterqa_test.py) to learn how to write your own MasterQA tests:
 
-You'll notice that tests are written based on [SeleniumBase](http://seleniumbase.com), with the key difference of using a different import: ``from seleniumbase import MasterQA`` rather than ``from seleniumbase import BaseCase``. Now the test class will import ``MasterQA`` instead of ``BaseCase``.
+You'll notice that tests are written the same way as regular [SeleniumBase](http://seleniumbase.com) tests, with the key difference being a different import: ``from seleniumbase import MasterQA`` rather than ``from seleniumbase import BaseCase``. Now your Python test class will import ``MasterQA`` instead of ``BaseCase``.
 
-To add a manual verification step, use ``self.verify()`` in the code after each part of the script that needs manual verification. If you want to include a custom question, add text inside that call (in quotes). Example:
+To add a manual verification step, use ``self.verify()`` in the code after each part of your test that needs a manual verification step. If you want to include a custom question, add text inside that call (in quotes). Example:
 
 ```python
 self.verify()

examples/master_qa/ReadMe.md

@@ -5,12 +5,12 @@
 
 class SwagLabsTests(BaseCase):
 
-    def login(self, user="standard_user"):
-        """ Login to Swag Labs and assert that the login was successful. """
-        if user not in (["standard_user", "problem_user"]):
-            raise Exception("Invalid user!")
+    def login(self, username="standard_user"):
+        """ Login to Swag Labs and verify that login was successful. """
         self.open("https://www.saucedemo.com/")
-        self.update_text("#user-name", user)
+        if username not in self.get_text("#login_credentials"):
+            self.fail("Invalid user for login: %s" % username)
+        self.update_text("#user-name", username)
         self.update_text("#password", "secret_sauce")
         self.click('input[type="submit"]')
         self.assert_element("#inventory_container")
@@ -21,11 +21,10 @@ def login(self, user="standard_user"):
         ["problem_user"],
     ])
     @pytest.mark.run(order=1)
-    def test_swag_labs_basic_functional_flow(self, user):
-        """ This test checks for basic functional flow in the Swag Labs store.
-            The test is parameterized, and receives the user to use for login.
-        """
-        self.login(user)
+    def test_swag_labs_basic_functional_flow(self, username):
+        """ This test checks functional flow of the Swag Labs store.
+            This test is parameterized, and receives the user for login. """
+        self.login(username=username)
 
         # Verify that the "Test.allTheThings() T-Shirt" appears on the page
         item_name = "Test.allTheThings() T-Shirt"
@@ -34,7 +33,7 @@ def test_swag_labs_basic_functional_flow(self, user):
         # Verify that a reverse-alphabetical sort works as expected
         self.select_option_by_value("select.product_sort_container", "za")
         if item_name not in self.get_text("div.inventory_item"):
-            raise Exception('Sort Failed! Expecting "%s" on top!' % item_name)
+            self.fail('Sort Failed! Expecting "%s" on top!' % item_name)
 
         # Add the "Test.allTheThings() T-Shirt" to the cart
         self.assert_exact_text("ADD TO CART", "button.btn_inventory")
@@ -49,7 +48,11 @@ def test_swag_labs_basic_functional_flow(self, user):
         self.assert_text(item_name, "div.inventory_item_name")
         self.assert_exact_text("1", "div.cart_quantity")
         self.assert_exact_text("REMOVE", "button.cart_button")
-        self.assert_element("link=CONTINUE SHOPPING")
+        continue_shopping_button = "link=CONTINUE SHOPPING"
+        if self.browser == "safari":
+            # Safari sees this element differently
+            continue_shopping_button = "link=Continue Shopping"
+        self.assert_element(continue_shopping_button)
 
         # Checkout - Add info
         self.click("link=CHECKOUT")
@@ -67,23 +70,22 @@ def test_swag_labs_basic_functional_flow(self, user):
         self.assert_text(item_price, "div.inventory_item_price")
         self.assert_exact_text("1", "div.summary_quantity")
 
-        # Finish Checkout and verify item is no longer in cart
+        # Finish Checkout and verify the item was removed from the cart
         self.click("link=FINISH")
         self.assert_exact_text("THANK YOU FOR YOUR ORDER", "h2")
         self.assert_element("div.pony_express")
         self.click("#shopping_cart_container path")
         self.assert_element_absent("div.inventory_item_name")
-        self.click("link=CONTINUE SHOPPING")
+        self.click(continue_shopping_button)
         self.assert_element_absent("span.shopping_cart_badge")
 
     @parameterized.expand([
         ["standard_user"],
         ["problem_user"],
     ])
     @pytest.mark.run(order=2)
-    def test_swag_labs_products_page_resource_verification(self, user):
+    def test_swag_labs_products_page_resource_verification(self, username):
         """ This test checks for 404 errors on the Swag Labs products page.
-            The test is parameterized, and receives the user to use for login.
-        """
-        self.login(user)
+            This test is parameterized, and receives the user for login. """
+        self.login(username=username)
         self.assert_no_404_errors()

examples/swag_labs_suite.py

@@ -3,20 +3,20 @@
 
 class SwagLabsTests(BaseCase):
 
-    def login(self, user="standard_user"):
-        """ Login to Swag Labs and assert that the login was successful. """
-        if user not in (["standard_user", "problem_user"]):
-            raise Exception("Invalid user!")
+    def login(self, username="standard_user"):
+        """ Login to Swag Labs and verify that login was successful. """
         self.open("https://www.saucedemo.com/")
-        self.update_text("#user-name", user)
+        if username not in self.get_text("#login_credentials"):
+            self.fail("Invalid user for login: %s" % username)
+        self.update_text("#user-name", username)
         self.update_text("#password", "secret_sauce")
         self.click('input[type="submit"]')
         self.assert_element("#inventory_container")
         self.assert_text("Products", "div.product_label")
 
     def test_swag_labs_basic_flow(self):
-        """ This test checks basic functional flow in the Swag Labs store. """
-        self.login()
+        """ This test checks functional flow of the Swag Labs store. """
+        self.login(username="standard_user")
 
         # Verify that the "Test.allTheThings() T-Shirt" appears on the page
         item_name = "Test.allTheThings() T-Shirt"
@@ -25,7 +25,7 @@ def test_swag_labs_basic_flow(self):
         # Verify that a reverse-alphabetical sort works as expected
         self.select_option_by_value("select.product_sort_container", "za")
         if item_name not in self.get_text("div.inventory_item"):
-            raise Exception('Sort Failed! Expecting "%s" on top!' % item_name)
+            self.fail('Sort Failed! Expecting "%s" on top!' % item_name)
 
         # Add the "Test.allTheThings() T-Shirt" to the cart
         self.assert_exact_text("ADD TO CART", "button.btn_inventory")
@@ -40,7 +40,11 @@ def test_swag_labs_basic_flow(self):
         self.assert_text(item_name, "div.inventory_item_name")
         self.assert_exact_text("1", "div.cart_quantity")
         self.assert_exact_text("REMOVE", "button.cart_button")
-        self.assert_element("link=CONTINUE SHOPPING")
+        continue_shopping_button = "link=CONTINUE SHOPPING"
+        if self.browser == "safari":
+            # Safari sees this element differently
+            continue_shopping_button = "link=Continue Shopping"
+        self.assert_element(continue_shopping_button)
 
         # Checkout - Add info
         self.click("link=CHECKOUT")
@@ -64,5 +68,5 @@ def test_swag_labs_basic_flow(self):
         self.assert_element("div.pony_express")
         self.click("#shopping_cart_container path")
         self.assert_element_absent("div.inventory_item_name")
-        self.click("link=CONTINUE SHOPPING")
+        self.click(continue_shopping_button)
         self.assert_element_absent("span.shopping_cart_badge")

examples/test_swag_labs.py

@@ -1,6 +1,8 @@
-## SeleniumBase Website Tours
+<h3 align="left"><img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_sb23.png" alt="SeleniumBase" height="48" /></h3>
 
-SeleniumBase Tours utilize your choice of 4 JavaScript libraries for prototyping 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/)**.
+## 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/)**.
 
 **Example tour:**
 

examples/tour_examples/ReadMe.md

@@ -1,4 +1,62 @@
-[<img src="https://cdn2.hubspot.net/hubfs/100006/images/SeleniumBaseText_F.png" title="SeleniumBase" align="center" height="38">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
-### Multi-Language Tests
+<h3 align="left"><a href="https://github.com/seleniumbase/SeleniumBase/blob/master/README.md"><img src="https://cdn2.hubspot.net/hubfs/100006/images/super_logo_m.png" title="SeleniumBase" height="48" /></a></h3>
 
-#### (Python 3 Only!)
+### <img src="https://cdn2.hubspot.net/hubfs/100006/images/super_square_logo_3.png" title="SeleniumBase" height="32"> Multi-Language Tests (Python 3 Only!)
+
+**SeleniumBase** supports the following 10 languages:
+* English
+* Chinese / 中文
+* Dutch / Nederlands
+* French / Français
+* Italian / Italiano
+* Japanese / 日本語
+* Korean / 한국어
+* Portuguese / Português
+* Russian / Русский
+* Spanish / Español
+
+Multi-language tests are run with **pytest** like any other test. Every test method has a one-to-one mapping to every other supported language. Example:
+ ``self.open(URL)`` = ``self.开启网址(URL)``
+
+--------
+
+You can use SeleniumBase to translate any test from one language to another by using the console scripts interface:
+
+```bash
+seleniumbase translate
+```
+
+```
+* Usage:
+seleniumbase translate [SB_FILE].py [LANGUAGE] [ACTION]
+
+* Languages:
+``--en`` / ``--English``  |  ``--zh`` / ``--Chinese``
+``--nl`` / ``--Dutch``    |  ``--fr`` / ``--French``
+``--it`` / ``--Italian``  |  ``--ja`` / ``--Japanese``
+``--ko`` / ``--Korean``   |  ``--pt`` / ``--Portuguese``
+``--ru`` / ``--Russian``  |  ``--es`` / ``--Spanish``
+
+* Actions:
+``-p`` / ``--print``  (Print translation output to the screen)
+``-o`` / ``--overwrite``  (Overwrite the file being translated)
+``-c`` / ``--copy``  (Copy the translation to a new ``.py`` file)
+
+* Examples:
+Translate test_1.py into Chinese and only print the output:
+>>> seleniumbase translate test_1.py --zh  -p
+Translate test_2.py into Portuguese and overwrite the file:
+>>> seleniumbase translate test_2.py --pt  -o
+Translate test_3.py into Dutch and make a copy of the file:
+>>> seleniumbase translate test_3.py --nl  -c
+
+* Output:
+Translates a SeleniumBase Python file into the language
+specified. Method calls and ``import`` lines get swapped.
+Both a language and an action must be specified.
+The ``-p`` action can be paired with one other action.
+When running with ``-c`` (or ``--copy``) the new file name
+will be the orginal name appended with an underscore
+plus the 2-letter language code of the new language.
+(Example: Translating ``test_1.py`` into Japanese with
+``-c`` will create a new file called ``test_1_ja.py``.)
+```

examples/translations/ReadMe.md

@@ -1,8 +1,8 @@
-[<img src="https://cdn2.hubspot.net/hubfs/100006/images/SeleniumBaseText_F.png" title="SeleniumBase" align="center" height="38">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
-### Automated Visual Regression Testing
+[<img src="https://cdn2.hubspot.net/hubfs/100006/images/sb_logo_f6.png" title="SeleniumBase" align="center" height="120">](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)
 
-[![Automated Visual Regression Testing](http://img.youtube.com/vi/erwkoiDeNzA/3.jpg)](https://www.youtube.com/watch?v=erwkoiDeNzA "Automated Visual Regression Testing")
+## <img src="https://cdn2.hubspot.net/hubfs/100006/images/super_square_logo_3a.png" title="SeleniumBase" height="32"> Automated Visual Regression Testing
 
+[<img src="http://img.youtube.com/vi/erwkoiDeNzA/0.jpg" title="Automated Visual Regression Testing" height="180">](https://www.youtube.com/watch?v=erwkoiDeNzA)
 (**[Watch the tutorial on YouTube](https://www.youtube.com/watch?v=erwkoiDeNzA)**)
 
 Automated Visual Regression Testing helps you detect when the layout of a web page has changed. Rather than comparing screenshots, layout differences are detected by comparing HTML tags and attributes with a baseline. If a change is detected, it could mean that something broke, the web page was redesigned, or dynamic content changed.